]> git.sur5r.net Git - bacula/docs/commitdiff
Create Bacula Main Reference manual
authorKern Sibbald <kern@sibbald.com>
Tue, 3 Nov 2009 16:42:44 +0000 (17:42 +0100)
committerKern Sibbald <kern@sibbald.com>
Tue, 3 Nov 2009 16:42:44 +0000 (17:42 +0100)
64 files changed:
docs/.gitignore
docs/Makefile.in
docs/autoconf/configure.in
docs/configure
docs/manuals/en/main/Makefile.in [new file with mode: 0644]
docs/manuals/en/main/STYLE [new file with mode: 0644]
docs/manuals/en/main/ansi-labels.tex [new file with mode: 0644]
docs/manuals/en/main/autochangerres.tex [new file with mode: 0644]
docs/manuals/en/main/autochangers.tex [new file with mode: 0644]
docs/manuals/en/main/bimagemgr.bix [new file with mode: 0644]
docs/manuals/en/main/bootstrap.tex [new file with mode: 0644]
docs/manuals/en/main/bugs.tex [new file with mode: 0644]
docs/manuals/en/main/catmaintenance.tex [new file with mode: 0644]
docs/manuals/en/main/check_tex.pl [new file with mode: 0755]
docs/manuals/en/main/configure.tex [new file with mode: 0644]
docs/manuals/en/main/consoleconf.tex [new file with mode: 0644]
docs/manuals/en/main/coverpage.tex [new file with mode: 0644]
docs/manuals/en/main/critical.tex [new file with mode: 0644]
docs/manuals/en/main/dataencryption.tex [new file with mode: 0644]
docs/manuals/en/main/dirdconf.tex [new file with mode: 0644]
docs/manuals/en/main/disk.tex [new file with mode: 0644]
docs/manuals/en/main/do_echo [new file with mode: 0644]
docs/manuals/en/main/fdl.tex [new file with mode: 0644]
docs/manuals/en/main/filedconf.tex [new file with mode: 0644]
docs/manuals/en/main/fileset.tex [new file with mode: 0644]
docs/manuals/en/main/fix_tex.pl [new file with mode: 0755]
docs/manuals/en/main/general.tex [new file with mode: 0644]
docs/manuals/en/main/gpl.tex [new file with mode: 0644]
docs/manuals/en/main/index.perl [new file with mode: 0644]
docs/manuals/en/main/install.tex [new file with mode: 0644]
docs/manuals/en/main/latex2html-init.pl [new file with mode: 0644]
docs/manuals/en/main/lesser.tex [new file with mode: 0644]
docs/manuals/en/main/license.tex [new file with mode: 0644]
docs/manuals/en/main/main.kilepr [new file with mode: 0644]
docs/manuals/en/main/main.tex [new file with mode: 0644]
docs/manuals/en/main/messagesres.tex [new file with mode: 0644]
docs/manuals/en/main/migration.tex [new file with mode: 0644]
docs/manuals/en/main/monitorconf.tex [new file with mode: 0644]
docs/manuals/en/main/mtx-changer.txt [new file with mode: 0644]
docs/manuals/en/main/mysql.tex [new file with mode: 0644]
docs/manuals/en/main/newfeatures.tex [new file with mode: 0644]
docs/manuals/en/main/pools.tex [new file with mode: 0644]
docs/manuals/en/main/postgresql.tex [new file with mode: 0644]
docs/manuals/en/main/quickstart.tex [new file with mode: 0644]
docs/manuals/en/main/recycling.tex [new file with mode: 0644]
docs/manuals/en/main/requirements.tex [new file with mode: 0644]
docs/manuals/en/main/rescue.tex [new file with mode: 0644]
docs/manuals/en/main/restore.tex [new file with mode: 0644]
docs/manuals/en/main/security.tex [new file with mode: 0644]
docs/manuals/en/main/spooling.tex [new file with mode: 0644]
docs/manuals/en/main/sqlite.tex [new file with mode: 0644]
docs/manuals/en/main/state.tex [new file with mode: 0644]
docs/manuals/en/main/statistics.tex [new file with mode: 0644]
docs/manuals/en/main/storedconf.tex [new file with mode: 0644]
docs/manuals/en/main/strategies.tex [new file with mode: 0644]
docs/manuals/en/main/supportedchangers.tex [new file with mode: 0644]
docs/manuals/en/main/supporteddrives.tex [new file with mode: 0644]
docs/manuals/en/main/supportedoses.tex [new file with mode: 0644]
docs/manuals/en/main/thanks.tex [new file with mode: 0644]
docs/manuals/en/main/tls.tex [new file with mode: 0644]
docs/manuals/en/main/translate_images.pl [new file with mode: 0755]
docs/manuals/en/main/tutorial.tex [new file with mode: 0644]
docs/manuals/en/main/verify.tex [new file with mode: 0644]
docs/manuals/en/main/win32.tex [new file with mode: 0644]

index 79ffb0587d55ad28c573b372431b3da4e4b4e6c1..b4da198523ec32d20b356dc0b7300d3d7b7a72ad 100644 (file)
@@ -58,6 +58,9 @@ manuals/*/developers/developers.pdf
 manuals/*/misc/misci-*.tex
 manuals/*/misc/misc.pdf
 manuals/*/misc/misc/
+manuals/*/main/maini-*.tex
+manuals/*/main/main.pdf
+manuals/*/main/main/
 manuals/*/install/install.pdf
 manuals/*/problems/problems.pdf
 manuals/*/problems/problems/
index 65f24bdfda31dbed5ae0832b13c2fd50fec5093a..a81a6a14092312bc695da8254d50984b91eb255b 100644 (file)
@@ -17,13 +17,12 @@ thisdir = docs
 #
 
 de_dirs = manuals/de/catalog manuals/de/concepts manuals/de/console \
-  manuals/de/developers manuals/de/install manusla/de/misc manuals/de/problems \
+  manuals/de/developers manuals/de/install manuals/de/misc manuals/de/problems \
   manuals/de/utility
 
 
-en_dirs = manuals/en/catalog manuals/en/concepts manuals/en/console \
-  manuals/en/developers manuals/en/install manuals/en/misc manuals/en/problems \
-  manuals/en/utility
+en_dirs = manuals/en/console manuals/en/developers manuals/en/main \
+  manuals/en/misc manuals/en/problems manuals/en/utility
 
 es_dirs = manuals/es/catalog manuals/es/concepts manuals/es/console \
   manuals/es/developers manuals/es/install manuals/es/misc manuals/es/problems \
index 50f71f965447d7a93516f5100befe9abcbe4c4c2..331edd29c15f8341bb5581cf894b2f64f8a9801d 100644 (file)
@@ -103,6 +103,7 @@ AC_OUTPUT([    \
           manuals/en/catalog/Makefile \
           manuals/en/concepts/Makefile \
           manuals/en/console/Makefile \
+          manuals/en/main/Makefile \
           manuals/en/developers/Makefile \
           manuals/en/install/Makefile \
           manuals/en/problems/Makefile \
@@ -132,7 +133,7 @@ chmod 766 manuals/update_version
 
 # Now move common files into each subdirectory
 for i in manuals/update_version manuals/version.tex manuals/bacula.sty ; do
-  for j in catalog concepts console developers install misc problems utility ; do
+  for j in console developers main misc problems utility ; do
       cp -f $i manuals/de/$j
       cp -f $i manuals/en/$j
       cp -f $i manuals/es/$j
index 6d7443f7d45d66d015557a8e7ea7c1d71aef7f0e..09322b38ce1f0dbe56a14032b1baef6b0ed7cb50 100755 (executable)
@@ -2189,7 +2189,7 @@ MCOMMON=./autoconf/Make.common
 
 
 
-ac_config_files="$ac_config_files autoconf/Make.common Makefile manuals/update_version manuals/version.tex manuals/bacula.sty manuals/de/catalog/Makefile manuals/de/concepts/Makefile manuals/de/console/Makefile manuals/de/developers/Makefile manuals/de/install/Makefile manuals/de/problems/Makefile manuals/de/utility/Makefile manuals/en/catalog/Makefile manuals/en/concepts/Makefile manuals/en/console/Makefile manuals/en/developers/Makefile manuals/en/install/Makefile manuals/en/problems/Makefile manuals/en/utility/Makefile manuals/en/misc/Makefile manuals/es/catalog/Makefile manuals/es/concepts/Makefile manuals/es/console/Makefile manuals/es/developers/Makefile manuals/es/install/Makefile manuals/es/problems/Makefile manuals/es/utility/Makefile manuals/fr/catalog/Makefile manuals/fr/concepts/Makefile manuals/fr/console/Makefile manuals/fr/developers/Makefile manuals/fr/install/Makefile manuals/fr/problems/Makefile manuals/fr/utility/Makefile bacula-web/Makefile bacula-web/version.tex $PFILES"
+ac_config_files="$ac_config_files autoconf/Make.common Makefile manuals/update_version manuals/version.tex manuals/bacula.sty manuals/de/catalog/Makefile manuals/de/concepts/Makefile manuals/de/console/Makefile manuals/de/developers/Makefile manuals/de/install/Makefile manuals/de/problems/Makefile manuals/de/utility/Makefile manuals/en/catalog/Makefile manuals/en/concepts/Makefile manuals/en/console/Makefile manuals/en/main/Makefile manuals/en/developers/Makefile manuals/en/install/Makefile manuals/en/problems/Makefile manuals/en/utility/Makefile manuals/en/misc/Makefile manuals/es/catalog/Makefile manuals/es/concepts/Makefile manuals/es/console/Makefile manuals/es/developers/Makefile manuals/es/install/Makefile manuals/es/problems/Makefile manuals/es/utility/Makefile manuals/fr/catalog/Makefile manuals/fr/concepts/Makefile manuals/fr/console/Makefile manuals/fr/developers/Makefile manuals/fr/install/Makefile manuals/fr/problems/Makefile manuals/fr/utility/Makefile bacula-web/Makefile bacula-web/version.tex $PFILES"
 
 ac_config_commands="$ac_config_commands default"
 
@@ -2780,6 +2780,7 @@ do
     "manuals/en/catalog/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/catalog/Makefile" ;;
     "manuals/en/concepts/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/concepts/Makefile" ;;
     "manuals/en/console/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/console/Makefile" ;;
+    "manuals/en/main/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/main/Makefile" ;;
     "manuals/en/developers/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/developers/Makefile" ;;
     "manuals/en/install/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/install/Makefile" ;;
     "manuals/en/problems/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/problems/Makefile" ;;
@@ -3274,7 +3275,7 @@ chmod 766 manuals/update_version
 
 # Now move common files into each subdirectory
 for i in manuals/update_version manuals/version.tex manuals/bacula.sty ; do
-  for j in catalog concepts console developers install misc problems utility ; do
+  for j in console developers main misc problems utility ; do
       cp -f $i manuals/de/$j
       cp -f $i manuals/en/$j
       cp -f $i manuals/es/$j
diff --git a/docs/manuals/en/main/Makefile.in b/docs/manuals/en/main/Makefile.in
new file mode 100644 (file)
index 0000000..57bc8ca
--- /dev/null
@@ -0,0 +1,146 @@
+#
+#  Makefile for Bacula LaTeX  Manual
+#
+# 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=main
+MAINDOC=Bacula_Main_Reference.html
+
+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
+       @(if [ -f imagename_translations ] ; then \
+           ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+        fi)
+       (cd ${DOC}; for i in *.png ; do cp -fp ../${IMAGES}/$${i} . 2>/dev/null; done)
+       @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 Main Reference" -long_titles 4 \
+               -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1
+       @(if [ -f imagename_translations ] ; then \
+           ./translate_images.pl --from_meaningful_names ${DOC}.html; \
+        fi)
+       (cd ${DOC}; for i in *.png ; do cp -fp ../${IMAGES}/$${i} . 2>/dev/null; done)
+       @cp -f ${DOC}/${MAINDOC} ${DOC}/index.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
diff --git a/docs/manuals/en/main/STYLE b/docs/manuals/en/main/STYLE
new file mode 100644 (file)
index 0000000..ccdf236
--- /dev/null
@@ -0,0 +1,75 @@
+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.
diff --git a/docs/manuals/en/main/ansi-labels.tex b/docs/manuals/en/main/ansi-labels.tex
new file mode 100644 (file)
index 0000000..7d6e14f
--- /dev/null
@@ -0,0 +1,58 @@
+
+\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}
diff --git a/docs/manuals/en/main/autochangerres.tex b/docs/manuals/en/main/autochangerres.tex
new file mode 100644 (file)
index 0000000..98563c7
--- /dev/null
@@ -0,0 +1,107 @@
+%%
+\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.
diff --git a/docs/manuals/en/main/autochangers.tex b/docs/manuals/en/main/autochangers.tex
new file mode 100644 (file)
index 0000000..d3fa47e
--- /dev/null
@@ -0,0 +1,1011 @@
+%%
+%%
+
+\chapter{Autochanger Support}
+\label{AutochangersChapter}
+\index[general]{Support!Autochanger }
+\index[general]{Autochanger Support }
+
+Bacula provides autochanger support for reading and writing tapes.  In
+order to work with an autochanger, Bacula requires a number of things, each of
+which is explained in more detail after this list:
+
+\begin{itemize}
+\item A script that actually controls the autochanger according  to commands
+   sent by Bacula. We furnish such a script  that works with {\bf mtx} found in
+   the {\bf depkgs} distribution. 
+
+\item That each Volume (tape) to be used must be defined in the Catalog and
+   have a Slot number assigned to it so that Bacula knows where the Volume is
+   in the autochanger. This is generally done with the {\bf label} command, but
+   can also done after the tape is labeled using the {\bf update slots}
+   command.  See below for more details. You must pre-label the tapes manually
+   before using them.
+
+\item Modifications to your Storage daemon's Device configuration  resource to
+   identify that the device is a changer, as well  as a few other parameters.  
+
+\item You should also modify your Storage resource definition  in the
+   Director's configuration file so that you are automatically prompted for the
+   Slot when labeling a Volume. 
+
+\item You need to ensure that your Storage daemon (if not running as root)
+   has access permissions to both the tape drive and the control device.
+
+\item You need to have {\bf Autochanger = yes} in your Storage resource
+   in your bacula-dir.conf file so that you will be prompted for the
+   slot number when you label Volumes.
+\end{itemize}
+
+In version 1.37 and later, there is a new \ilink{Autochanger
+resource}{AutochangerRes} that permits you to group Device resources thus
+creating a multi-drive autochanger. If you have an autochanger,
+you {\bf must} use this new resource. 
+
+Bacula uses its own {\bf mtx-changer} script to interface with a program
+that actually does the tape changing.  Thus in principle, {\bf mtx-changer}
+can be adapted to function with any autochanger program, or you can
+call any other script or program. The current
+version of {\bf mtx-changer} works with the {\bf mtx} program.  However,
+FreeBSD users have provided a script in the {\bf examples/autochangers}
+directory that allows Bacula to use the {\bf chio} program.
+
+Bacula also supports autochangers with barcode
+readers. This support includes two Console commands: {\bf label barcodes}
+and {\bf update slots}. For more details on these commands, see the "Barcode
+Support" section below. 
+
+Current Bacula autochanger support does not include cleaning, stackers, or
+silos. Stackers and silos are not supported because Bacula expects to
+be able to access the Slots randomly.
+However, if you are very careful to setup Bacula to access the Volumes
+in the autochanger sequentially, you may be able to make Bacula
+work with stackers (gravity feed and such).  
+
+Support for multi-drive
+autochangers requires the \ilink{Autochanger resource}{AutochangerRes}
+introduced in version 1.37.  This resource is also recommended for single
+drive autochangers.
+
+In principle, if {\bf mtx} will operate your changer correctly, then it is
+just a question of adapting the {\bf mtx-changer} script (or selecting one
+already adapted) for proper interfacing. You can find a list of autochangers
+supported by {\bf mtx} at the following link: 
+\elink{http://mtx.opensource-sw.net/compatibility.php}
+{http://mtx.opensource-sw.net/compatibility.php}.
+The home page for the {\bf mtx} project can be found at: 
+\elink{http://mtx.opensource-sw.net/}{http://mtx.opensource-sw.net/}. 
+
+Note, we have feedback from some users that there are certain
+incompatibilities between the Linux kernel and mtx.  For example between
+kernel 2.6.18-8.1.8.el5 of CentOS and RedHat and version 1.3.10 and 1.3.11
+of mtx.  This was fixed by upgrading to a version 2.6.22 kernel.
+
+In addition, apparently certain versions of mtx, for example, version
+1.3.11 limit the number of slots to a maximum of 64. The solution was to
+use version 1.3.10.
+
+If you are having troubles, please use the {\bf auto} command in the {\bf
+btape} program to test the functioning of your autochanger with Bacula. When
+Bacula is running, please remember that for many distributions (e.g. FreeBSD,
+Debian, ...) the Storage daemon runs as {\bf bacula.tape} rather than {\bf
+root.root}, so you will need to ensure that the Storage daemon has sufficient
+permissions to access the autochanger. 
+
+Some users have reported that the the Storage daemon blocks under certain
+circumstances in trying to mount a volume on a drive that has a different
+volume loaded.  As best we can determine, this is simply a matter of
+waiting a bit.  The drive was previously in use writing a Volume, and
+sometimes the drive will remain BLOCKED for a good deal of time (up to 7
+minutes on a slow drive) waiting for the cassette to rewind and to unload
+before the drive can be used with a different Volume.
+
+\label{SCSI devices}
+\section{Knowing What SCSI Devices You Have}
+\index[general]{Have!Knowing What SCSI Devices You }
+\index[general]{Knowing What SCSI Devices You Have }
+\index[general]{SCSI devices}
+\index[general]{devices!SCSI}
+
+Under Linux, you can 
+
+\footnotesize
+\begin{verbatim}
+cat /proc/scsi/scsi
+\end{verbatim}
+\normalsize
+
+to see what SCSI devices you have available. You can also: 
+
+\footnotesize
+\begin{verbatim}
+cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices
+\end{verbatim}
+\normalsize
+
+to find out how to specify their control address ({\bf /dev/sg0} for the
+first, {\bf /dev/sg1} for the second, ...) on the {\bf Changer Device = }
+Bacula directive. 
+
+You can also use the excellent  {\bf lsscsi} tool.
+\footnotesize
+\begin{verbatim}
+$ lsscsi -g
+ [1:0:2:0]    tape    SEAGATE  ULTRIUM06242-XXX 1619  /dev/st0  /dev/sg9
+ [1:0:14:0]   mediumx STK      L180             0315  /dev/sch0 /dev/sg10
+ [2:0:3:0]    tape    HP       Ultrium 3-SCSI   G24S  /dev/st1  /dev/sg11
+ [3:0:0:0]    enclosu HP       A6255A           HP04  -         /dev/sg3
+ [3:0:1:0]    disk    HP 36.4G ST336753FC       HP00  /dev/sdd  /dev/sg4
+\end{verbatim}
+\normalsize
+
+For more detailed information on what SCSI devices you have please see
+the \ilink{Linux SCSI Tricks}{SCSITricks}  section of the Tape Testing
+chapter of this manual.
+
+Under FreeBSD, you can use: 
+
+\footnotesize
+\begin{verbatim}
+camcontrol devlist
+\end{verbatim}
+\normalsize
+
+To list the SCSI devices as well as the {\bf /dev/passn} that you will use on
+the Bacula {\bf Changer Device = } directive. 
+
+Please check that your Storage daemon has permission to access this
+device.
+
+The following tip for FreeBSD users comes from Danny Butroyd:
+on reboot Bacula will NOT have permission to 
+control the device /dev/pass0 (assuming this is your changer device).  
+To get around this just edit the /etc/devfs.conf file and add the 
+following to the bottom:                   
+\footnotesize
+\begin{verbatim}
+own     pass0   root:bacula
+perm    pass0   0666
+own     nsa0.0  root:bacula
+perm    nsa0.0    0666
+\end{verbatim}
+\normalsize
+
+This gives the bacula group permission to write to the nsa0.0 device 
+too just to be on the safe side.   To bring these changes into effect 
+just run:-
+
+/etc/rc.d/devfs restart
+
+Basically this will stop you having to manually change permissions on these 
+devices to make Bacula work when operating the AutoChanger after a reboot.
+
+\label{scripts}
+\section{Example Scripts}
+\index[general]{Scripts!Example }
+\index[general]{Example Scripts }
+
+Please read the sections below so that you understand how autochangers work
+with Bacula. Although we supply a default {\bf mtx-changer} script, your
+autochanger may require some additional changes. If you want to see examples
+of configuration files and scripts, please look in the {\bf
+\lt{}bacula-src\gt{}/examples/devices} directory where you will find an
+example {\bf HP-autoloader.conf} Bacula Device resource, and several {\bf
+mtx-changer} scripts that have been modified to work with different
+autochangers. 
+
+\label{Slots}
+
+\section{Slots}
+\index[general]{Slots }
+
+To properly address autochangers, Bacula must know which Volume is in each
+{\bf slot} of the autochanger. Slots are where the changer cartridges reside
+when not loaded into the drive. Bacula numbers these slots from one to the
+number of cartridges contained in the autochanger. 
+
+Bacula will not automatically use a Volume in your autochanger unless it is
+labeled and the slot number is stored in the catalog and the Volume is marked
+as InChanger. This is because it must know where each volume is (slot) to
+be able to load the volume.
+For each Volume in your
+changer, you will, using the Console program, assign a slot. This information
+is kept in {\bf Bacula's} catalog database along with the other data for the
+volume. If no slot is given, or the slot is set to zero, Bacula will not
+attempt to use the autochanger even if all the necessary configuration records
+are present. When doing a {\bf mount} command on an autochanger, you must
+specify which slot you want mounted.  If the drive is loaded with a tape 
+from another slot, it will unload it and load the correct tape, but
+normally, no tape will be loaded because an {\bf unmount} command causes
+Bacula to unload the tape in the drive.
+          
+
+You can check if the Slot number and InChanger flag are set by doing a:
+\begin{verbatim}
+list Volumes
+\end{verbatim}
+
+in the Console program.
+
+\label{mult}
+\section{Multiple Devices}
+\index[general]{Devices!Multiple}
+\index[general]{Multiple Devices}
+
+Some autochangers have more than one read/write device (drive). The
+new \ilink{Autochanger resource}{AutochangerRes} introduced in version
+1.37 permits you to group Device resources, where each device 
+represents a drive. The Director may still reference the Devices (drives)
+directly, but doing so, bypasses the proper functioning of the
+drives together.  Instead, the Director (in the Storage resource)
+should reference the Autochanger resource name. Doing so permits 
+the Storage daemon to ensure that only one drive uses the mtx-changer
+script at a time, and also that two drives don't reference the
+same Volume.
+
+Multi-drive requires the use of the {\bf
+Drive Index} directive in the Device resource of the Storage daemon's
+configuration file. Drive numbers or the Device Index are numbered beginning
+at zero, which is the default. To use the second Drive in an autochanger, you
+need to define a second Device resource and set the Drive Index to 1 for
+that device. In general, the second device will have the same {\bf Changer
+Device} (control channel) as the first drive, but a different {\bf Archive
+Device}. 
+
+As a default, Bacula jobs will prefer to write to a Volume that is
+already mounted. If you have a multiple drive autochanger and you want
+Bacula to write to more than one Volume in the same Pool at the same
+time, you will need to set \ilink{Prefer Mounted Volumes} {PreferMountedVolumes}
+in the Directors Job resource to {\bf no}. This will cause
+the Storage daemon to maximize the use of drives.
+
+
+\label{ConfigRecords}
+\section{Device Configuration Records}
+\index[general]{Records!Device Configuration }
+\index[general]{Device Configuration Records }
+
+Configuration of autochangers within Bacula is done in the Device resource of
+the Storage daemon. Four records: {\bf Autochanger}, {\bf Changer Device},
+{\bf Changer Command}, and {\bf Maximum Changer Wait} control how Bacula uses
+the autochanger. 
+
+These four records, permitted in {\bf Device} resources, are described in
+detail below. Note, however, that the {\bf Changer Device} and the 
+{\bf Changer Command} directives are not needed in the Device resource
+if they are present in the {\bf Autochanger} resource.
+
+\begin{description}
+
+\item [Autochanger = {\it Yes|No} ]
+   \index[sd]{Autochanger  }
+   The {\bf Autochanger} record specifies that the current device  is or is not
+an autochanger. The default is {\bf no}.  
+
+\item [Changer Device = \lt{}device-name\gt{}]
+   \index[sd]{Changer Device  }
+   In addition to the Archive Device name, you must specify a  {\bf Changer
+Device} name. This is because most autochangers are  controlled through a
+different device than is used for reading and  writing the cartridges. For
+example, on Linux, one normally uses the generic SCSI interface for
+controlling the autochanger, but the standard SCSI interface for reading and
+writing the  tapes. On Linux, for the {\bf Archive Device = /dev/nst0},  you
+would typically have {\bf Changer Device = /dev/sg0}.  Note, some of the more
+advanced autochangers will locate the changer device on {\bf /dev/sg1}. Such
+devices typically have  several drives and a large number of tapes.  
+
+On FreeBSD systems, the changer device will typically be on {\bf /dev/pass0}
+through {\bf /dev/passn}.  
+
+On Solaris, the changer device will typically be some file under {\bf
+/dev/rdsk}.  
+
+Please ensure that your Storage daemon has permission to access this
+device.
+
+\item [Changer Command = \lt{}command\gt{}]
+   \index[sd]{Changer Command  }
+   This record is used to specify the external program to call  and what
+arguments to pass to it. The command is assumed to be  a standard program or
+shell script that can be executed by  the operating system. This command is
+invoked each time that Bacula wishes to manipulate the autochanger.  The
+following substitutions are made in the {\bf command}  before it is sent to
+the operating system for execution:  
+
+\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
+
+An actual example for using {\bf mtx} with the  {\bf mtx-changer} script (part
+of the Bacula distribution) is:  
+
+\footnotesize
+\begin{verbatim}
+Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
+\end{verbatim}
+\normalsize
+
+Where you will need to adapt the {\bf /etc/bacula} to be  the actual path on
+your system where the mtx-changer script  resides.  Details of the three
+commands currently used by Bacula  (loaded, load, unload) as well as the
+output expected by  Bacula are give in the {\bf Bacula Autochanger Interface} 
+section below.  
+
+\item [Maximum Changer Wait = \lt{}time\gt{}]
+   \index[sd]{Maximum Changer Wait  }
+   This record is used to define the maximum amount of time that Bacula
+   will wait for an autoloader to respond to a command (e.g.  load).  The
+   default is set to 120 seconds.  If you have a slow autoloader you may
+   want to set it longer.
+
+If the autoloader program fails to respond in this time, it  will be killed
+and Bacula will request operator intervention.  
+
+\item [Drive Index = \lt{}number\gt{}]
+   \index[sd]{Drive Index  }
+   This record allows you to tell Bacula to use the second or subsequent
+   drive in an autochanger with multiple drives.  Since the drives are
+   numbered from zero, the second drive is defined by
+
+\footnotesize
+\begin{verbatim}
+Device Index = 1
+      
+\end{verbatim}
+\normalsize
+
+To use the second drive, you need a second Device resource definition  in the
+Bacula configuration file. See the Multiple Drive section above  in this
+chapter for more information. 
+\end{description}
+
+In addition, for proper functioning of the Autochanger, you must 
+define an Autochanger resource.
+\input{autochangerres}
+
+\label{example}
+\section{An Example Configuration File}
+\index[general]{Example Configuration File }
+\index[general]{File!Example Configuration }
+
+The following two resources implement an autochanger: 
+
+\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
+
+where you will adapt the {\bf Archive Device}, the {\bf Changer Device}, and
+the path to the {\bf Changer Command} to correspond to the values used on your
+system. 
+
+\section{A Multi-drive Example Configuration File}
+\index[general]{Multi-drive Example Configuration File }
+
+The following resources implement a multi-drive autochanger: 
+
+\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
+
+where you will adapt the {\bf Archive Device}, the {\bf Changer Device}, and
+the path to the {\bf Changer Command} to correspond to the values used on your
+system. 
+
+\label{SpecifyingSlots}
+\section{Specifying Slots When Labeling}
+\index[general]{Specifying Slots When Labeling }
+\index[general]{Labeling!Specifying Slots When }
+
+If you add an {\bf Autochanger = yes} record to the Storage resource in your
+Director's configuration file, the Bacula Console will automatically prompt
+you for the slot number when the Volume is in the changer when
+you {\bf add} or {\bf label} tapes for that Storage device. If your
+{\bf mtx-changer} script is properly installed, Bacula will automatically
+load the correct tape during the label command.
+  
+You must also set
+{\bf Autochanger = yes} in the Storage daemon's Device resource                
+as we have described above in
+order for the autochanger to be used. Please see the 
+\ilink{Storage Resource}{Autochanger1} in the Director's chapter
+and the 
+\ilink{Device Resource}{Autochanger} in the Storage daemon
+chapter for more details on these records. 
+
+Thus all stages of dealing with tapes can be totally automated. It is also
+possible to set or change the Slot using the {\bf update} command in the
+Console and selecting {\bf Volume Parameters} to update. 
+
+Even though all the above configuration statements are specified and correct,
+Bacula will attempt to access the autochanger only if a {\bf slot} is non-zero
+in the catalog Volume record (with the Volume name). 
+
+If your autochanger has barcode labels, you can label all the Volumes in
+your autochanger one after another by using the {\bf label barcodes} command.
+For each tape in the changer containing a barcode, Bacula will mount the tape
+and then label it with the same name as the barcode. An appropriate Media
+record will also be created in the catalog. Any barcode that begins with the
+same characters as specified on the "CleaningPrefix=xxx" command, will be
+treated as a cleaning tape, and will not be labeled. For example with: 
+
+Please note that Volumes must be pre-labeled to be automatically used in
+the autochanger during a backup.  If you do not have a barcode reader, this
+is done manually (or via a script).
+
+\footnotesize
+\begin{verbatim}
+Pool {
+  Name ...
+  Cleaning Prefix = "CLN"
+}
+\end{verbatim}
+\normalsize
+
+Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
+and will not be mounted.
+
+\section{Changing Cartridges}
+\index[general]{Changing Cartridges }
+If you wish to insert or remove cartridges in your autochanger or
+you manually run the {\bf mtx} program, you must first tell Bacula
+to release the autochanger by doing:
+
+\footnotesize
+\begin{verbatim}
+unmount
+(change cartridges and/or run mtx)
+mount
+\end{verbatim}
+\normalsize
+
+If you do not do the unmount before making such a change, Bacula
+will become completely confused about what is in the autochanger
+and may stop function because it expects to have exclusive use
+of the autochanger while it has the drive mounted.
+
+
+\label{Magazines}
+\section{Dealing with Multiple Magazines}
+\index[general]{Dealing with Multiple Magazines }
+\index[general]{Magazines!Dealing with Multiple }
+
+If you have several magazines or if you insert or remove cartridges from a
+magazine, you should notify Bacula of this. By doing so, Bacula will as
+a preference, use Volumes that it knows to be in the autochanger before
+accessing Volumes that are not in the autochanger. This prevents unneeded
+operator intervention. 
+
+If your autochanger has barcodes (machine readable tape labels), the task of
+informing Bacula is simple. Every time, you change a magazine, or add or
+remove a cartridge from the magazine, simply do 
+
+\footnotesize
+\begin{verbatim}
+unmount
+(remove magazine)
+(insert new magazine)
+update slots
+mount
+\end{verbatim}
+\normalsize
+
+in the Console program. This will cause Bacula to request the autochanger to
+return the current Volume names in the magazine. This will be done without
+actually accessing or reading the Volumes because the barcode reader does this
+during inventory when the autochanger is first turned on. Bacula will ensure
+that any Volumes that are currently marked as being in the magazine are marked
+as no longer in the magazine, and the new list of Volumes will be marked as
+being in the magazine. In addition, the Slot numbers of the Volumes will be
+corrected in Bacula's catalog if they are incorrect (added or moved). 
+
+If you do not have a barcode reader on your autochanger, you have several
+alternatives. 
+
+\begin{enumerate}
+\item You can manually set the Slot and InChanger flag using  the {\bf update
+   volume} command in the Console (quite  painful). 
+
+\item You can issue a 
+
+\footnotesize
+\begin{verbatim}
+update slots scan
+\end{verbatim}
+\normalsize
+
+   command that will cause Bacula to read the label on each  of the cartridges in
+   the magazine in turn and update the  information (Slot, InChanger flag) in the
+   catalog. This  is quite effective but does take time to load each cartridge 
+   into the drive in turn and read the Volume label.  
+
+\item You can modify the mtx-changer script so that it simulates  an
+   autochanger with barcodes. See below for more details. 
+\end{enumerate}
+
+\label{simulating}
+\section{Simulating Barcodes in your Autochanger}
+\index[general]{Autochanger!Simulating Barcodes in your }
+\index[general]{Simulating Barcodes in your Autochanger }
+
+You can simulate barcodes in your autochanger by making the {\bf mtx-changer}
+script return the same information that an autochanger with barcodes would do.
+This is done by commenting out the one and only line in the {\bf list)} case,
+which is: 
+
+\footnotesize
+\begin{verbatim}
+  ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//"
+\end{verbatim}
+\normalsize
+
+at approximately line 99 by putting a \# in column one of that line, or by
+simply deleting it. Then in its place add a new line that prints the contents
+of a file. For example: 
+
+\footnotesize
+\begin{verbatim}
+cat /etc/bacula/changer.volumes
+\end{verbatim}
+\normalsize
+
+Be sure to include a full path to the file, which can have any name. The
+contents of the file must be of the following format: 
+
+\footnotesize
+\begin{verbatim}
+1:Volume1
+2:Volume2
+3:Volume3
+...
+\end{verbatim}
+\normalsize
+
+Where the 1, 2, 3 are the slot numbers and Volume1, Volume2, ... are the
+Volume names in those slots. You can have multiple files that represent the
+Volumes in different magazines, and when you change magazines, simply copy the
+contents of the correct file into your {\bf /etc/bacula/changer.volumes} file.
+There is no need to stop and start Bacula when you change magazines, simply
+put the correct data in the file, then run the {\bf update slots} command, and
+your autochanger will appear to Bacula to be an autochanger with barcodes. 
+\label{updateslots}
+
+\section{The Full Form of the Update Slots Command}
+\index[general]{Full Form of the Update Slots Command }
+\index[general]{Command!Full Form of the Update Slots }
+
+If you change only one cartridge in the magazine, you may not want to scan all
+Volumes, so the {\bf update slots} command (as well as the {\bf update slots
+scan} command) has the additional form: 
+
+\footnotesize
+\begin{verbatim}
+update slots=n1,n2,n3-n4, ...
+\end{verbatim}
+\normalsize
+
+where the keyword {\bf scan} can be appended or not. The n1,n2, ... represent
+Slot numbers to be updated and the form n3-n4 represents a range of Slot
+numbers to be updated (e.g. 4-7 will update Slots 4,5,6, and 7). 
+
+This form is particularly useful if you want to do a scan (time expensive) and
+restrict the update to one or two slots. 
+
+For example, the command: 
+
+\footnotesize
+\begin{verbatim}
+update slots=1,6 scan
+\end{verbatim}
+\normalsize
+
+will cause Bacula to load the Volume in Slot 1, read its Volume label and
+update the Catalog. It will do the same for the Volume in Slot 6. The command:
+
+
+\footnotesize
+\begin{verbatim}
+update slots=1-3,6
+\end{verbatim}
+\normalsize
+
+will read the barcoded Volume names for slots 1,2,3 and 6 and make the
+appropriate updates in the Catalog. If you don't have a barcode reader or have
+not modified the mtx-changer script as described above, the above command will
+not find any Volume names so will do nothing. 
+\label{FreeBSD}
+
+\section{FreeBSD Issues}
+\index[general]{Issues!FreeBSD }
+\index[general]{FreeBSD Issues }
+
+If you are having problems on FreeBSD when Bacula tries to select a tape, and
+the message is {\bf Device not configured}, this is because FreeBSD has made
+the tape device {\bf /dev/nsa1} disappear when there is no tape mounted in the
+autochanger slot. As a consequence, Bacula is unable to open the device. The
+solution to the problem is to make sure that some tape is loaded into the tape
+drive before starting Bacula. This problem is corrected in Bacula versions
+1.32f-5 and later. 
+
+Please see the 
+\ilink{ Tape Testing}{FreeBSDTapes} chapter of this manual for
+{\bf important} information concerning your tape drive before doing the
+autochanger testing. 
+\label{AutochangerTesting}
+
+\section{Testing Autochanger and Adapting mtx-changer script}
+\index[general]{Testing the Autochanger }
+\index[general]{Adapting Your mtx-changer script}
+
+
+Before attempting to use the autochanger with Bacula, it is preferable to
+"hand-test" that the changer works. To do so, we suggest you do the
+following commands (assuming that the {\bf mtx-changer} script is installed in
+{\bf /etc/bacula/mtx-changer}): 
+
+\begin{description}
+
+\item [Make sure Bacula is not running.]
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ list \ 0 \ /dev/nst0 \ 0]
+\index[sd]{mtx-changer list}
+
+This command should print:  
+
+\footnotesize
+\begin{verbatim}
+   1:
+   2:
+   3:
+   ...
+   
+\end{verbatim}
+\normalsize
+
+or one number per line for each slot that is  occupied in your changer, and
+the number should be  terminated by a colon ({\bf :}). If your changer has 
+barcodes, the barcode will follow the colon.  If an error message is printed,
+you must resolve the  problem (e.g. try a different SCSI control device name
+if {\bf /dev/sg0}  is incorrect). For example, on FreeBSD systems, the
+autochanger  SCSI control device is generally {\bf /dev/pass2}.  
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ slots ]
+\index[sd]{mtx-changer slots}
+
+This command should return the number of slots in your autochanger.  
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload \ 1 \ /dev/nst0 \ 0 ]
+\index[sd]{mtx-changer unload}
+
+   If a tape is loaded from slot 1, this should cause it to be unloaded.  
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ load \ 3 \ /dev/nst0 \ 0 ]
+\index[sd]{mtx-changer load}
+
+Assuming you have a tape in slot 3,  it will be loaded into drive (0).
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ loaded \ 0 \ /dev/nst0 \ 0]
+\index[sd]{mtx-changer loaded}
+
+It should print "3"  
+Note, we have used an "illegal" slot number 0. In this case, it is simply
+ignored because the slot number is not used.  However, it must be specified
+because the drive parameter at the end of the command is needed to select
+the correct drive.
+
+\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload \ 3 /dev/nst0 \ 0]
+
+will unload the tape into slot 3.
+
+\end{description}
+
+Once all the above commands work correctly, assuming that you have the right
+{\bf Changer Command} in your configuration, Bacula should be able to operate
+the changer. The only remaining area of problems will be if your autoloader
+needs some time to get the tape loaded after issuing the command. After the
+{\bf mtx-changer} script returns, Bacula will immediately rewind and read the
+tape. If Bacula gets rewind I/O errors after a tape change, you will probably
+need to insert a {\bf sleep 20} after the {\bf mtx} command, but be careful to
+exit the script with a zero status by adding {\bf exit 0} after any additional
+commands you add to the script. This is because Bacula checks the return
+status of the script, which should be zero if all went well. 
+
+You can test whether or not you need a {\bf sleep} by putting the following
+commands into a file and running it as a script: 
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+/etc/bacula/mtx-changer /dev/sg0 unload 1 /dev/nst0 0
+/etc/bacula/mtx-changer /dev/sg0 load 3 /dev/nst0 0
+mt -f /dev/st0 rewind
+mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+If the above script runs, you probably have no timing problems. If it does not
+run, start by putting a {\bf sleep 30} or possibly a {\bf sleep 60} in the 
+script just after the mtx-changer load command. If that works, then you should
+move the sleep into the actual {\bf mtx-changer} script so that it will be
+effective when Bacula runs. 
+
+A second problem that comes up with a small number of autochangers is that
+they need to have the cartridge ejected before it can be removed. If this is
+the case, the {\bf load 3} will never succeed regardless of how long you wait.
+If this seems to be your problem, you can insert an eject just after the
+unload so that the script looks like: 
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+/etc/bacula/mtx-changer /dev/sg0 unload 1 /dev/nst0 0
+mt -f /dev/st0 offline
+/etc/bacula/mtx-changer /dev/sg0 load 3 /dev/nst0 0
+mt -f /dev/st0 rewind
+mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+Obviously, if you need the {\bf offline} command, you should move it into the
+mtx-changer script ensuring that you save the status of the {\bf mtx} command
+or always force an {\bf exit 0} from the script, because Bacula checks the
+return status of the script. 
+
+As noted earlier, there are several scripts in {\bf
+\lt{}bacula-source\gt{}/examples/devices} that implement the above features,
+so they may be a help to you in getting your script to work. 
+
+If Bacula complains "Rewind error on /dev/nst0. ERR=Input/output error." you
+most likely need more sleep time in your {\bf mtx-changer} before returning to
+Bacula after a load command has been completed.
+
+\label{using}
+
+\section{Using the Autochanger}
+\index[general]{Using the Autochanger }
+\index[general]{Autochanger!Using the }
+
+Let's assume that you have properly defined the necessary Storage daemon
+Device records, and you have added the {\bf Autochanger = yes} record to the
+Storage resource in your Director's configuration file. 
+
+Now you fill your autochanger with say six blank tapes. 
+
+What do you do to make Bacula access those tapes? 
+
+One strategy is to prelabel each of the tapes. Do so by starting Bacula, then
+with the Console program, enter the {\bf label} command: 
+
+\footnotesize
+\begin{verbatim}
+./bconsole
+Connecting to Director rufus:8101
+1000 OK: rufus-dir Version: 1.26 (4 October 2002)
+*label
+\end{verbatim}
+\normalsize
+
+it will then print something like: 
+
+\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
+
+I select the autochanger (1), and it prints: 
+
+\footnotesize
+\begin{verbatim}
+Enter new Volume name: TestVolume1
+Enter slot (0 for none): 1
+\end{verbatim}
+\normalsize
+
+where I entered {\bf TestVolume1} for the tape name, and slot {\bf 1} for the
+slot. It then asks: 
+
+\footnotesize
+\begin{verbatim}
+Defined Pools:
+     1: Default
+     2: File
+Select the Pool (1-2): 1
+\end{verbatim}
+\normalsize
+
+I select the Default pool. This will be automatically done if you only have a
+single pool, then Bacula will proceed to unload any loaded volume, load the
+volume in slot 1 and label it. In this example, nothing was in the drive, so
+it printed: 
+
+\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
+
+You may then proceed to label the other volumes. The messages will change
+slightly because Bacula will unload the volume (just labeled TestVolume1)
+before loading the next volume to be labeled. 
+
+Once all your Volumes are labeled, Bacula will automatically load them as they
+are needed. 
+
+To "see" how you have labeled your Volumes, simply enter the {\bf list
+volumes} command from the Console program, which should print something like
+the following: 
+
+\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{Barcode Support}
+\index[general]{Support!Barcode }
+\index[general]{Barcode Support }
+
+Bacula provides barcode support with two Console commands, {\bf label
+barcodes} and {\bf update slots}.
+
+The {\bf label barcodes} will cause Bacula to read the barcodes of all the
+cassettes that are currently installed in the magazine (cassette holder) using
+the {\bf mtx-changer} {\bf list} command. Each cassette is mounted in turn and
+labeled with the same Volume name as the barcode. 
+
+The {\bf update slots} command will first obtain the list of cassettes and
+their barcodes from {\bf mtx-changer}. Then it will find each volume in turn
+in the catalog database corresponding to the barcodes and set its Slot to
+correspond to the value just read. If the Volume is not in the catalog, then
+nothing will be done. This command is useful for synchronizing Bacula with the
+current magazine in case you have changed magazines or in case you have moved
+cassettes from one slot to another. If the autochanger is empty, nothing will
+be done.
+
+The {\bf Cleaning Prefix} statement can be used in the Pool resource to define
+a Volume name prefix, which if it matches that of the Volume (barcode) will
+cause that Volume to be marked with a VolStatus of {\bf Cleaning}. This will
+prevent Bacula from attempting to write on the Volume.
+
+\section{Use bconsole to display Autochanger content}
+
+The {\bf status slots storage=xxx} command displays autochanger content.
+
+\footnotesize
+\begin{verbatim}
+ Slot |  Volume Name    |  Status  |      Type         |    Pool        |  Loaded |
+------+-----------------+----------+-------------------+----------------+---------|
+    1 |           00001 |   Append |  DiskChangerMedia |        Default |    0    |
+    2 |           00002 |   Append |  DiskChangerMedia |        Default |    0    |
+    3*|           00003 |   Append |  DiskChangerMedia |        Scratch |    0    |
+    4 |                 |          |                   |                |    0    |
+\end{verbatim}
+\normalsize
+
+If you see a {\bf *} near the slot number, you have to run {\bf update slots}
+command to synchronize autochanger content with your catalog.
+
+\label{interface}
+
+\section{Bacula Autochanger Interface}
+\index[general]{Interface!Bacula Autochanger }
+\index[general]{Bacula Autochanger Interface }
+
+Bacula calls the autochanger script that you specify on the {\bf Changer
+Command} statement. Normally this script will be the {\bf mtx-changer} script
+that we provide, but it can in fact be any program. The only requirement
+for the script is that it must understand the commands that
+Bacula uses, which are {\bf loaded}, {\bf load}, {\bf
+unload}, {\bf list}, and {\bf slots}. In addition,
+each of those commands must return the information in the precise format as
+specified below: 
+
+\footnotesize
+\begin{verbatim}
+- Currently the changer commands used are:
+    loaded -- returns number of the slot that is loaded, base 1,
+              in the drive or 0 if the drive is empty.
+    load   -- loads a specified slot (note, some autochangers
+              require a 30 second pause after this command) into
+              the drive.
+    unload -- unloads the device (returns cassette to its slot).
+    list   -- returns one line for each cassette in the autochanger
+              in the format <slot>:<barcode>. Where
+              the {\bf slot} is the non-zero integer representing
+              the slot number, and {\bf barcode} is the barcode
+              associated with the cassette if it exists and if you
+              autoloader supports barcodes. Otherwise the barcode
+              field is blank.
+    slots  -- returns total number of slots in the autochanger.
+\end{verbatim}
+\normalsize
+
+Bacula checks the exit status of the program called, and if it is zero, the
+data is accepted. If the exit status is non-zero, Bacula will print an
+error message and request the tape be manually mounted on the drive.
diff --git a/docs/manuals/en/main/bimagemgr.bix b/docs/manuals/en/main/bimagemgr.bix
new file mode 100644 (file)
index 0000000..8c18e20
--- /dev/null
@@ -0,0 +1,7 @@
+\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}
diff --git a/docs/manuals/en/main/bootstrap.tex b/docs/manuals/en/main/bootstrap.tex
new file mode 100644 (file)
index 0000000..882aaf0
--- /dev/null
@@ -0,0 +1,427 @@
+%%
+%%
+
+\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 [FileRegex]
+   \index[general]{FileRegex}
+   The value is a regular expression.  When specified, only matching
+   filenames will be restored.
+
+\begin{verbatim}
+   FileRegex=^/etc/passwd(.old)?
+\end{verbatim}
+
+\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. 
diff --git a/docs/manuals/en/main/bugs.tex b/docs/manuals/en/main/bugs.tex
new file mode 100644 (file)
index 0000000..42df829
--- /dev/null
@@ -0,0 +1,21 @@
+%%
+%%
+
+\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. 
diff --git a/docs/manuals/en/main/catmaintenance.tex b/docs/manuals/en/main/catmaintenance.tex
new file mode 100644 (file)
index 0000000..da243b0
--- /dev/null
@@ -0,0 +1,788 @@
+%%
+%%
+
+\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}
+
+\section{MySQL Temporary Tables}
+When doing backups with large numbers of files, MySQL creates some
+temporary tables.  When these tables are small they can be held in
+system memory, but as they approach some size, they
+spool off to disk.  The default location for these temp tables is
+/tmp.  Once that space fills up, Bacula daemons such as the Storage
+daemon doing spooling can get strange errors. E.g.
+
+\footnotesize                                 
+\begin{verbatim}
+Fatal error: spool.c:402 Spool data read error.
+Fatal error: backup.c:892 Network send error to SD. ERR=Connection reset by
+peer
+\end{verbatim}
+\normalsize
+
+What you need to do is setup MySQL to use a different (larger) temp
+directory, which can be set in the /etc/my.cnf with these variables
+set:
+
+\footnotesize                                 
+\begin{verbatim}
+  tmpdir=/path/to/larger/tmpdir
+  bdb_tmpdir=/path/to/larger/tmpdir
+\end{verbatim}
+\normalsize
+
+\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 two 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
+one is the (JobId, PathId, Filename) 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 (jobid, pathid, filenameid);
+\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 (JobId, 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}
+sqlite <path>/bacula.db
+CREATE INDEX file_jobid_idx on File (JobId);
+CREATE INDEX file_jfp_idx on File (JobId, PathId, FilenameId);
+\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 or PostgreSQL}
+\index[general]{MySQL!Migrating from SQLite to }
+\index[general]{Migrating from SQLite to MySQL or PostgreSQL}
+
+You may begin using Bacula with SQLite then later find that you want to switch
+to MySQL or Postgres 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 by
+exporting the SQLite data and then processing it with Perl scripts prior to
+putting it into MySQL or PostgreSQL. This is, however, not a simple process.
+Scripts are available on bacula source distribution under
+\texttt{examples/database}.
+
+\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. 
diff --git a/docs/manuals/en/main/check_tex.pl b/docs/manuals/en/main/check_tex.pl
new file mode 100755 (executable)
index 0000000..e12d51b
--- /dev/null
@@ -0,0 +1,152 @@
+#!/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);
diff --git a/docs/manuals/en/main/configure.tex b/docs/manuals/en/main/configure.tex
new file mode 100644 (file)
index 0000000..0752156
--- /dev/null
@@ -0,0 +1,406 @@
+%%
+%%
+
+\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{\idir bacula-objects.eps} 
+\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\vb{}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{\idir 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}
diff --git a/docs/manuals/en/main/consoleconf.tex b/docs/manuals/en/main/consoleconf.tex
new file mode 100644 (file)
index 0000000..563c81a
--- /dev/null
@@ -0,0 +1,356 @@
+%%
+%%
+
+\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
diff --git a/docs/manuals/en/main/coverpage.tex b/docs/manuals/en/main/coverpage.tex
new file mode 100644 (file)
index 0000000..d6aa6a5
--- /dev/null
@@ -0,0 +1,28 @@
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{\idir bacula-logo.eps} \\ \bigskip
+  \Huge{Bacula}$^{\normalsize \textregistered}$ \Huge{Bacula Main Reference}
+  \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 \fullversion \\
+      \vspace{0.2in}
+      Copyright {\copyright} 1999-2009, Free Software Foundation Europe
+      e.V. \\
+      Bacula {\textregistered}  is a registered trademark of Kern Sibbald.\\
+      \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
diff --git a/docs/manuals/en/main/critical.tex b/docs/manuals/en/main/critical.tex
new file mode 100644 (file)
index 0000000..ee0d225
--- /dev/null
@@ -0,0 +1,130 @@
+%%
+%%
+
+\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
+   notepad} 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}
diff --git a/docs/manuals/en/main/dataencryption.tex b/docs/manuals/en/main/dataencryption.tex
new file mode 100644 (file)
index 0000000..9b259ce
--- /dev/null
@@ -0,0 +1,195 @@
+
+\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 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 \gt master.keypair
+
+\item 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
diff --git a/docs/manuals/en/main/dirdconf.tex b/docs/manuals/en/main/dirdconf.tex
new file mode 100644 (file)
index 0000000..c448d31
--- /dev/null
@@ -0,0 +1,3544 @@
+%%
+%%
+
+\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.
+
+\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.
+
+
+\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.  
+
+   The Volume format becomes more complicated with 
+   multiple simultaneous jobs, consequently, restores may take longer if
+   Bacula must sort through interleaved volume blocks from  multiple simultaneous
+   jobs. This can be avoided by having each simultaneous job write to
+   a different volume or  by using data spooling, which will first spool the data
+   to disk simultaneously, then write one spool file at a time to the volume
+   thus avoiding excessive interleaving of the different job blocks.
+
+\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 (N.B 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 (N.B. plural) directive.
+
+\item [DirSourceAddress = \lt{}IP-Address\gt{}]
+   \index[fd]{DirSourceAddress}
+   \index[fd]{Directive!DirSourceAddress}
+   This record is optional, and if it is specified, it will cause the Director
+   server (when initiating connections to a storage or file daemon) to source
+   its connections from the specified address.  Only a single IP address may be
+   specified.  If this record is not specified, the Director server will source
+   its outgoing connections according to the system routing table (the default).
+
+\item[Statistics Retention = \lt{}time\gt{}]
+   \index[dir]{StatisticsRetention}
+   \index[dir]{Directive!StatisticsRetention}
+   \label{PruneStatistics}
+
+   The \texttt{Statistics Retention} directive defines the length of time that
+   Bacula will keep statistics job records in the Catalog database after the
+   Job End time. (In \texttt{JobHistory} table) When this time period expires,
+   and if user runs \texttt{prune stats} command, Bacula will prune (remove)
+   Job records that are older than the specified period.
+
+   Theses statistics records aren't use for restore purpose, but mainly for
+   capacity planning, billings, etc. See \ilink{Statistics chapter} for
+   additional information.
+
+   See the \ilink{ Configuration chapter}{Time} of this manual for additional
+   details of time specification.
+
+   The default is 5 years.
+
+\item[VerId = \lt{}string\gt{}]
+  \index[dir]{Directive!VerId}
+  where  \lt{}string\gt{} is an identifier which can be used for support purpose.
+  This string is displayed using the \texttt{version} command.
+
+\item[MaxConsoleConnections = \lt{}number\gt{}] 
+  \index[dir]{MaximumConsoleConnections}
+  \index[dir]{MaxConsoleConnections}
+  \index[dir]{Directive!MaxConsoleConnections}
+  \index[dir]{Console}
+   where \lt{}number\gt{}  is the maximum number of Console Connections that
+   could run  concurrently. The default is set to 20, but you may set it to a 
+   larger number.
+
+\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.
+
+Multiple Storage daemons are not currently supported for Jobs, so if
+you do want to use multiple storage daemons, you will need to create
+a different Job and ensure that for each Job that the combination of
+Client and FileSet are unique.  The Client and FileSet are what Bacula
+uses to restore a client, so if there are multiple Jobs with the same
+Client and FileSet or multiple Storage daemons that are used, the
+restore will not work.  This problem can be resolved by defining multiple
+FileSet definitions (the names must be different, but the contents of
+the FileSets may be the same).
+               
+
+\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\vb{}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).  
+\item The Job started no longer ago than {\bf Max Full Interval}.
+\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.
+
+   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.
+
+   However, to manage deleted files or directories changes in the
+   catalog during an Incremental backup you can use \texttt{accurate}
+   mode. This is quite memory consuming process. See \ilink{Accurate
+     mode}{accuratemode} for more details.
+
+\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).  
+\item The Job started no longer ago than {\bf Max Full Interval}.
+\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.
+
+%% TODO: merge this with incremental 
+   However, to manage deleted files or directories changes in the
+   catalog during an Differential backup you can use \texttt{accurate}
+   mode. This is quite memory consuming process. See \ilink{Accurate
+     mode}{accuratemode} for more details.
+
+   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 [Accurate = \lt{}yes\vb{}no\gt{}]
+\index[dir]{Accurate}
+   In accurate mode, the File daemon knowns exactly which files were present
+   after the last backup. So it is able to handle deleted or renamed files.
+
+   When restoring a FileSet for a specified date (including "most
+   recent"), Bacula is able to restore exactly the files and
+   directories that existed at the time of the last backup prior to
+   that date including ensuring that deleted files are actually deleted,
+   and renamed directories are restored properly.
+
+   In this mode, the File daemon must keep data concerning all files in
+   memory.  So you do not have sufficient memory, the restore may
+   either be terribly slow or fail.
+
+%%   $$ memory = \sum_{i=1}^{n}(strlen(path_i + file_i) + sizeof(CurFile))$$
+
+   For 500.000 files (a typical desktop linux system), it will require
+   approximately 64 Megabytes of RAM on your File daemon to hold the
+   required information.
+
+\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).
+
+\item [Incremental|Differential Max Wait Time = \lt{}time\gt{}]
+\index[dir]{Incremental Wait Run Time}
+\index[dir]{Differential Wait Run Time}
+\index[dir]{Directive!Differential Max Wait Time}
+    Theses directives have been deprecated in favor of
+    \texttt{Incremental|Differential Max Run Time} since bacula 2.3.18.
+
+\item [Incremental Max Run Time = \lt{}time\gt{}]
+\index[dir]{Incremental Max Run Time}
+\index[dir]{Directive!Incremental Max Run Time}
+The time specifies the maximum allowed time that an Incremental backup job may
+run, counted from when the job starts, ({\bf not} necessarily the same as when
+the job was scheduled).
+
+\item [Differential Max Wait Time = \lt{}time\gt{}]
+\index[dir]{Differential Max Run Time}
+\index[dir]{Directive!Differential Max Run Time}
+The time specifies the maximum allowed time that a Differential backup job may
+run, counted from when the job starts, ({\bf not} necessarily the same as when
+the job was scheduled).
+
+\item [Max Run Sched Time = \lt{}time\gt{}]
+\index[dir]{Max Run Sched Time}
+\index[dir]{Directive!Max Run Sched Time}
+
+The time specifies the maximum allowed time that a job may run, counted from
+when the job was scheduled. This can be useful to prevent jobs from running
+during working hours. We can see it like \texttt{Max Start Delay + Max Run
+  Time}.
+
+\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 works as expected since bacula 2.3.18.
+
+\addcontentsline{lof}{figure}{Job time control directives}
+\includegraphics{\idir different_time.eps}
+
+\item [Max Full Interval = \lt{}time\gt{}]
+\index[dir]{Max Full Interval}
+\index[dir]{Directive!Max Full Interval}
+   The time specifies the maximum allowed age (counting from start time) of
+   the most recent successful Full backup that is required in order to run
+   Incremental or Differential backup jobs. If the most recent Full backup
+   is older than this interval, Incremental and Differential backups will be
+   upgraded to Full backups automatically. If this directive is not present,
+   or specified as 0, then the age of the previous Full backup is not
+   considered.
+
+\label{PreferMountedVolumes}
+\item [Prefer Mounted Volumes = \lt{}yes\vb{}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), unless you are using multiple pools.
+   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.
+
+   Despite the above, we recommend against setting this directive to
+   {\bf no} since
+   it tends to add a lot of swapping of Volumes between the different
+   drives and can easily lead to deadlock situations in the Storage
+   daemon. We will accept bug reports against it, but we cannot guarantee
+   that we will be able to fix the problem in a reasonable time.
+
+   A better alternative for using multiple drives is to use multiple
+   pools so that Bacula will be forced to mount Volumes from those Pools
+   on different drives.
+
+\item [Prune Jobs = \lt{}yes\vb{}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\vb{}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\vb{}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}
+
+   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.  By default, the
+   program is executed on the Client side like in \texttt{ClientRunXXXJob}.
+
+   \textbf{Console} options are special commands that are sent to the director instead
+   of the OS. At this time, console command ouputs are redirected to log with
+   the jobid 0.
+
+   You can use following console command : \texttt{delete}, \texttt{disable},
+   \texttt{enable}, \texttt{estimate}, \texttt{list}, \texttt{llist},
+   \texttt{memory}, \texttt{prune}, \texttt{purge}, \texttt{reload},
+   \texttt{status}, \texttt{setdebug}, \texttt{show}, \texttt{time},
+   \texttt{trace}, \texttt{update}, \texttt{version}, \texttt{.client},
+   \texttt{.jobs}, \texttt{.pool}, \texttt{.storage}.  See console chapter for
+   more information. You need to specify needed information on command line, nothing
+   will be prompted. Example :
+
+\begin{verbatim}
+   Console = "prune files client=%c"
+   Console = "update stats age=3"
+\end{verbatim}
+
+   You can specify more than one Command/Console option per RunScript.
+
+   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|\textsl{AfterVSS} & {\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
+Console          &       &          & Console command\\
+\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 (Only on director side)
+\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 Notes about ClientRunBeforeJob}
+
+   For compatibility reasons, with this shortcut, the command is executed
+   directly when the client recieve it. And if the command is in error, other
+   remote runscripts will be discarded. To be sure that all commands will be
+   sent and executed, you have to use RunScript syntax.
+
+   {\bf Special Windows Considerations}
+
+   You can run scripts just after snapshots initializations with
+   \textsl{AfterVSS} keyword.
+
+   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\vb{}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\vb{}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\vb{}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.  This is the default value.
+
+\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\vb{}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\vb{}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, unless Allow Mixed Priority is set.
+
+   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{AllowMixedPriority}
+\item [Allow Mixed Priority = \lt{}yes\vb{}no\gt{}]
+\index[dir]{Allow Mixed Priority}
+   This directive is only implemented in version 2.5 and later.  When
+   set to {\bf yes} (default {\bf no}), this job may run even if lower
+   priority jobs are already running.  This means a high priority job
+   will not have to wait for other jobs to finish before starting.
+   The scheduler will only mix priorities when all running jobs have
+   this set to true.
+
+   Note that only higher priority jobs will start early.  Suppose the
+   director will allow two concurrent jobs, and that two jobs with
+   priority 10 are running, with two more in the queue.  If a job with
+   priority 5 is added to the queue, it will be run as soon as one of
+   the running jobs finishes.  However, new priority 10 jobs will not
+   be run until the priority 5 job has finished.
+
+\label{WritePartAfterJob}
+\item [Write Part After Job = \lt{}yes\vb{}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.  
+
+\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\vb{}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\vb{}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> | <wday-range> |
+                    <week-keyword> <wday-keyword> |
+                    <week-keyword> <wday-range> |
+                    <daily-keyword>
+<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\vb{}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.
+
+\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\vb{}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\vb{}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\vb{}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\vb{}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{PoolScratchPool}
+\item [ScratchPool = \lt{}pool-resource-name\gt{}]
+   \index[dir]{ScrachPool}
+   \index[dir]{Directive!ScrachPool}
+   This directive permits to specify a dedicate \textsl{Scratch} for the
+   current pool. This pool will replace the special pool named \textsl{Scrach}
+   for volume selection. For more information about \textsl{Scratch} see
+   \ilink{Scratch Pool}{TheScratchPool} section of this manual. This is useful
+   when using multiple storage sharing the same mediatype or when you want to
+   dedicate volumes to a particular set of pool.
+
+\label{PoolRecyclePool}
+\item [RecyclePool = \lt{}pool-resource-name\gt{}]
+   \index[dir]{RecyclePool}
+   \index[dir]{Directive!RecyclePool}
+   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\vb{}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\vb{}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\vb{}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\vb{}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
+   a unique number that increases.  If you do not remove volumes from the
+   pool, this number should be the number of volumes plus one, but this
+   is not guaranteed. The unique number 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\vb{}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
diff --git a/docs/manuals/en/main/disk.tex b/docs/manuals/en/main/disk.tex
new file mode 100644 (file)
index 0000000..52fa4a8
--- /dev/null
@@ -0,0 +1,798 @@
+%%
+%%
+
+\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 {
+        Options {
+        compression=GZIP
+        signature=SHA1
+                }
+    File = /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 /disk1} 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 {
+       Options {
+       compression=GZIP
+       signature=SHA1 
+               }
+    File = /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
diff --git a/docs/manuals/en/main/do_echo b/docs/manuals/en/main/do_echo
new file mode 100644 (file)
index 0000000..04b9f79
--- /dev/null
@@ -0,0 +1,6 @@
+#
+# 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}
diff --git a/docs/manuals/en/main/fdl.tex b/docs/manuals/en/main/fdl.tex
new file mode 100644 (file)
index 0000000..b46cd99
--- /dev/null
@@ -0,0 +1,485 @@
+% 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.
+
+%---------------------------------------------------------------------
diff --git a/docs/manuals/en/main/filedconf.tex b/docs/manuals/en/main/filedconf.tex
new file mode 100644 (file)
index 0000000..f7a8921
--- /dev/null
@@ -0,0 +1,384 @@
+%%
+%%
+
+\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 in seconds.  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 [FDSourceAddress = \lt{}IP-Address\gt{}]
+   \index[fd]{FDSourceAddress}
+   \index[fd]{Directive!FDSourceAddress}
+   This record is optional,  and if it is specified, it will cause the File
+   daemon server (for  Storage 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 kernel will choose 
+   the best address according to the routing table (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\vb{}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
diff --git a/docs/manuals/en/main/fileset.tex b/docs/manuals/en/main/fileset.tex
new file mode 100644 (file)
index 0000000..ffcfe72
--- /dev/null
@@ -0,0 +1,1777 @@
+-%
+%%
+
+\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\vb{}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\vb{}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
+(e.g.  {\bf c:/xxx}) using Unix directory name separators
+(forward slash).  The drive letter itself can be upper or lower case (e.g.
+c:/xxx or C:/xxx).
+
+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.
+
+You find yourself using a lot of Regex statements, which will cost quite a lot
+of CPU time, we recommend you simplify them if you can, or better yet
+convert them to Wild statements which are much more efficient.
+
+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[basejob=\lt{}options\gt{}] 
+\index[dir]{basejob}
+\index[dir]{Directive!basejob}
+
+The options letters specified are used when running a {\bf Backup Level=Full}
+with BaseJobs. The options letters are the same than in the \textbf{verify=}
+option below.
+
+\item[accurate=\lt{}options\gt{}] 
+\index[dir]{accurate}
+\index[dir]{Directive!accurate}
+   The options letters specified are used  when running a {\bf Backup
+   Level=Incremental/Differential} in Accurate mode. The options
+   letters are the same than in the \textbf{verify=} option below.  
+
+\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\vb{}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.
+
+   
+\item [honor nodump flag=\lt{}yes\vb{}no\gt{}]
+\index[dir]{honornodumpflag}
+\index[dir]{Directive!honornodumpflag}
+        If your file system supports the {\bf nodump} flag (e. g. most
+        BSD-derived systems) Bacula will honor the setting of the flag
+        when this option is set to {\bf yes}. Files having this flag set
+        will not be included in the backup and will not show up in the
+        catalog. For directories with the {\bf nodump} flag set recursion
+        is turned off and the directory will be listed in the catalog.
+        If the {\bf honor nodump flag} option is not defined
+        or set to {\bf no} every file and directory will be eligible for
+        backup.
+
+
+\label{portable}
+\item [portable=yes\vb{}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\vb{}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\vb{}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\vb{}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\vb{}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\vb{}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\vb{}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\vb{}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\vb{}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.
+
+   You find yourself using a lot of Regex statements, which will cost quite a lot
+   of CPU time, we recommend you simplify them if you can, or better yet
+   convert them to Wild statements which are much more efficient.
+
+
+\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\vb{}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\vb{}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\vb{}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 [DriveType=Windows-drive-type]
+\index[dir]{DriveType}
+\index[dir]{Directive!DriveType}
+   This option is effective only on Windows machines and is
+   somewhat similar to the Unix/Linux {\bf fstype} described
+   above, except that it allows you to select what Windows
+   drive types you want to allow.  By default all drive
+   types are accepted.
+
+   The permitted drivetype names are:
+
+   removable, fixed, remote, cdrom, ramdisk
+
+   You may have multiple Driveype directives, and thus permit matching
+   of multiple drive types within a single Options resource.  If
+   the type specified on the drivetype 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 Unix/Linux systems.
+
+
+\item [hfsplussupport=yes\vb{}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 (\vb) 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. Before submitting the 
+   specified command bacula will performe 
+   \ilink{character substitution}{character substitution}.
+
+   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. Note, the {bf /dev/hd6} must be
+   the raw partition itself. Bacula will not back it up as a raw device if
+   you specify a symbolic link to a raw device such as my be created by the
+   LVM Snapshot utilities.
+
+   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.
+
+\item
+\index[general]{IgnoreDir}
+The {\bf ExcludeDirContaining = \lt{}filename\gt{}} is a directive that
+can be added to the Include section of the FileSet resource.  If the specified
+filename ({\bf filename-string}) is found on the Client in any directory to be
+backed up, the whole directory will be ignored (not backed up).  For example:
+
+\begin{verbatim}
+  # List of files to be backed up
+  FileSet {
+    Name = "MyFileSet"
+    Include {
+      Options {
+        signature = MD5
+      }
+      File = /home
+      Exclude Dir Containing = .excludeme
+    }
+  }
+\end{verbatim}
+
+But in /home, there may be hundreds of directories of users and some
+people want to indicate that they don't want to have certain
+directories backed up. For example, with the above FileSet, if
+the user or sysadmin creates a file named {\bf .excludeme} in 
+specific directories, such as
+
+\begin{verbatim}
+   /home/user/www/cache/.excludeme
+   /home/user/temp/.excludeme
+\end{verbatim}
+
+then Bacula will not backup the two directories named:
+
+\begin{verbatim}
+   /home/user/www/cache
+   /home/user/temp
+\end{verbatim}
+
+NOTE: subdirectories will not be backed up.  That is, the directive
+applies to the two directories in question and any children (be they
+files, directories, etc).
+
+\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
+
+
+The following example shows how to back up only the My Pictures directory inside
+the My Documents directory for all users in C:/Documents and Settings, i.e.
+everything matching the pattern:
+
+C:/Documents and Settings/*/My Documents/My Pictures/*
+
+To understand how this can be achieved, there are two important points to
+remember:
+
+Firstly, Bacula walks over the filesystem depth-first starting from the File =
+lines.  It stops descending when a directory is excluded, so you must include
+all ancestor directories of each directory containing files to be included.
+
+Secondly, each directory and file is compared to the Options clauses in the
+order they appear in the FileSet.  When a match is found, no further clauses
+are compared and the directory or file is either included or excluded.
+
+The FileSet resource definition below implements this by including specifc
+directories and files and excluding everything else.
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+  Name = "AllPictures"
+
+  Include {
+
+    File  = "C:/Documents and Settings"
+
+    Options {
+      signature = SHA1
+      verify = s1
+      IgnoreCase = yes
+
+      # Include all users' directories so we reach the inner ones.  Unlike a
+      # WildDir pattern ending in *, this RegExDir only matches the top-level
+      # directories and not any inner ones.
+      RegExDir = "^C:/Documents and Settings/[^/]+$"
+
+      # Ditto all users' My Documents directories.
+      WildDir = "C:/Documents and Settings/*/My Documents"
+
+      # Ditto all users' My Documents/My Pictures directories.
+      WildDir = "C:/Documents and Settings/*/My Documents/My Pictures"
+
+      # Include the contents of the My Documents/My Pictures directories and
+      # any subdirectories.
+      Wild = "C:/Documents and Settings/*/My Documents/My Pictures/*"
+    }
+
+    Options {
+      Exclude = yes
+      IgnoreCase = yes
+
+      # Exclude everything else, in particular any files at the top level and
+      # any other directories or files in the users' directories.
+      Wild = "C:/Documents and Settings/*"
+    }
+  }
+}
+\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 exclude a directory, you must not have a trailing slash on the 
+   directory name.  
+\item If 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.
diff --git a/docs/manuals/en/main/fix_tex.pl b/docs/manuals/en/main/fix_tex.pl
new file mode 100755 (executable)
index 0000000..9865757
--- /dev/null
@@ -0,0 +1,184 @@
+#!/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;
diff --git a/docs/manuals/en/main/general.tex b/docs/manuals/en/main/general.tex
new file mode 100644 (file)
index 0000000..ab0f100
--- /dev/null
@@ -0,0 +1,522 @@
+%%
+%%
+
+\chapter{What is Bacula?}
+\label{GeneralChapter}
+\index[general]{Bacula!What is }
+\index[general]{What is Bacula? }
+
+Bacula is a set of computer programs that permits the system
+administrator to manage backup, recovery, and verification of computer data
+across a network of computers of different kinds. Bacula can also run entirely
+upon a single computer and can backup to various types of media, including tape
+and disk.
+
+In technical terms, it is a
+network Client/Server based backup program. Bacula is relatively easy to use
+and efficient, while offering many advanced storage management features that
+make it easy to find and recover lost or damaged files. Due to its modular
+design, Bacula is scalable from small single computer systems to systems
+consisting of hundreds of computers located over a large network. 
+
+\section{Who Needs Bacula?}
+\index[general]{Who Needs Bacula? }
+\index[general]{Bacula!Who Needs }
+
+If you are currently using a program such as tar, dump, or
+bru to backup your computer data, and you would like a network solution, more
+flexibility, or catalog services, Bacula will most likely provide the
+additional features you want. However, if you are new to Unix systems or do
+not have offsetting experience with a sophisticated backup package, the Bacula project does not
+recommend using Bacula as it is much more difficult to setup and use than 
+tar or dump. 
+
+If you want Bacula to behave like the above mentioned simple
+programs and write over any tape that you put in the drive, then you will find
+working with Bacula difficult. Bacula is designed to protect your data
+following the rules you specify, and this means reusing a tape only
+as the last resort. It is possible to "force" Bacula to write
+over any tape in the drive, but it is easier and more efficient to use a
+simpler program for that kind of operation.
+
+If you would like a backup program that can write
+to multiple volumes (i.e. is not limited by your tape drive capacity), Bacula
+can most likely fill your needs. In addition, quite a number of Bacula users
+report that Bacula is simpler to setup and use than other equivalent programs.
+
+If you are currently using a sophisticated commercial package such as Legato
+Networker. ARCserveIT, Arkeia, or PerfectBackup+, you may be interested in
+Bacula, which provides many of the same features and is free software
+available under the GNU Version 2 software license. 
+
+\section{Bacula Components or Services}
+\index[general]{Bacula Components or Services }
+\index[general]{Services!Bacula Components or }
+
+Bacula is made up of the following five major components or services:
+Director, Console, File, Storage, and Monitor services.
+
+
+\addcontentsline{lof}{figure}{Bacula Applications}
+\includegraphics{\idir bacula-applications.eps} 
+(thanks to Aristedes Maniatis for this graphic and the one below) 
+% TODO: move the thanks to Credits section in preface
+
+\subsection*{Bacula Director}
+   \label{DirDef}
+   The Bacula Director service is the program that supervises
+   all the backup, restore, verify and archive operations.  The system
+   administrator uses the Bacula Director to schedule backups and to
+   recover files.  For more details see the Director Services Daemon Design
+   Document in the Bacula Developer's Guide.  The Director runs as a daemon
+   (or service) in the background.
+% TODO: tell reader where this Developer's Guide is at?
+   \label{UADef}
+
+\subsection*{Bacula Console}
+
+   The Bacula Console service is the program that allows the
+   administrator or user to communicate with the Bacula Director
+   Currently, the Bacula Console is available in three versions:
+   text-based console interface, GNOME-based interface, and a
+   wxWidgets graphical interface.
+   The first and simplest is to run the Console program in a shell window
+   (i.e.  TTY interface).  Most system administrators will find this
+   completely adequate.  The second version is a GNOME GUI interface that
+   is far from complete, but quite functional as it has most the
+   capabilities of the shell Console.  The third version is a wxWidgets GUI
+   with an interactive file restore.  It also has most of the capabilities
+   of the shell console, allows command completion with tabulation, and
+   gives you instant help about the command you are typing.  For more
+   details see the \ilink{Bacula Console Design Document}{_ConsoleChapter}.
+
+\subsection*{Bacula File}
+   \label{FDDef}
+   The Bacula File service (also known as the Client program) is the software
+   program that is installed on the machine to be backed up.
+   It is specific to the
+   operating system on which it runs and is responsible for providing the
+   file attributes and data when requested by the Director.  The File
+   services are also responsible for the file system dependent part of
+   restoring the file attributes and data during a recovery operation.  For
+   more details see the File Services Daemon Design Document in the Bacula
+   Developer's Guide.  This program runs as a daemon on the machine to be
+   backed up.
+   In addition to Unix/Linux File daemons, there is a Windows File daemon
+   (normally distributed in binary format).  The Windows File daemon runs
+   on current Windows versions (NT, 2000, XP, 2003, and possibly Me and
+   98).
+% TODO: maybe do not list Windows here as that is listed elsewhere
+% TODO: remove "possibly"?
+% TODO: mention Vista?
+
+\subsection*{Bacula Storage}
+   \label{SDDef}
+   The Bacula Storage services consist of the software programs that
+   perform the storage and recovery of the file attributes and data to the
+   physical backup media or volumes.  In other words, the Storage daemon is
+   responsible for reading and writing your tapes (or other storage media,
+   e.g.  files).  For more details see the Storage Services Daemon Design
+   Document in the Bacula Developer's Guide.  The Storage services runs as
+   a daemon on the machine that has the backup device (usually a tape
+   drive).
+% TODO: may switch e.g. to "for example" or "such as" as appropriate
+% TODO: is "usually" correct? Maybe "such as" instead?
+
+\subsection*{Catalog}
+   \label{DBDefinition}
+   The Catalog services are comprised of the software programs
+   responsible for maintaining the file indexes and volume databases for
+   all files backed up.  The Catalog services permit the system
+   administrator or user to quickly locate and restore any desired file.
+   The Catalog services sets Bacula apart from simple backup programs like
+   tar and bru, because the catalog maintains a record of all Volumes used,
+   all Jobs run, and all Files saved, permitting efficient restoration and
+   Volume management.  Bacula currently supports three different databases,
+   MySQL, PostgreSQL, and SQLite, one of which must be chosen when building
+   Bacula.
+
+   The three SQL databases currently supported (MySQL, PostgreSQL or
+   SQLite) provide quite a number of features, including rapid indexing,
+   arbitrary queries, and security.  Although the Bacula project plans to support other
+   major SQL databases, the current Bacula implementation interfaces only
+   to MySQL, PostgreSQL and SQLite.  For the technical and porting details
+   see the Catalog Services Design Document in the developer's documented.
+
+   The packages for MySQL and PostgreSQL are available for several operating
+   systems.
+   Alternatively, installing from the
+   source is quite easy, see the \ilink{ Installing and Configuring
+   MySQL}{MySqlChapter} chapter of this document for the details.  For
+   more information on MySQL, please see:
+   \elink{www.mysql.com}{http://www.mysql.com}.  Or see the \ilink{
+   Installing and Configuring PostgreSQL}{PostgreSqlChapter} chapter of this
+   document for the details.  For more information on PostgreSQL, please
+   see: \elink{www.postgresql.org}{http://www.postgresql.org}.
+
+   Configuring and building SQLite is even easier.  For the details of
+   configuring SQLite, please see the \ilink{ Installing and Configuring
+   SQLite}{SqlLiteChapter} chapter of this document.
+
+\subsection*{Bacula Monitor} 
+   \label{MonDef}
+   A Bacula Monitor service is the program that allows the
+   administrator or user to watch current status of Bacula Directors,
+   Bacula File Daemons and Bacula Storage Daemons.
+   Currently, only a GTK+ version is available, which works with GNOME,
+   KDE, or any window manager that supports the FreeDesktop.org system tray
+   standard. 
+
+   To perform a successful save or restore, the following four daemons must be
+   configured and running: the Director daemon, the File daemon, the Storage
+   daemon, and the Catalog service (MySQL, PostgreSQL or SQLite). 
+
+\section{Bacula Configuration}
+\index[general]{Configuration!Bacula }
+\index[general]{Bacula Configuration }
+
+In order for Bacula to understand your system, what clients you want backed
+up and how, you must create a number of configuration files containing
+resources (or objects). The following presents an overall picture of this: 
+
+\addcontentsline{lof}{figure}{Bacula Objects}
+\includegraphics{\idir bacula-objects.eps} 
+
+\section{Conventions Used in this Document}
+\index[general]{Conventions Used in this Document }
+\index[general]{Document!Conventions Used in this }
+
+Bacula is in a state of evolution, and as a consequence, this manual
+will not always agree with the code. If an item in this manual is preceded by
+an asterisk (*), it indicates that the particular feature is not implemented.
+If it is preceded by a plus sign (+), it indicates that the feature may be
+partially implemented. 
+% TODO: search for plus sign and asterisk and "IMPLEMENTED" and fix for printed book
+
+If you are reading this manual as supplied in a released version of the
+software, the above paragraph holds true. If you are reading the online
+version of the manual, 
+\elink{ www.bacula.org}{http://www.bacula.org}, please bear in
+mind that this version describes the current version in development (in the
+CVS) that may contain features not in the released version. Just the same, it
+generally lags behind the code a bit. 
+% TODO: is this still true? there are separate websites
+
+\section{Quick Start}
+\index[general]{Quick Start }
+\index[general]{Start!Quick }
+
+To get Bacula up and running quickly, the author recommends
+that you first scan the
+Terminology section below, then quickly review the next chapter entitled 
+\ilink{The Current State of Bacula}{StateChapter}, then the 
+\ilink{Getting Started with Bacula}{QuickStartChapter}, which will
+give you a quick overview of getting Bacula running. After which, you should
+proceed to the chapter on 
+\ilink{Installing Bacula}{InstallChapter}, then 
+\ilink{How to Configure Bacula}{ConfigureChapter}, and finally the
+chapter on 
+\ilink{ Running Bacula}{TutorialChapter}. 
+
+\section{Terminology}
+\index[general]{Terminology }
+
+\begin{description}
+
+\item [Administrator]
+   \index[fd]{Administrator }
+   The person or persons responsible for administrating the Bacula system. 
+
+\item [Backup]
+   \index[fd]{Backup }
+   The term Backup refers to a Bacula Job that saves files. 
+
+\item [Bootstrap File]
+   \index[fd]{Bootstrap File }
+   The bootstrap file is an ASCII file containing a compact form of
+   commands that allow Bacula or the stand-alone file extraction utility
+   (bextract) to restore the contents of one or more Volumes, for
+   example, the current state of a system just backed up.  With a bootstrap
+   file, Bacula can restore your system without a Catalog.  You can create
+   a bootstrap file from a Catalog to extract any file or files you wish.
+
+\item [Catalog]
+   \index[fd]{Catalog }
+   The Catalog is used to store summary information about the Jobs,
+   Clients, and Files that were backed up and on what Volume or Volumes.
+   The information saved in the Catalog permits the administrator or user
+   to determine what jobs were run, their status as well as the important
+   characteristics of each file that was backed up, and most importantly,
+   it permits you to choose what files to restore.
+   The Catalog is an
+   online resource, but does not contain the data for the files backed up.
+   Most of the information stored in the catalog is also stored on the
+   backup volumes (i.e.  tapes).  Of course, the tapes will also have a
+   copy of the file data in addition to the File Attributes (see below).
+
+   The catalog feature is one part of Bacula that distinguishes it from
+   simple backup and archive programs such as dump and tar.
+
+\item [Client]
+   \index[fd]{Client }
+   In Bacula's terminology, the word Client refers to the machine being
+   backed up, and it is synonymous with the File services or File daemon,
+   and quite often, it is referred to it as the FD. A Client is defined in a
+   configuration file resource.
+
+\item [Console]
+   \index[fd]{Console }
+   The program that interfaces to the Director allowing  the user or system
+   administrator to control Bacula. 
+
+\item [Daemon]
+   \index[fd]{Daemon }
+   Unix terminology for a program that is always present in  the background to
+   carry out a designated task. On Windows systems, as well as some Unix
+   systems, daemons are called Services. 
+
+\item [Directive]
+   \index[fd]{Directive }
+   The term directive is used to refer to a statement or a record within a
+   Resource in a configuration file that defines one specific setting.  For
+   example, the {\bf Name} directive defines the name of the Resource.
+
+\item [Director]
+   \index[fd]{Director }
+   The main Bacula server daemon that schedules and directs all  Bacula
+   operations. Occasionally, the project refers to the Director as DIR. 
+
+\item [Differential]
+   \index[fd]{Differential }
+   A backup that includes all files changed since the last  Full save started.
+   Note, other backup programs may define this differently. 
+
+\item [File Attributes]
+   \index[fd]{File Attributes }
+   The File Attributes are all the information  necessary about a file to
+   identify it and all its properties such as  size, creation date, modification
+   date, permissions, etc. Normally, the  attributes are handled entirely by
+   Bacula so that the user never  needs to be concerned about them. The
+   attributes do not include the  file's data. 
+
+\item [File Daemon]
+   \index[fd]{File Daemon }
+   The daemon running on the client  computer to be backed up. This is also
+   referred to as the File  services, and sometimes as the Client services or the
+   FD. 
+
+\label{FileSetDef}
+\item [FileSet]
+\index[fd]{a name }
+   A FileSet is a Resource contained in a configuration file that defines
+   the files to be backed up.  It consists of a list of included files or
+   directories, a list of excluded files, and how the file is to be stored
+   (compression, encryption, signatures).  For more details, see the
+   \ilink{FileSet Resource definition}{FileSetResource} in the Director
+   chapter of this document.
+
+\item [Incremental]
+   \index[fd]{Incremental }
+   A backup that includes all files changed since the  last Full, Differential,
+   or Incremental backup started. It is normally  specified on the {\bf Level}
+   directive within the Job resource  definition, or in a Schedule resource. 
+
+\label{JobDef}
+\item [Job]
+\index[fd]{a name }
+   A Bacula Job is a configuration resource that defines the work that
+   Bacula must perform to backup or restore a particular Client.  It
+   consists of the {\bf Type} (backup, restore, verify, etc), the {\bf
+   Level} (full, incremental,...), the {\bf FileSet}, and {\bf Storage} the
+   files are to be backed up (Storage device, Media Pool).  For more
+   details, see the \ilink{Job Resource definition}{JobResource} in the
+   Director chapter of this document.
+% TODO: clean up "..." for book
+
+\item [Monitor]
+   \index[fd]{Monitor }
+   The program that interfaces to all the daemons  allowing the user or
+   system administrator to monitor Bacula status. 
+
+\item [Resource]
+   \index[fd]{Resource }
+   A resource is a part of a configuration file that defines a specific
+   unit of information that is available to Bacula.  It consists of several
+   directives (individual configuration statements).  For example, the {\bf
+   Job} resource defines all the properties of a specific Job: name,
+   schedule, Volume pool, backup type, backup level, ...
+% TODO: clean up "..." for book
+
+\item [Restore]
+   \index[fd]{Restore }
+   A restore is a configuration resource that describes the operation of
+   recovering a file from backup media.  It is the inverse of a save,
+   except that in most cases, a restore will normally have a small set of
+   files to restore, while normally a Save backs up all the files on the
+   system.  Of course, after a disk crash, Bacula can be called upon to do
+   a full Restore of all files that were on the system.
+% TODO: Why? Why say "Of course"??
+
+% TODO: define "Save"
+% TODO: define "Full"
+
+\item [Schedule]
+   \index[fd]{Schedule }
+   A Schedule is a configuration resource that defines when the Bacula Job
+   will be scheduled for execution.  To use the Schedule, the Job resource
+   will refer to the name of the Schedule.  For more details, see the
+   \ilink{Schedule Resource definition}{ScheduleResource} in the Director
+   chapter of this document.
+
+\item [Service]
+   \index[fd]{Service }
+   This is a program that remains permanently in memory awaiting
+   instructions.  In Unix environments, services are also known as
+   {\bf daemons}. 
+
+\item [Storage Coordinates]
+   \index[fd]{Storage Coordinates }
+   The information returned from the Storage Services that uniquely locates
+   a file on a backup medium.  It consists of two parts: one part pertains
+   to each file saved, and the other part pertains to the whole Job.
+   Normally, this information is saved in the Catalog so that the user
+   doesn't need specific knowledge of the Storage Coordinates.  The Storage
+   Coordinates include the File Attributes (see above) plus the unique
+   location of the information on the backup Volume.
+
+\item [Storage Daemon]
+   \index[fd]{Storage Daemon }
+   The Storage daemon, sometimes referred to as the SD, is the code that
+   writes the attributes and data to a storage Volume (usually a tape or
+   disk).
+
+\item [Session]
+   \index[sd]{Session }
+   Normally refers to the internal conversation between the File daemon and
+   the Storage daemon.  The File daemon opens a {\bf session} with the
+   Storage daemon to save a FileSet or to restore it.  A session has a
+   one-to-one correspondence to a Bacula Job (see above).
+
+\item [Verify]
+   \index[sd]{Verify }
+   A verify is a job that compares the current file attributes to the
+   attributes that have previously been stored in the Bacula Catalog.  This
+   feature can be used for detecting changes to critical system files
+   similar to what a file integrity checker like Tripwire does.
+   One of the major advantages of
+   using Bacula to do this is that on the machine you want protected such
+   as a server, you can run just the File daemon, and the Director, Storage
+   daemon, and Catalog reside on a different machine.  As a consequence, if
+   your server is ever compromised, it is unlikely that your verification
+   database will be tampered with.
+
+   Verify can also be used to check that the most recent Job data written
+   to a Volume agrees with what is stored in the Catalog (i.e.  it compares
+   the file attributes), *or it can check the Volume contents against the
+   original files on disk.
+
+\item [*Archive]
+   \index[fd]{*Archive }
+   An Archive operation is done after a Save, and it  consists of removing the
+   Volumes on which data is saved from active  use. These Volumes are marked as
+   Archived, and may no longer be  used to save files. All the files contained
+   on an Archived Volume  are removed from the Catalog. NOT YET IMPLEMENTED. 
+
+\item [Retention Period]
+   \index[fd]{Retention Period }
+   There are various kinds of retention periods that Bacula recognizes.
+   The most important are the {\bf File} Retention Period, {\bf Job}
+   Retention Period, and the {\bf Volume} Retention Period.  Each of these
+   retention periods applies to the time that specific records will be kept
+   in the Catalog database.  This should not be confused with the time that
+   the data saved to a Volume is valid.
+
+   The File Retention Period determines the time that File records are kept
+   in the catalog database.  This period is important for two reasons: the
+   first is that as long as File records remain in the database, you
+   can "browse" the database with a console program and restore any
+   individual file. Once the File records are removed or pruned from the
+   database, the individual files of a backup job can no longer be
+   "browsed".  The second reason for carefully choosing the File Retention
+   Period is because the volume of
+   the database File records use the most storage space in the
+   database.  As a consequence, you must ensure that regular "pruning" of
+   the database file records is done to keep your database from growing 
+   too large. (See the Console {\bf prune}
+   command for more details on this subject).
+
+   The Job Retention Period is the length of time that Job records will be
+   kept in the database.  Note, all the File records are tied to the Job
+   that saved those files.  The File records can be purged leaving the Job
+   records.  In this case, information will be available about the jobs
+   that ran, but not the details of the files that were backed up.
+   Normally, when a Job record is purged, all its File records will also be
+   purged.
+
+   The Volume Retention Period is the minimum of time that a Volume will be
+   kept before it is reused.  Bacula will normally never overwrite a Volume
+   that contains the only backup copy of a file.  Under ideal conditions,
+   the Catalog would retain entries for all files backed up for all current
+   Volumes.  Once a Volume is overwritten, the files that were backed up on
+   that Volume are automatically removed from the Catalog.  However, if
+   there is a very large pool of Volumes or a Volume is never overwritten,
+   the Catalog database may become enormous.  To keep the Catalog to a
+   manageable size, the backup information should be removed from the
+   Catalog after the defined File Retention Period.  Bacula provides the
+   mechanisms for the catalog to be automatically pruned according to the
+   retention periods defined.
+
+\item [Scan]
+   \index[sd]{Scan }
+   A Scan operation causes the contents of a Volume or a series of Volumes
+   to be scanned.  These Volumes with the information on which files they
+   contain are restored to the Bacula Catalog.  Once the information is
+   restored to the Catalog, the files contained on those Volumes may be
+   easily restored.  This function is particularly useful if certain
+   Volumes or Jobs have exceeded their retention period and have been
+   pruned or purged from the Catalog.  Scanning data from Volumes into the
+   Catalog is done by using the {\bf bscan} program.  See the \ilink{ bscan
+   section}{bscan} of the Bacula Utilities Chapter of this manual for more
+   details.
+
+\item [Volume]
+   \index[sd]{Volume }
+   A Volume is an archive unit, normally a tape or a named disk file where
+   Bacula stores the data from one or more backup jobs.  All Bacula Volumes
+   have a software label written to the Volume by Bacula so that it
+   identifies what Volume it is really reading.  (Normally there should be
+   no confusion with disk files, but with tapes, it is easy to mount the
+   wrong one.)
+\end{description}
+
+\section{What Bacula is Not}
+\index[general]{What Bacula is Not}
+
+Bacula is a backup, restore and verification program and is not a
+complete disaster recovery system in itself, but it can be a key part of one
+if you plan carefully and follow the instructions included in the 
+\ilink{ Disaster Recovery}{RescueChapter} Chapter of this manual. 
+
+With proper planning, as mentioned in the Disaster Recovery chapter,
+Bacula can be a central component of your disaster recovery system. For
+example, if you have created an emergency boot disk, and/or a Bacula Rescue disk to
+save the current partitioning information of your hard disk, and maintain a
+complete Bacula backup, it is possible to completely recover your system from
+"bare metal" that is starting from an empty disk. 
+
+If you have used the {\bf WriteBootstrap} record in your job or some other
+means to save a valid bootstrap file, you will be able to use it to extract
+the necessary files (without using the catalog or manually searching for the
+files to restore). 
+
+\section{Interactions Between the Bacula Services}
+\index[general]{Interactions Between the Bacula Services}
+\index[general]{Services!Interactions Between the Bacula}
+
+The following block diagram shows the typical interactions between the Bacula
+Services for a backup job. Each block represents in general a separate process
+(normally a daemon). In general, the Director oversees the flow of
+information. It also maintains the Catalog. 
+
+\addcontentsline{lof}{figure}{Interactions between Bacula Services}
+\includegraphics{\idir flow.eps} 
diff --git a/docs/manuals/en/main/gpl.tex b/docs/manuals/en/main/gpl.tex
new file mode 100644 (file)
index 0000000..a368afc
--- /dev/null
@@ -0,0 +1,420 @@
+%%
+%%
+
+\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 
diff --git a/docs/manuals/en/main/index.perl b/docs/manuals/en/main/index.perl
new file mode 100644 (file)
index 0000000..bc4e1b6
--- /dev/null
@@ -0,0 +1,564 @@
+# 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.
diff --git a/docs/manuals/en/main/install.tex b/docs/manuals/en/main/install.tex
new file mode 100644 (file)
index 0000000..83b62a9
--- /dev/null
@@ -0,0 +1,1745 @@
+%%
+%%
+
+\chapter{Installing Bacula}
+\label{InstallChapter}
+\index[general]{Bacula!Installing}
+\index[general]{Installing Bacula}
+
+In general, you will need the Bacula source release, and if you want to run
+a Windows client, you will need the Bacula Windows binary release.
+However, Bacula needs certain third party packages (such as {\bf MySQL},
+{\bf PostgreSQL}, or {\bf SQLite} to build and run
+properly depending on the
+options you specify.  Normally, {\bf MySQL} and {\bf PostgreSQL} are
+packages that can be installed on your distribution.  However, if you do
+not have them, to simplify your task, we have combined a number of these
+packages into three {\bf depkgs} releases (Dependency Packages).  This can
+vastly simplify your life by providing you with all the necessary packages
+rather than requiring you to find them on the Web, load them, and install
+them.
+
+\section{Source Release Files}
+\index[general]{Source Files}
+\index[general]{Release Files}
+ Beginning with Bacula 1.38.0, the source code has been broken into
+ four separate tar files each corresponding to a different module in
+ the Bacula SVN. The released files are:
+
+\begin{description}
+\item [bacula-3.0.3.tar.gz]
+  This is the primary source code release for Bacula. On each
+  release the version number (3.0.3) will be updated.
+
+\item [bacula-docs-3.0.3.tar.gz]
+  This file contains a copy of the docs directory with the
+  documents prebuild. English HTML directory, single HTML
+  file, and pdf file. The French and German translations
+  are in progress, but are not built.
+
+\item [bacula-gui-3.0.3.tar.gz]
+  This file contains the non-core GUI programs. Currently,
+  it contains bacula-web, a PHP program for producing management
+  viewing of your Bacula job status in a browser; and bimagemgr
+  a browser program for burning CDROM images with Bacula Volumes.
+
+\item [bacula-rescue-3.0.3.tar.gz]
+  This is the Bacula Rescue CDROM code. Note, the version number
+  of this package is not tied to the Bacula release version, so
+  it will be different.  Using this code, you can burn a CDROM
+  with your system configuration and containing a statically
+  linked version of the File daemon. This can permit you to easily
+  repartition and reformat your hard disks and reload your
+  system with Bacula in the case of a hard disk failure.
+  Unfortunately this rescue disk does not properly boot for
+  all Linux distributions. The problem is that the boot procedure
+  can vary significantly between distributions, and even within
+  a distribution, they are a moving target.
+
+  This package evolves slower than the Bacula source code,
+  so there may not always be a new release of the rescue package when
+  making minor updates to the Bacula code. For example, when releasing
+  Bacula version 3.0.3, the rescue package may still be at a prior
+  version if there were no updates.
+
+\item [winbacula-3.0.3.exe]
+  This file is the 32 bit Windows installer for installing
+  the Windows client (File daemon) on a Windows machine.
+  This client will also run on 64 bit Windows machines.
+  Beginning with Bacula version 1.39.20, this executable will
+  also optionally load the Win32 Director and the Win32 
+  Storage daemon.
+
+\item [win64bacula-3.0.3.exe]
+  This file is the 64 bit Windows installer for installing
+  the Windows client (File daemon) on a Windows machine.
+  This client will only run on 64 bit Windows OS machines.
+  It will not run on 32 bit machines or 32 bit Windows OSes.
+  The win64bacula release is necessary for Volume Shadow
+  Copy (VSS) to work on Win64 OSes.  This installer
+  installs only the FD, the Director and Storage daemon
+  are not included.
+
+\end{description}
+
+\label{upgrading1}
+\section{Upgrading Bacula}
+\index[general]{Bacula!Upgrading}
+\index[general]{Upgrading Bacula}
+\index[general]{Upgrading}
+
+If you are upgrading from one Bacula version to another, you should first
+carefully read the ReleaseNotes of all major versions between your current
+version and the version to which you are upgrading.  In many upgrades,
+especially for minor patch upgrades (e.g. between 3.0.0 and 3.0.1) there
+will be no database upgrade, and hence the process is rather simple.
+
+With version 3.0.0 and later, you {\bf must} ensure that on any one
+machine that all components of Bacula are running on exactly the
+same version.  Prior to version 3.0.0, it was possible to run a 
+lower level FD with a newer Director and SD.  This is no longer the
+case.  
+
+As always, we attempt to support older File daemons. This avoids the
+need to do a simultaneous upgrade of many machines. For exactly what
+older versions of the FD are supported, please see the ReleaseNotes 
+for the new version.  In any case, you must always upgrade both the
+Director and the Storage daemon at the same time, and you must also
+upgrade any File daemon that is running on the same machine as a Director
+or a Storage daemon (see the prior paragraph).
+
+If the Bacula catalog
+database has been upgraded (as it is almost every major release), you will
+either need to reinitialize your database starting from scratch (not
+normally a good idea), or save an ASCII copy of your database, then proceed
+to upgrade it. If you are upgrading two major versions (e.g. 1.36 to 2.0)
+then life will be more complicated because you must do two database
+upgrades. See below for more on this.
+
+Upgrading the catalog is normally done after Bacula is build and installed
+by:
+
+\begin{verbatim}
+cd <installed-scripts-dir> (default /etc/bacula)
+./update_bacula_tables
+\end{verbatim}
+
+This update script can also be find in the Bacula source src/cats
+directory.
+
+If there are several database upgrades between your version and the
+version to which you are upgrading, you will need to apply each database
+upgrade script. For your convenience, you can find all the old upgrade scripts
+in the {\bf upgradedb} directory of the source code. You will need to edit the
+scripts to correspond to your system configuration. The final upgrade script,
+if any, can be applied as noted above.
+
+If you are upgrading from one major version to another, you will need to
+replace all your components at the same time as generally the inter-daemon
+protocol will change. However, within any particular release (e.g. version
+1.32.x) unless there is an oversight or bug, the daemon protocol will not
+change. If this is confusing, simply read the ReleaseNotes very carefully as
+they will note if all daemons must be upgraded at the same time. 
+
+Finally, please note that in general it is not necessary or desirable
+to do a {\bf make uninstall} before doing an upgrade providing you are careful
+not to change the installation directories. In fact, if you do so, you will 
+most likely delete all your conf files, which could be disastrous.
+The normal procedure during an upgrade is simply:
+
+\begin{verbatim}
+./configure (your options)
+make
+make install
+\end{verbatim}
+
+In general none of your existing .conf or .sql files will be overwritten,
+and you must do both the {\bf make} and {\bf make install}  commands, a
+{\bf make install} without the preceding {\bf make} will not work.
+  
+For additional information on upgrading, please see the \ilink{Upgrading Bacula
+Versions}{upgrading} in the Tips chapter of this manual.
+
+\section{Releases Numbering}
+\index[general]{Release Numbering}
+\index[general]{Version Numbering}
+Every Bacula release whether beta or production has a different number  
+as well as the date of the release build. The numbering system follows
+traditional Open Source conventions in that it is of the form.
+
+\begin{verbatim}
+major.minor.release
+\end{verbatim}
+
+For example:
+\begin{verbatim}
+1.38.11
+\end{verbatim}
+
+where each component (major, minor, patch) is a number.
+The major number is currently 1 and normally does not change
+very frequently.  The minor number starts at 0 and increases
+each for each production release by 2 (i.e. it is always an
+even number for a production release), and the patch number is
+starts at zero each time the minor number changes.  The patch
+number is increased each time a bug fix (or fixes) is released
+to production.
+
+So, as of this date (10 September 2006), the current production Bacula
+release is version 1.38.11.  If there are bug fixes, the next release
+will be 1.38.12 (i.e. the patch number has increased by one).
+
+For all patch releases where the minor version number does not change,
+the database and all the daemons will be compatible.  That means that
+you can safely run a 1.38.0 Director with a 1.38.11 Client.  Of course,
+in this case, the Director may have bugs that are not fixed. Generally,
+within a minor release (some minor releases are not so minor), all
+patch numbers are officially released to production. This means that while
+the current Bacula version is 1.38.11, versions 1.38.0, 1.38.1, ... 1.38.10
+have all been previously released.
+
+When the minor number is odd, it indicates that the package is under 
+development and thus may not be stable. For example, while the current 
+production release of Bacula is currently 1.38.11, the current development
+version is 1.39.22. All patch versions of the development code are 
+available in the SVN (source repository).  However, not all patch versions
+of the development code (odd minor version) are officially released. When
+they are released, they are released as beta versions (see below for a
+definition of what beta means for Bacula releases).                     
+
+In general when the minor number increases from one production release
+to the next (i.e. 1.38.x to 1.40.0), the catalog database must be upgraded,
+the Director and Storage daemon must always be on the same minor release
+number, and often (not always), the Clients must also be on the same minor
+release. As often as possible, we attempt to make new releases that are
+downwards compatible with prior clients, but this is not always possible.
+You must check the release notes.  In general, you will have fewer problems
+if you always run all the components on the same minor version number (i.e.
+all either 1.38.x or 1.40.x but not mixed).
+
+
+\label{BetaReleases}
+\section*{Beta Releases}
+\index[general]{Beta Releases}
+Towards the end of the development cycle, which typically runs
+one year from a major release to another, there will be several beta
+releases of the development code prior to a production release.  
+As noted above, beta versions always have odd minor version numbers
+(e.g 1.37.x or 1.39.x). 
+The purpose of the beta releases is to allow early adopter users to test
+the new code.  Beta releases are made with the following considerations:
+
+\begin{itemize}
+\item The code passes the regression testing on FreeBSD, Linux, and Solaris
+  machines.
+
+\item There are no known major bugs, or on the rare occasion that 
+  there are, they will be documented or already in the bugs database.
+
+\item Some of the new code/features may not yet be tested.
+
+\item Bugs are expected to be found, especially in the new
+  code before the final production release.
+
+\item The code will have been run in production in at least one small
+  site (mine).
+
+\item The Win32 client will have been run in production at least
+  one night at that small site.
+
+\item The documentation in the manual is unlikely to be complete especially
+  for the new features, and the Release Notes may not be fully
+  organized.
+
+\item Beta code is not generally recommended for everyone, but
+  rather for early adopters.
+\end{itemize}
+
+
+\label{Dependency}
+\section{Dependency Packages}
+\index[general]{Dependency Packages}
+\index[general]{Packages!Dependency}
+
+As discussed above, we have combined a number of third party packages that
+Bacula might need into the {\bf depkgs} release. You can,
+of course, get the latest packages from the original authors or 
+from your operating system supplier. The locations of
+where we obtained the packages are in the README file in each package.
+However, be aware that the packages in the depkgs files have been tested by us
+for compatibility with Bacula. 
+
+Typically, a dependency package will be named {\bf depkgs-ddMMMyy.tar.gz}
+where {\bf dd} is the day we release it, {\bf MMM}
+is the abbreviated month (e.g. Jan), and {\bf yy} is the year. An actual
+example is: {\bf depkgs-24Jul09.tar.gz}. To install and build this package (if
+needed), you do the following: 
+
+\begin{enumerate}
+\item Create a {\bf bacula} directory, into which you will place  both the
+   Bacula source as well as the dependency package.  
+\item Detar the {\bf depkgs} into the {\bf bacula} directory.  
+\item cd bacula/depkgs  
+\item make 
+\end{enumerate}
+
+Although the exact composition of the dependency packages may change from time
+to time, the current makeup is the following: 
+
+\addcontentsline{lot}{table}{Dependency Packages}
+\begin{longtable}{|l|l|l|}
+ \hline 
+\multicolumn{1}{|c| }{\bf 3rd Party Package} & \multicolumn{1}{c| }{\bf depkgs}
+     & \multicolumn{1}{c| }{\bf depkgs-qt} \\
+ \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 {qt4 } & \multicolumn{1}{c| }{ } & \multicolumn{1}{c| }{X } \\
+ \hline {qwt } & \multicolumn{1}{c| }{ } & \multicolumn{1}{c| }{X } \\
+ \hline 
+\end{longtable}
+
+Note, some of these packages are quite large, so that building them can be a
+bit time consuming. The above instructions will build all the packages
+contained in the directory. However, when building Bacula, it will take only
+those pieces that it actually needs. 
+
+Alternatively, you can make just the packages that are needed. For example, 
+
+\footnotesize
+\begin{verbatim}
+cd bacula/depkgs
+make sqlite
+\end{verbatim}
+\normalsize
+
+will configure and build only the SQLite package. 
+
+You should build the packages that you will require in {\bf depkgs} a     
+prior to configuring and building Bacula, since Bacula will need
+them during the build process. 
+
+For more information on the {\bf depkgs-qt} package, please read the
+INSTALL file in the main directory of that package. If you are going to 
+build Qt4 using {\bf depkgs-qt}, you must source the {\bf qt4-paths} file
+included in the package prior to building Bacula. Please read the INSTALL
+file for more details.
+
+Even if you do not use SQLite, you might find it worthwhile to build {\bf mtx}
+because the {\bf tapeinfo} program that comes with it can often provide you
+with valuable information about your SCSI tape drive (e.g. compression,
+min/max block sizes, ...). Note, most distros provide {\bf mtx} as part of 
+their release.
+
+The {\bf depkgs1} package is depreciated and previously contained
+readline, which should be available on all operating systems.
+
+The {\bf depkgs-win32} package is deprecated and no longer used in 
+Bacula version 1.39.x and later. It was previously used to build
+the native Win32 client program, but this program is now built on Linux
+systems using cross-compiling.  All the tools and third party libraries
+are automatically downloaded by executing the appropriate scripts.  See
+src/win32/README.mingw32 for more details.
+
+\section{Supported Operating Systems}
+\label{Systems}
+\index[general]{Systems!Supported Operating}
+\index[general]{Supported Operating Systems}
+
+Please see the 
+\ilink{ Supported Operating Systems}{SupportedOSes} section
+of the QuickStart chapter of this manual. 
+
+\section{Building Bacula from Source}
+\label{Building}
+\index[general]{Source!Building Bacula from}
+\index[general]{Building Bacula from Source}
+
+The basic installation is rather simple. 
+
+\begin{enumerate}
+\item Install and build any {\bf depkgs} as noted above. This
+   should be unnecessary on most modern Operating Systems.
+
+\item Configure and install MySQL or PostgreSQL (if desired). 
+   \ilink{Installing and Configuring MySQL Phase I}{MySqlChapter} or  
+   \ilink{Installing and Configuring PostgreSQL Phase
+   I}{PostgreSqlChapter}.  If you are installing from rpms, and are
+   using MySQL, please be sure to install  {\bf mysql-devel}, so that the MySQL
+   header files are available  while compiling Bacula. In addition, 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.  
+
+   Note, if you already have a running MySQL or PostgreSQL on your system, you 
+   can skip this phase provided that you have built the thread  safe libraries.
+   And you have already installed the additional  rpms noted above.  
+
+   SQLite is not supported on Solaris. This is because it
+   frequently fails with bus errors.  However SQLite3 may work.
+
+\item Detar the Bacula source code preferably into the {\bf bacula}  directory
+   discussed above.  
+
+\item {\bf cd} to the directory containing the source code.  
+
+\item ./configure (with appropriate options as described below). Any
+   path names you specify as options on the ./configure command line
+   must be absolute paths and not relative.
+
+\item Check the output of ./configure very carefully, especially  the Install
+   binaries and Install config directories.  If they are not correct,
+   please rerun ./configure until they  are. The output from ./configure is
+   stored in {\bf config.out}  and can be re-displayed at any time without
+   rerunning the  ./configure by doing {\bf cat config.out}.  
+
+\item If after running ./configure once, you decide to change options  and
+   re-run it, that is perfectly fine, but before re-running it,  you should run: 
+
+\footnotesize
+\begin{verbatim}
+      make distclean
+\end{verbatim}
+\normalsize
+
+so that you are sure to start from scratch and not have a  mixture of the two
+options. This is because ./configure  caches much of the information. The {\bf
+make distclean}  is also critical if you move the source directory from one 
+machine to another. If the {\bf make distclean} fails,  just ignore it and
+continue on.  
+
+\item make  
+   If you get errors while linking in the Storage daemon directory
+   (src/stored), it is probably because you have not loaded the static
+   libraries on your system.  I noticed this problem on a Solaris system.
+   To correct it, make sure that you have not added {\bf
+   {-}{-}enable-static-tools} to the {\bf ./configure} command.
+
+   If you skip this step ({\bf make}) and proceed immediately to the {\bf
+   make install} you are making two serious errors: 1.  your install will
+   fail because Bacula requires a {\bf make} before a {\bf make install}.
+   2.  you are depriving yourself of the chance to make sure there are no
+   errors before beginning to write files to your system directories.
+                                 
+
+\item make install  
+   Please be sure you have done a {\bf make} before entering this command,
+   and that everything has properly compiled and linked without errors.
+
+
+\item If you are new to Bacula, we {\bf strongly} recommend that you skip
+   the next step and use the default configuration files, then run the
+   example program in the next chapter, then come back and modify your
+   configuration files to suit your particular needs.
+
+\item Customize the configuration files for each of the three daemons 
+   (Directory, File, Storage) and for the Console program.  For the details
+   of how to do this, please see \ilink{Setting Up Bacula Configuration
+   Files}{ConfigureChapter} in the Configuration chapter of this manual.  We
+   recommend that you start by modifying the default configuration files
+   supplied, making the minimum changes necessary.  Complete customization
+   can be done after you have Bacula up and running.  Please take care when
+   modifying passwords, which were randomly generated, and the {\bf Name}s
+   as the passwords and names must agree between the configuration files
+   for security reasons.  
+
+\label{CreateDatabase}
+\item Create the Bacula MySQL database and tables
+   (if using MySQL)
+      \ilink{Installing and Configuring MySQL Phase II}{mysql_phase2} or 
+      create the Bacula PostgreSQL database and tables  
+   \ilink{Configuring PostgreSQL
+   II}{PostgreSQL_configure} or alternatively  if you are using
+   SQLite \ilink{Installing and Configuring SQLite Phase II}{phase2}.  
+
+\item Start Bacula ({\bf ./bacula start}) Note. the next chapter  shows you
+   how to do this in detail.  
+
+\item Interface with Bacula using the Console program  
+
+\item For the previous two items, please follow the instructions  in the 
+   \ilink{Running Bacula}{TutorialChapter} chapter of  this manual,
+   where you will run a simple backup and do a  restore. Do this before you make
+   heavy modifications to the  configuration files so that you are sure that
+   Bacula works  and are familiar with it. After that changing the conf files 
+   will be easier.  
+
+\item If after installing Bacula, you decide to "move it", that is  to
+   install it in a different set of directories, proceed  as follows:  
+
+\footnotesize
+\begin{verbatim}
+      make uninstall
+      make distclean
+      ./configure (your-new-options)
+      make
+      make install
+      
+\end{verbatim}
+\normalsize
+
+\end{enumerate}
+
+If all goes well, the {\bf ./configure} will correctly determine which
+operating system you are running and configure the source code appropriately.
+Currently, FreeBSD, Linux (Red Hat), and Solaris are supported. The Bacula
+client (File daemon) is reported to work with MacOS X 10.3 is if 
+readline support is not enabled (default) when building the client.       
+
+If you install Bacula on more than one system, and they are identical, you can
+simply transfer the source tree to that other system and do a "make
+install". However, if there are differences in the libraries or OS versions,
+or you wish to install on a different OS, you should start from the original
+compress tar file. If you do transfer the source tree, and you have previously
+done a ./configure command, you MUST do: 
+
+\footnotesize
+\begin{verbatim}
+make distclean
+\end{verbatim}
+\normalsize
+
+prior to doing your new ./configure. This is because the GNU autoconf tools
+cache the configuration, and if you re-use a configuration for a Linux machine
+on a Solaris, you can be sure your build will fail. To avoid this, as
+mentioned above, either start from the tar file, or do a "make distclean". 
+
+In general, you will probably want to supply a more complicated {\bf
+configure} statement to ensure that the modules you want are built and that
+everything is placed into the correct directories. 
+
+For example, on Fedora, Red Hat, or SuSE one could use the following: 
+
+\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
+
+The advantage of using the above configuration to start is that
+everything will be put into a single directory, which you can later delete
+once you have run the examples in the next chapter and learned how Bacula
+works. In addition, the above can be installed and run as non-root. 
+
+For the developer's convenience, I have added a {\bf defaultconfig} script to
+the {\bf examples} directory. This script contains the statements that you
+would normally use, and each developer/user may modify them to suit his needs.
+You should find additional useful examples in this directory as well. 
+
+The {\bf \verb:--:enable-conio} or {\bf \verb:--:enable-readline} options are useful because
+they provide a command line history and editing capability for the Console
+program. If you have included either option in the build, either the {\bf
+termcap} or the {\bf ncurses} package will be needed to link. On most
+systems, including Red Hat and SuSE, you should include the ncurses package.
+If Bacula's configure process finds the ncurses libraries, it will use
+those rather than the termcap library.
+On some systems, such as SuSE, the termcap library is not in the standard
+library directory.  As a consequence, the option may be disabled or you may
+get an error message such as:
+
+\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
+
+while building the Bacula Console. In that case, you will need to set the {\bf
+LDFLAGS} environment variable prior to building. 
+
+\footnotesize
+\begin{verbatim}
+export LDFLAGS="-L/usr/lib/termcap"
+\end{verbatim}
+\normalsize
+
+The same library requirements apply if you wish to use the readline
+subroutines for command line editing and history or
+if you are using a MySQL library that requires encryption. If you need encryption,
+you can either export the appropriate additional library options as shown
+above 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
+
+On some systems such as Mandriva, readline tends to
+gobble up prompts, which makes it totally useless. If this happens to you, use
+the disable option, or if you are using version 1.33 and above try using {\bf
+\verb:--:enable-conio} to use a built-in readline replacement. You will still need
+either the termcap or the ncurses library, but it is unlikely that the {\bf conio}
+package will gobble up prompts. 
+
+readline is no longer supported after version 1.34.  The code within Bacula
+remains, so it should be usable, and if users submit patches for it, we will
+be happy to apply them.  However, due to the fact that each version of
+readline seems to be incompatible with previous versions, and that there
+are significant differences between systems, we can no longer afford to
+support it.
+
+\section{What Database to Use?}
+\label{DB}
+\index[general]{What Database to Use?}
+\index[general]{Use!What Database to}
+
+Before building Bacula you need to decide if you want to use SQLite, MySQL, or
+PostgreSQL. If you are not already running MySQL or PostgreSQL, you might
+want to start by testing with SQLite (not supported on Solaris).
+This will greatly simplify the setup for you
+because SQLite is compiled into Bacula an requires no administration. It
+performs well and is suitable for small to medium sized installations (maximum
+10-20 machines). However, we should note that a number of users have
+had unexplained database corruption with SQLite. For that reason, we
+recommend that you install either MySQL or PostgreSQL for production
+work.
+
+If you wish to use MySQL as the Bacula catalog, please see the 
+\ilink{Installing and Configuring MySQL}{MySqlChapter} chapter of
+this manual. You will need to install MySQL prior to continuing with the
+configuration of Bacula. MySQL is a high quality database that is very
+efficient and is suitable for any sized installation. It is slightly more
+complicated than SQLite to setup and administer because it has a number of
+sophisticated features such as userids and passwords. It runs as a separate
+process, is truly professional and can manage a database of any size. 
+
+If you wish to use PostgreSQL as the Bacula catalog, please see the 
+\ilink{Installing and Configuring PostgreSQL}{PostgreSqlChapter}
+chapter of this manual. You will need to install PostgreSQL prior to
+continuing with the configuration of Bacula. PostgreSQL is very similar to
+MySQL, though it tends to be slightly more SQL92 compliant and has many more
+advanced features such as transactions, stored procedures, and the such. It
+requires a certain knowledge to install and maintain. 
+
+If you wish to use SQLite as the Bacula catalog, please see 
+\ilink{Installing and Configuring SQLite}{SqlLiteChapter} chapter of
+this manual. SQLite is not supported on Solaris.
+
+\section{Quick Start}
+\index[general]{Quick Start}
+\index[general]{Start!Quick}
+
+There are a number of options and important considerations given below
+that you can skip for the moment if you have not had any problems building
+Bacula with a simplified configuration as shown above. 
+      
+If the ./configure process is unable to find specific libraries (e.g.    
+libintl, you should ensure that the appropriate package is installed on
+your system. Alternatively, if the package is installed in a non-standard
+location (as far as Bacula is concerned), then there is generally an
+option listed below (or listed with "./configure {-}{-}help" that will
+permit you to specify the directory that should be searched. In other
+cases, there are options that will permit you to disable to feature 
+(e.g. {-}{-}disable-nls).
+
+If you want to dive right into it, we recommend you skip to the next chapter,
+and run the example program. It will teach you a lot about Bacula and as an
+example can be installed into a single directory (for easy removal) and run as
+non-root. If you have any problems or when you want to do a real installation,
+come back to this chapter and read the details presented below. 
+
+\section{Configure Options}
+\label{Options}
+\index[general]{Options!Configure}
+\index[general]{Configure Options}
+
+The following command line options are available for {\bf configure} to
+customize your installation. 
+
+\begin{description}
+\item [ {-}prefix=\lt{}patch\gt{}]
+   \index[general]{{-}prefix}
+   This option is meant to allow you to direct where the architecture
+   independent files should be placed.  However, we find this a somewhat
+   vague concept, and so we have not implemented this option other than
+   what ./configure does by default.  As a consequence, we suggest that
+   you avoid it. We have provided options that allow you to explicitly
+   specify the directories for each of the major categories of installation
+   files.
+\item [ {-}{-}sbindir=\lt{}binary-path\gt{}]
+   \index[general]{{-}{-}sbindir}
+   Defines where the Bacula  binary (executable) files will be placed during a
+   {\bf make  install} command.  
+
+\item [ {-}{-}sysconfdir=\lt{}config-path\gt{}]
+   \index[general]{{-}{-}sysconfdir}
+   Defines where the Bacula configuration files should be placed during a
+   {\bf make install} command.
+
+\item [ {-}{-}mandir=\lt{}path\gt{}]
+   \index[general]{{-}{-}mandir}
+   Note, as of Bacula version 1.39.14, the meaning of any path
+   specified on this option is change from prior versions. It
+   now specifies the top level man directory.
+   Previously the mandir specified the full path to where you
+   wanted the man files installed.
+   The man files will be installed in gzip'ed format under
+   mandir/man1 and mandir/man8 as appropriate.
+   For the install to succeed you must have {\bf gzip} installed
+   on your system.
+
+   By default, Bacula will install the Unix man pages in 
+   /usr/share/man/man1 and /usr/share/man/man8.  
+   If you wish the man page to be installed in
+   a different location, use this option to specify the path.
+   Note, the main HTML and PDF Bacula documents are in a separate
+   tar file that is not part of the source distribution.
+
+\item [ {-}{-}datadir=\lt{}path\gt{} ]
+   \index[general]{{-}{-}datadir}
+   If you translate Bacula or parts of Bacula into a different language
+   you may specify the location of the po files using the {\bf
+   {-}{-}datadir} option. You must manually install any po files as
+   Bacula does not (yet) automatically do so.
+
+\item [ {-}{-}disable-ipv6 ]
+   \index[general]{{-}{-}disable-ipv6}
+
+\item [ {-}{-}enable-smartalloc ]
+   \index[general]{{-}{-}enable-smartalloc}
+   This enables the inclusion of the Smartalloc orphaned buffer detection
+   code.  This option is highly recommended.  Because we never build
+   without this option, you may experience problems if it is not enabled.
+   In this case, simply re-enable the option.  We strongly recommend
+   keeping this option enabled as it helps detect memory leaks.  This
+   configuration parameter is used while building Bacula
+
+\item [ {-}{-}enable-bat ]
+   \label{enablebat}
+   \index[general]{{-}{-}enable-bat}
+   If you have Qt4 >= 4.3 installed on your computer including the
+   libqt4 and libqt4-devel (libqt4-dev on Debian) libraries, and you want
+   to use the Bacula Administration Tool (bat) GUI Console interface to
+   Bacula, you must specify this option.  Doing so will build everything in
+   the {\bf src/qt-console} directory.  The build with enable-bat will work
+   only with a full Bacula build (i.e. it will not work with a client-only
+   build). 
+
+   Qt4 is available on OpenSUSE 10.2, CentOS 5, Fedora, and Debian. If it
+   is not available on your system, you can download the {\bf depkgs-qt}
+   package from the Bacula Source Forge download area and build it and
+   the qwt package, both of which are needed to build bat.  See the
+   INSTALL file in that package for more details. In particular to use
+   the Qt4 built by {\bf depkgs-qt} you {bf must} source the file
+   {\bf qt4-paths}.
+
+\item [ {-}{-}with-qwt=\lt{}path\gt{} ]
+  \index[general]{{-}{-}with-qwt}
+  The qwt package is a graphics library for Qt. If it is included
+  during the building of bat, you will get one extra graphical function.
+  At the current time, we recommend not including this option when
+  building bat. The path specified must be an absolute path and
+  not relative.  
+
+  The qwt package is available for download from
+  the qwt project on Source Forge.  If you wish, you may build and 
+  install it on your system (by default in /usr/lib). 
+  If you have done so, you would specify:
+
+\begin{verbatim}
+ --with-qwt=/usr/lib/qwt-5.0.2
+\end{verbatim}
+
+  Alternatively, you can download the Bacula depkgs-qt package (currently
+  version 28Jul09) and build it, then assuming that you have put it 
+  into a directory named bacula, you would specify:
+
+\begin{verbatim}
+ --with-qwt=$HOME/bacula/depkgs-qt/qwt
+\end{verbatim}
+
+   Some packages such as Debian do not adhere to the standard of
+   naming the library libqwt.a or libqwt.so, and you will either need
+   to manually add a soft link to the name they use or use the
+   depkgs version, which handles the naming correctly.
+
+
+\item [ {-}{-}enable-batch-insert ]
+   \index[general]{{-}{-}enable-batch-insert}
+   This option enables batch inserts of the attribute records (default) in
+    the catalog database, which is much faster (10 times or more) than
+   without this option for large numbers of files. However, this option
+   will automatically be disabled if your SQL libraries are not
+   thread safe. If you find that batch mode is not enabled on your Bacula
+   installation, then your database most likely does not support threads.
+
+   SQLite2 is not thread safe.  Batch insert cannot be enabled when using
+   SQLite2
+
+   On most systems, MySQL, PostgreSQL and SQLite3 are thread safe.
+
+   To verify that your PostgreSQL is thread safe, you can try this
+   (change the path to point to your particular installed libpq.a;
+   these commands were issued on FreeBSD 6.2):
+
+\begin{verbatim}
+$ nm /usr/local/lib/libpq.a | grep PQputCopyData
+00001b08 T PQputCopyData
+$ nm /usr/local/lib/libpq.a | grep mutex
+         U pthread_mutex_lock
+         U pthread_mutex_unlock
+         U pthread_mutex_init
+         U pthread_mutex_lock
+         U pthread_mutex_unlock
+\end{verbatim}
+
+   The above example shows a libpq that contains the required function
+   PQputCopyData and is thread enabled (i.e. the pthread\_mutex* entries).
+   If you do not see PQputCopyData, your version of PostgreSQL is too old
+   to allow batch insert.  If you do not see the mutex entries, then thread
+   support has not been enabled. Our tests indicate you usually need to
+   change the configuration options and recompile/reinstall the PostgreSQL
+   client software to get thread support.
+
+   Bacula always links to the thread safe MySQL libraries.
+
+   As a default, Bacula runs SQLite3 with {\bf PRAGMA synchronous=OFF}
+   because it improves performance by more than 30 times. However, it 
+   increases the possibility of a corrupted database. If you want more
+   security, please modify src/version.h appropriately (it should be
+   obvious when you look at the file).
+
+   Running with Batch Insert turned on is recommended because it can
+   significantly improve attribute insertion times. However, it does 
+   put a significantly larger part of the work on your SQL engine, so
+   you may need to pay more attention to tuning it. In particular,   
+   Batch Insert can require large temporary table space, and consequently,
+   the default location (often /tmp) may run out of space causing errors.
+   For MySQL, the location is set in my.conf with "tmpdir".  You may also
+   want to increase the memory available to your SQL engine to further
+   improve performance during Batch Inserts.
+
+\item [ {-}{-}enable-gnome ]
+   \index[general]{{-}{-}enable-gnome}
+   If you have GNOME installed on your computer including the
+   GNOME development libraries, and you want to use the
+   GNOME GUI Console interface to Bacula, you must specify this option.
+   Doing so will build everything in the {\bf src/gnome2-console} directory.
+
+\item [ {-}{-}enable-bwx-console ]
+   \index[general]{{-}{-}enable-bwx-console}
+   If you have wxWidgets installed on your computer and you want to use the
+   wxWidgets GUI Console interface to Bacula, you must specify this option.
+   Doing so will build everything in the {\bf src/wx-console} directory.
+   This could also be useful to users who want a GUI Console and don't want
+   to install GNOME, as wxWidgets can work with GTK+, Motif or even X11
+   libraries.
+
+\item [ {-}{-}enable-tray-monitor ]
+   \index[general]{{-}{-}enable-tray-monitor}
+   If you have GTK installed on your computer, you run a graphical
+   environment or a window manager compatible with the FreeDesktop system
+   tray standard (like KDE and GNOME) and you want to use a GUI to monitor
+   Bacula daemons, you must specify this option.  Doing so will build
+   everything in the {\bf src/tray-monitor} directory. Note, due to 
+   restrictions on what can be linked with GPLed code, we were forced to
+   remove the egg code that dealt with the tray icons and replace it by
+   calls to the GTK+ API, and unfortunately, the tray icon API necessary
+   was not implemented until GTK version 2.10 or later.
+
+\item [ {-}{-}enable-static-tools]
+   \index[general]{{-}{-}enable-static-tools}
+   This option causes the linker to link the Storage daemon utility tools
+   ({\bf bls}, {\bf bextract}, and {\bf bscan}) statically.  This permits
+   using them without having the shared libraries loaded.  If you have
+   problems linking in the {\bf src/stored} directory, make sure you have
+   not enabled this option, or explicitly disable static linking by adding
+   {\bf \verb:--:disable-static-tools}.
+
+\item [ {-}{-}enable-static-fd]
+   \index[general]{{-}{-}enable-static-fd}
+   This option causes the make process to build a {\bf static-bacula-fd} in
+   addition to the standard File daemon.  This static version will include
+   statically linked libraries and is required for the Bare Metal recovery.
+   This option is largely superseded by using {\bf make static-bacula-fd}
+   from with in the {\bf src/filed} directory.  Also, the {\bf
+   \verb:--:enable-client-only} option described below is useful for just
+   building a client so that all the other parts of the program are not
+   compiled.   
+     
+   When linking a static binary, the linker needs the static versions
+   of all the libraries that are used, so frequently users will 
+   experience linking errors when this option is used. The first 
+   thing to do is to make sure you have the static glibc library 
+   installed on your system. The second thing to do is the make sure
+   you do not specify {\bf {-}{-}openssl} or {\bf {-}{-}with-python}
+   on your ./configure statement as these options require additional
+   libraries. You may be able to enable those options, but you will
+   need to load additional static libraries.
+
+
+\item [ {-}{-}enable-static-sd]
+   \index[general]{{-}{-}enable-static-sd}
+   This option causes the make process to build a {\bf static-bacula-sd} in
+   addition to the standard Storage daemon.  This static version will
+   include statically linked libraries and could be useful during a Bare
+   Metal recovery.
+
+   When linking a static binary, the linker needs the static versions
+   of all the libraries that are used, so frequently users will 
+   experience linking errors when this option is used. The first 
+   thing to do is to make sure you have the static glibc library 
+   installed on your system. The second thing to do is the make sure
+   you do not specify {\bf {-}{-}openssl} or {\bf {-}{-}with-python}
+   on your ./configure statement as these options require additional
+   libraries. You may be able to enable those options, but you will
+   need to load additional static libraries.
+
+
+\item [ {-}{-}enable-static-dir]
+   \index[general]{{-}{-}enable-static-dir}
+   This option causes the make process to build a {\bf static-bacula-dir}
+   in addition to the standard Director.  This static version will include
+   statically linked libraries and could be useful during a Bare Metal
+   recovery.
+
+   When linking a static binary, the linker needs the static versions
+   of all the libraries that are used, so frequently users will 
+   experience linking errors when this option is used. The first 
+   thing to do is to make sure you have the static glibc library 
+   installed on your system. The second thing to do is the make sure
+   you do not specify {\bf {-}{-}openssl} or {\bf {-}{-}with-python}
+   on your ./configure statement as these options require additional
+   libraries. You may be able to enable those options, but you will
+   need to load additional static libraries.
+
+
+\item [ {-}{-}enable-static-cons]
+   \index[general]{{-}{-}enable-static-cons}
+   This option causes the make process to build a {\bf static-console} and
+   a {\bf static-gnome-console} in addition to the standard console.  This
+   static version will include statically linked libraries and could be
+   useful during a Bare Metal recovery.
+
+   When linking a static binary, the linker needs the static versions
+   of all the libraries that are used, so frequently users will 
+   experience linking errors when this option is used. The first 
+   thing to do is to make sure you have the static glibc library 
+   installed on your system. The second thing to do is the make sure
+   you do not specify {\bf {-}{-}openssl} or {\bf {-}{-}with-python}
+   on your ./configure statement as these options require additional
+   libraries. You may be able to enable those options, but you will
+   need to load additional static libraries.
+
+
+\item [ {-}{-}enable-client-only]
+   \index[general]{{-}{-}enable-client-only}
+   This option causes the make process to build only the File daemon and
+   the libraries that it needs.  None of the other daemons, storage tools,
+   nor the console will be built.  Likewise a {\bf make install} will then
+   only install the File daemon.  To cause all daemons to be built, you
+   will need to do a configuration without this option.  This option
+   greatly facilitates building a Client on a client only machine.
+
+   When linking a static binary, the linker needs the static versions
+   of all the libraries that are used, so frequently users will 
+   experience linking errors when this option is used. The first 
+   thing to do is to make sure you have the static glibc library 
+   installed on your system. The second thing to do is the make sure
+   you do not specify {\bf {-}{-}openssl} or {\bf {-}{-}with-python}
+   on your ./configure statement as these options require additional
+   libraries. You may be able to enable those options, but you will
+   need to load additional static libraries.
+
+\item [ {-}{-}enable-build-dird]
+   \index[general]{{-}{-}enable-build-dird}
+   This option causes the make process to build the Director and the
+   Director's tools. By default, this option is on, but you may turn
+   it off by using {\bf {-}{-}disable-build-dird} to prevent the
+   Director from being built.
+
+\item [ {-}{-}enable-build-stored]
+   \index[general]{{-}{-}enable-build-stored}
+   This option causes the make process to build the Storage daemon.
+   By default, this option is on, but you may turn
+   it off by using {\bf {-}{-}disable-build-stored} to prevent the
+   Storage daemon from being built.
+
+
+\item [ {-}{-}enable-largefile]
+   \index[general]{{-}{-}enable-largefile}
+   This option (default) causes  Bacula to be built with 64 bit file address
+   support if it  is available on your system. This permits Bacula to read and 
+   write files greater than 2 GBytes in size. You may disable this  feature and
+   revert to 32 bit file addresses by using  {\bf \verb:--:disable-largefile}.  
+
+\item [ {-}{-}disable-nls]
+   \index[general]{{-}{-}disable-nls}
+   By default, Bacula uses the GNU Native Language Support (NLS) libraries. On
+   some machines, these libraries may not be present or may not function 
+   correctly (especially on non-Linux implementations). In such cases, you
+   may specify {\bf {-}{-}disable-nls} to disable use of those libraries.
+   In such a case, Bacula will revert to using English.
+
+\item [ {-}{-}disable-ipv6 ]
+   \index[general]{{-}{-}disable-ipv6}
+   By default, Bacula enables IPv6 protocol. On some systems, the files
+   for IPv6 may exist, but the functionality could be turned off in the
+   kernel. In that case, in order to correctly build Bacula, you will
+   explicitly need to use this option so that Bacula does not attempt
+   to reference OS function calls that do not exist.
+
+\item [ {-}{-}with-sqlite=\lt{}sqlite-path\gt{}]
+   \index[general]{{-}{-}with-sqlite}
+   This enables use of the SQLite version 2.8.x database.  The {\bf
+   sqlite-path} is not normally specified as Bacula looks for the necessary
+   components in a standard location ({\bf depkgs/sqlite}).  See
+   \ilink{Installing and Configuring SQLite}{SqlLiteChapter} chapter of
+    this manual for more details. SQLite is not supported on Solaris.
+
+   See the note below under the {-}{-}with-postgresql item.
+
+\item [ {-}{-}with-sqlite3=\lt{}sqlite3-path\gt{}]
+   \index[general]{{-}{-}with-sqlite3}
+   This enables use of the SQLite version 3.x database.  The {\bf
+   sqlite3-path} is not normally specified as Bacula looks for the
+   necessary components in a standard location ({\bf depkgs/sqlite3}).  See
+   \ilink{Installing and Configuring SQLite}{SqlLiteChapter} chapter of
+   this manual for more details. SQLite3 is not supported on Solaris.
+
+\item [ {-}{-}with-mysql=\lt{}mysql-path\gt{}]
+   \index[general]{{-}{-}with-mysql}
+   This enables building of the Catalog services for Bacula.  It assumes
+   that MySQL is running on your system, and expects it to be installed in
+   the {\bf mysql-path} that you specify.  Normally, if MySQL is installed
+   in a standard system location, you can simply use {\bf {-}{-}with-mysql}
+   with no path specification.  If you do use this option, please proceed
+   to installing MySQL in the \ilink{Installing and Configuring
+   MySQL}{MySqlChapter} chapter before proceeding with the configuration.
+
+   See the note below under the {-}{-}with-postgresql item.
+
+\item [ {-}{-}with-postgresql=\lt{}path\gt{}]
+   \index[general]{{-}{-}with-postgresql}
+   This provides an explicit path to the PostgreSQL libraries if Bacula
+   cannot find it by default.  Normally to build with PostgreSQL, you would
+   simply use {\bf {-}{-}with-postgresql}.
+
+   Note, for Bacula to be configured properly, you must specify one
+   of the four database options supported.  That is:
+   {-}{-}with-sqlite, {-}{-}with-sqlite3, {-}{-}with-mysql, or
+   {-}{-}with-postgresql, otherwise the ./configure will fail.
+
+\item [ {-}{-}with-openssl=\lt{}path\gt{}]
+   This configuration option is necessary if you want to enable TLS (ssl),
+   which encrypts the communications within       
+   Bacula or if you want to use File Daemon PKI data encryption.
+   Normally, the {\bf path} specification is not necessary since
+   the configuration searches for the OpenSSL libraries in standard system
+   locations. Enabling OpenSSL in Bacula permits secure communications
+   between the daemons and/or data encryption in the File daemon.
+   For more information on using TLS, please see the
+   \ilink{Bacula TLS -- Communications Encryption}{CommEncryption} chapter
+   of this manual.
+   For more information on using PKI data encryption, please see the
+   \ilink{Bacula PKI -- Data Encryption}{DataEncryption}
+   chapter of this manual.
+
+\item [ {-}{-}with-python=\lt{}path\gt{}]
+   \index[general]{{-}{-}with-python}
+   This option enables Bacula support for Python.  If no path is supplied,
+   configure will search the standard library locations for Python 2.2,
+   2.3, 2.4, or 2.5.  If it cannot find the library, you will need to
+   supply a path to your Python library directory.  Please see the
+   \ilink{Python chapter}{PythonChapter} for the details of using Python
+   scripting.
+
+\item [ {-}{-}with-libintl-prefix=\lt{}DIR\gt{}]
+   \index[general]{{-}{-}with-libintl-prefix}
+   This option may be used to tell Bacula to search DIR/include and
+   DIR/lib for the libintl headers and libraries needed for Native
+   Language Support (NLS).
+
+\item [ {-}{-}enable-conio]
+   \index[general]{{-}{-}enable-conio}
+   Tells Bacula to enable building the small, light weight readline
+   replacement routine.  It is generally much easier to configure than
+   readline, although, like readline, it needs either the termcap or
+   ncurses library.
+
+\item [ {-}{-}with-readline=\lt{}readline-path\gt{}]
+   \index[general]{{-}{-}with-readline}
+   Tells Bacula where {\bf readline} is installed.  Normally, Bacula will
+   find readline if it is in a standard library.  If it is not found and no
+   {-}{-}with-readline is specified, readline will be disabled.  This
+   option affects the Bacula build.  Readline provides the Console program
+   with a command line history and editing capability and is no longer
+   supported, so you are on your own if you have problems.
+
+\item [ {-}{-}enable-readline]
+   \index[general]{{-}{-}enable-readline}
+   Tells Bacula to enable readline support.  It is normally disabled due to the
+   large number of configuration  problems and the fact that the package seems to
+   change in incompatible  ways from version to version.  
+
+\item [ {-}{-}with-tcp-wrappers=\lt{}path\gt{}]
+   \index[general]{{-}{-}with-tcp-wrappers}
+   \index[general]{TCP Wrappers}
+   \index[general]{Wrappers!TCP}
+   \index[general]{libwrappers}
+   This specifies that you  want TCP wrappers (man hosts\_access(5)) compiled in.
+   The path is optional since  Bacula will normally find the libraries in the
+   standard locations.  This option affects the Bacula build.  In specifying your
+   restrictions in the {\bf /etc/hosts.allow}  or {\bf /etc/hosts.deny} files, do
+   not use the {\bf twist}  option (hosts\_options(5)) or the Bacula process will
+   be terminated. Note, when setting up your {\bf /etc/hosts.allow}
+   or {\bf /etc/hosts.deny}, you must identify the Bacula daemon in
+   question with the name you give it in your conf file rather than the
+   name of the executable.
+   
+   For more information on configuring and testing TCP wrappers, please  see the 
+   \ilink{Configuring and Testing TCP Wrappers}{wrappers}  section
+   in the Security Chapter.  
+
+   On SuSE, the libwrappers libraries needed to link Bacula are
+   contained in the tcpd-devel package. On Red Hat, the package is named
+   tcp\_wrappers.
+
+\item [ {-}{-}with-archivedir=\lt{}path\gt{} ]
+   \index[general]{{-}{-}with-archivedir}
+   The directory used for disk-based backups.  Default value is /tmp.
+   This parameter sets the default values in the bacula-dir.conf and bacula-sd.conf
+   configuration files.  For example, it sets the Where directive for the
+   default restore job and the Archive Device directive for the FileStorage
+   device.
+
+   This option is designed primarily for use in regression testing.
+   Most users can safely ignore this option.
+
+\item [ {-}{-}with-working-dir=\lt{}working-directory-path\gt{} ]
+   \index[general]{{-}{-}with-working-dir}
+   This option is mandatory and specifies a directory  into which Bacula may
+   safely place files that  will remain between Bacula executions. For example, 
+   if the internal database is used, Bacula will keep  those files in this
+   directory.  This option is only used to modify the daemon  configuration
+   files. You may also accomplish the same  thing by directly editing them later.
+   The working directory  is not automatically created by the install process, so
+   you  must ensure that it exists before using Bacula for the  first time. 
+
+\item [ {-}{-}with-base-port=\lt{}port=number\gt{}]
+   \index[general]{{-}{-}with-base-port}
+   In order to run,  Bacula needs three TCP/IP ports (one for the Bacula 
+   Console, one for the Storage daemon, and one for the File daemon).  The {\bf
+   \verb:--:with-baseport} option will automatically assign three  ports beginning at
+   the base port address specified. You may  also change the port number in the
+   resulting configuration  files. However, you need to take care that the
+   numbers  correspond correctly in each of the three daemon configuration 
+   files. The default base port is 9101, which assigns ports 9101  through 9103.
+   These ports (9101, 9102, and 9103) have been  officially assigned to Bacula by
+   IANA.  This option is only used  to modify the daemon configuration files. You
+   may also accomplish  the same thing by directly editing them later. 
+
+\item [ {-}{-}with-dump-email=\lt{}email-address\gt{}]
+   \index[general]{{-}{-}with-dump-email}
+   This option specifies  the email address where any core dumps should be set.
+   This option  is normally only used by developers.  
+
+\item [ {-}{-}with-pid-dir=\lt{}PATH\gt{}  ]
+   \index[general]{{-}{-}with-pid-dir}
+   This specifies where Bacula should place the process id  file during
+   execution. The default is: {\bf /var/run}.  This directory is not created by
+   the install process, so  you must ensure that it exists before using Bacula
+   the  first time.  
+
+\item [ {-}{-}with-subsys-dir=\lt{}PATH\gt{}]
+   \index[general]{{-}{-}with-subsys-dir}
+   This specifies where Bacula should place the subsystem lock  file during
+   execution. The default is {\bf /var/run/subsys}.  Please make sure that you do
+   not specify the same directory  for this directory and for the {\bf sbindir}
+   directory.  This directory is used only within the autostart scripts.  The
+   subsys directory is not created by the Bacula install,  so you must be sure to
+   create it before using Bacula. 
+
+\item [ {-}{-}with-dir-password=\lt{}Password\gt{}]
+   \index[general]{{-}{-}with-dir-password}
+   This option allows you to specify the password used to  access the Director
+   (normally from the Console program).  If it is not specified, configure will
+   automatically create a random  password.  
+
+\item [ {-}{-}with-fd-password=\lt{}Password\gt{} ]
+   \index[general]{{-}{-}with-fd-password}
+   This option allows you to specify the password used to  access the File daemon
+   (normally called from the Director).  If it is not specified, configure will
+   automatically create a random  password.  
+
+\item [ {-}{-}with-sd-password=\lt{}Password\gt{} ]
+   \index[general]{{-}{-}with-sd-password}
+   This option allows you to specify the password used to access the Storage daemon
+   (normally called from the Director).  If it is not specified, configure will
+   automatically create a random  password.  
+
+\item [ {-}{-}with-dir-user=\lt{}User\gt{} ]
+   \index[general]{{-}{-}with-dir-user}
+   This option allows you to specify the Userid used to run the Director.  The
+   Director must be started as root, but doesn't need to run as root, and
+   after doing preliminary initializations, it can "drop" to the UserId
+   specified on this option.  
+   If you specify this option, you must
+   create the User prior to running {\bf make install}, because the
+   working directory owner will be set to {\bf User}.
+                       
+\item [ {-}{-}with-dir-group=\lt{}Group\gt{} ]
+   \index[general]{{-}{-}with-dir-group}
+   This option allows you to specify the GroupId used to  run the Director. The
+   Director must be started as root, but  doesn't need to run as root, and  after
+   doing preliminary initializations, it can "drop"  to the GroupId specified
+   on this option. 
+   If you specify this option, you must
+   create the Group prior to running {\bf make install}, because the
+   working directory group will be set to {\bf Group}.
+
+\item [ {-}{-}with-sd-user=\lt{}User\gt{} ]
+   \index[general]{{-}{-}with-sd-user}
+   This option allows you to specify the Userid used to  run the Storage daemon.
+   The Storage daemon must be started as root, but  doesn't need to run as root,
+   and  after doing preliminary initializations, it can "drop"  to the UserId
+   specified on this option. If you use this option,  you will need to take care
+   that the Storage daemon has access  to all the devices (tape drives, ...) that
+   it needs. 
+
+\item [ {-}{-}with-sd-group=\lt{}Group\gt{} ]
+   \index[general]{{-}{-}with-sd-group}
+   This option allows you to specify the GroupId used to  run the Storage daemon.
+   The Storage daemon must be started as root, but  doesn't need to run as root,
+   and  after doing preliminary initializations, it can "drop"  to the GroupId
+   specified on this option. 
+
+\item [ {-}{-}with-fd-user=\lt{}User\gt{} ]
+   \index[general]{{-}{-}with-fd-user}
+   This option allows you to specify the Userid used to  run the File daemon. The
+   File daemon must be started as root,  and in most cases, it needs to run as
+   root, so this option is  used only in very special cases,  after doing
+   preliminary initializations, it can "drop"  to the UserId specified on this
+   option. 
+
+\item [ {-}{-}with-fd-group=\lt{}Group\gt{} ]
+   \index[general]{{-}{-}with-fd-group}
+   This option allows you to specify the GroupId used to  run the File daemon.
+   The File daemon must be started as root, and  in most cases, it must be run as
+   root, however,  after doing preliminary initializations, it can "drop"  to
+   the GroupId specified on this option. 
+
+\item [ {-}{-}with-mon-dir-password=\lt{}Password\gt{}]
+   \index[general]{{-}{-}with-mon-dir-password}
+   This option allows you to specify the password used to  access the Directory
+   from the monitor.  If it is not specified, configure will
+   automatically create a random  password.  
+
+\item [ {-}{-}with-mon-fd-password=\lt{}Password\gt{} ]
+   \index[general]{{-}{-}with-mon-fd-password}
+   This option allows you to specify the password used to  access the File daemon
+   from the Monitor.  If it is not specified, configure will
+   automatically create a random  password.  
+
+\item [ {-}{-}with-mon-sd-password=\lt{}Password\gt{} ]
+   \index[general]{{-}{-}with-mon-sd-password}
+   This option allows you to specify the password used to  access the
+   Storage daemon from the Monitor. If it is not specified, configure will
+   automatically create a random  password.  
+
+\item [ {-}{-}with-db-name=\lt{}database-name\gt{} ]
+   \index[general]{{-}{-}with-db-name}
+   This option allows you to specify the database name to be used in
+   the conf files.  The default is bacula.
+
+\item [ {-}{-}with-db-user=\lt{}database-user\gt{} ]
+   \index[general]{{-}{-}with-db-user}
+   This option allows you to specify the database user name to be used in
+   the conf files.  The default is bacula.
+
+\end{description}
+
+Note, many other options are presented when you do a {\bf ./configure
+\verb:--:help}, but they are not implemented.
+
+\section{Recommended Options for Most Systems}
+\index[general]{Systems!Recommended Options for Most}
+\index[general]{Recommended Options for Most Systems}
+
+For most systems, we recommend starting with the following options: 
+
+\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
+
+If you want to install Bacula in an installation directory rather than run it
+out of the build directory (as developers will do most of the time), you
+should also include the \verb:--:sbindir and \verb:--:sysconfdir options with appropriate
+paths. Neither are necessary if you do not use "make install" as is the case
+for most development work. The install process will create the sbindir and
+sysconfdir if they do not exist, but it will not automatically create the
+pid-dir, subsys-dir, or working-dir, so you must ensure that they exist before
+running Bacula for the first time.
+
+\section{Red Hat}
+\index[general]{Red Hat}
+
+Using 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-bat \
+  --with-qwt=$HOME/bacula/depkgs/qwt \
+  --enable-conio
+\end{verbatim}
+\normalsize
+
+or 
+
+\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
+
+or finally, a completely traditional Red Hat Linux install: 
+
+\footnotesize
+\begin{verbatim}
+CFLAGS="-g -Wall" ./configure \
+  --sbindir=/usr/sbin \
+  --sysconfdir=/etc/bacula \
+  --with-scriptdir=/etc/bacula \
+  --enable-smartalloc \
+  --enable-bat \
+  --with-qwt=$HOME/bacula/depkgs/qwt \
+  --with-mysql \
+  --with-working-dir=/var/bacula \
+  --with-pid-dir=/var/run \
+  --enable-conio
+\end{verbatim}
+\normalsize
+
+Note, Bacula assumes that /var/bacula, /var/run, and /var/lock/subsys exist so
+it will not automatically create them during the install process. 
+
+\section{Solaris}
+\index[general]{Solaris}
+
+To build Bacula from source, you will need the following installed on your
+system (they are not by default): libiconv, gcc 3.3.2, stdc++, libgcc (for
+stdc++ and gcc\_s libraries), make 3.8 or later. 
+
+You will probably also need to: Add /usr/local/bin to PATH and Add
+/usr/ccs/bin to PATH for ar. 
+
+It is possible to build Bacula on Solaris with the Solaris compiler, but
+we recommend using GNU C++ if possible.  
+
+A typical configuration command might look like:
+
+\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
+
+As mentioned above, the install process will create the sbindir and sysconfdir
+if they do not exist, but it will not automatically create the pid-dir,
+subsys-dir, or working-dir, so you must ensure that they exist before running
+Bacula for the first time.
+
+Note, you may need to install the following packages to build Bacula
+from source:
+\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
+
+If you have installed special software not normally in the Solaris
+libraries, such as OpenSSL, or the packages shown above, then you may need
+to add {\bf /usr/sfw/lib} to the library search path.  Probably the
+simplest way to do so is to run:
+
+\footnotesize
+\begin{verbatim}
+setenv LDFLAGS "-L/usr/sfw/lib -R/usr/sfw/lib"
+\end{verbatim}
+\normalsize
+
+Prior to running the ./configure command.
+
+Alternatively, you can set the LD\_LIBARY\_PATH and/or the LD\_RUN\_PATH
+environment variables appropriately.
+
+It is also possible to use the {\bf crle} program to set the library
+search path.  However, this should be used with caution.
+
+\section{FreeBSD}
+\index[general]{FreeBSD}
+
+Please see: 
+\elink{The FreeBSD Diary}{http://www.freebsddiary.org/bacula.php} for a
+detailed description on how to make Bacula work on your system. In addition,
+users of FreeBSD prior to 4.9-STABLE dated Mon Dec 29 15:18:01 2003 UTC who
+plan to use tape devices, please see the 
+\ilink{Tape Testing Chapter}{FreeBSDTapes} of this manual for
+{\bf important} information on how to configure your tape drive for
+compatibility with Bacula. 
+
+If you are using Bacula with MySQL, you should take care to compile MySQL with
+FreeBSD native threads rather than LinuxThreads, since Bacula is normally built
+with FreeBSD native threads rather than LinuxTreads. Mixing the two will
+probably not work. 
+
+\section{Win32}
+\index[general]{Win32}
+
+To install the binary Win32 version of the File daemon please see the 
+\ilink{Win32 Installation Chapter}{Win32Chapter} in this document. 
+
+\section{One File Configure Script}
+\index[general]{Script!One File Configure}
+\index[general]{One Files Configure Script}
+
+The following script could be used if you want to put everything
+in a single file:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+CFLAGS="-g -Wall" \
+  ./configure \
+    --sbindir=$HOME/bacula/bin \
+    --sysconfdir=$HOME/bacula/bin \
+    --mandir=$HOME/bacula/bin \
+    --enable-smartalloc \
+    --enable-gnome \
+    --enable-bat \
+    --with-qwt=$HOME/bacula/depkgs/qwt \
+    --enable-bwx-console \
+    --enable-tray-monitor \
+    --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@your-site.com \
+    --with-job-email=$USER@your-site.com \
+    --with-smtp-host=mail.your-site.com
+exit 0
+\end{verbatim}
+\normalsize
+
+You may also want to put the following entries in your {\bf /etc/services}
+file as it will make viewing the connections made by Bacula easier to
+recognize (i.e. netstat -a): 
+
+\footnotesize
+\begin{verbatim}
+bacula-dir      9101/tcp
+bacula-fd       9102/tcp
+bacula-sd       9103/tcp
+\end{verbatim}
+\normalsize
+
+\section{Installing Bacula}
+\index[general]{Bacula!Installing}
+\index[general]{Installing Bacula}
+
+Before setting up your configuration files, you will want to install Bacula in
+its final location. Simply enter: 
+
+\footnotesize
+\begin{verbatim}
+make install
+\end{verbatim}
+\normalsize
+
+If you have previously installed Bacula, the old binaries will be overwritten,
+but the old configuration files will remain unchanged, and the "new"
+configuration files will be appended with a {\bf .new}. Generally if you have
+previously installed and run Bacula you will want to discard or ignore the
+configuration files with the appended {\bf .new}. 
+
+\section{Building a File Daemon or Client}
+\index[general]{Client!Building a File Daemon or}
+\index[general]{Building a File Daemon or Client}
+
+If you run the Director and the Storage daemon on one machine and you wish to
+back up another machine, you must have a copy of the File daemon for that
+machine. If the machine and the Operating System are identical, you can simply
+copy the Bacula File daemon binary file {\bf bacula-fd} as well as its
+configuration file {\bf bacula-fd.conf} then modify the name and password in
+the conf file to be unique. Be sure to make corresponding additions to the
+Director's configuration file ({\bf bacula-dir.conf}). 
+
+If the architecture or the OS level are different, you will need to build a
+File daemon on the Client machine. To do so, you can use the same {\bf
+./configure} command as you did for your main program, starting either from a
+fresh copy of the source tree, or using {\bf make\ distclean} before the {\bf
+./configure}. 
+
+Since the File daemon does not access the Catalog database, you can remove
+the {\bf \verb:--:with-mysql} or {\bf \verb:--:with-sqlite} options, then
+add {\bf \verb:--:enable-client-only}.  This will compile only the
+necessary libraries and the client programs and thus avoids the necessity
+of installing one or another of those database programs to build the File
+daemon.  With the above option, you simply enter {\bf make} and just the
+client will be built.
+
+\label{autostart}
+\section{Auto Starting the Daemons}
+\index[general]{Daemons!Auto Starting the}
+\index[general]{Auto Starting the Daemons}
+
+If you wish the daemons to be automatically started and stopped when your
+system is booted (a good idea), one more step is necessary. First, the
+./configure process must recognize your system -- that is it must be a
+supported platform and not {\bf unknown}, then you must install the platform
+dependent files by doing: 
+
+\footnotesize
+\begin{verbatim}
+(become root)
+make install-autostart
+\end{verbatim}
+\normalsize
+
+Please note, that the auto-start feature is implemented only on systems
+that we officially support (currently, FreeBSD, Red Hat/Fedora Linux, and
+Solaris), and has only been fully tested on Fedora Linux.
+
+The {\bf make install-autostart} will cause the appropriate startup scripts
+to be installed with the necessary symbolic links.  On Red Hat/Fedora Linux
+systems, these scripts reside in {\bf /etc/rc.d/init.d/bacula-dir} {\bf
+/etc/rc.d/init.d/bacula-fd}, and {\bf /etc/rc.d/init.d/bacula-sd}.  However
+the exact location depends on what operating system you are using.
+
+If you only wish to install the File daemon, you may do so with: 
+
+\footnotesize
+\begin{verbatim}
+make install-autostart-fd
+\end{verbatim}
+\normalsize
+
+\section{Other Make Notes}
+\index[general]{Notes!Other Make}
+\index[general]{Other Make Notes}
+
+To simply build a new executable in any directory, enter: 
+
+\footnotesize
+\begin{verbatim}
+make
+\end{verbatim}
+\normalsize
+
+To clean out all the objects and binaries (including the files named 1, 2, or
+3, which are development temporary files), enter: 
+
+\footnotesize
+\begin{verbatim}
+make clean
+\end{verbatim}
+\normalsize
+
+To really clean out everything for distribution, enter: 
+
+\footnotesize
+\begin{verbatim}
+make distclean
+\end{verbatim}
+\normalsize
+
+note, this cleans out the Makefiles and is normally done from the top level
+directory to prepare for distribution of the source. To recover from this
+state, you must redo the {\bf ./configure} in the top level directory, since
+all the Makefiles will be deleted. 
+
+To add a new file in a subdirectory, edit the Makefile.in in that directory,
+then simply do a {\bf make}. In most cases, the make will rebuild the Makefile
+from the new Makefile.in. In some case, you may need to issue the {\bf make} a
+second time. In extreme cases, cd to the top level directory and enter: {\bf
+make Makefiles}. 
+
+To add dependencies: 
+
+\footnotesize
+\begin{verbatim}
+make depend
+\end{verbatim}
+\normalsize
+
+The {\bf make depend} appends the header file dependencies for each of the
+object files to Makefile and Makefile.in. This command should be done in each
+directory where you change the dependencies. Normally, it only needs to be run
+when you add or delete source or header files. {\bf make depend} is normally
+automatically invoked during the configuration process. 
+
+To install: 
+
+\footnotesize
+\begin{verbatim}
+make install
+\end{verbatim}
+\normalsize
+
+This not normally done if you are developing Bacula, but is used if you are
+going to run it to backup your system. 
+
+After doing a {\bf make install} the following files will be installed on your
+system (more or less). The exact files and location (directory) for each file
+depends on your {\bf ./configure} command (e.g. bgnome-console and
+bgnome-console.conf are not installed if you do not configure GNOME. Also, if
+you are using SQLite instead of MySQL, some of the files will be different). 
+
+NOTE: it is quite probable that this list is out of date.  But it is a
+starting point.
+
+\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
+bgnome-console
+bgnome-console.conf
+make_bacula_tables
+make_catalog_backup
+make_mysql_tables
+mtx-changer
+query.sql
+bsmtp
+startmysql
+stopmysql
+bwx-console
+bwx-console.conf
+9 man pages
+\end{verbatim}
+\normalsize
+
+\label{monitor}
+
+\section{Installing Tray Monitor}
+\index[general]{Monitor!Installing Tray}
+\index[general]{Installing Tray Monitor}
+
+The Tray Monitor is already installed if you used the {\bf
+\verb:--:enable-tray-monitor} configure option and ran {\bf make install}.
+
+As you don't run your graphical environment as root (if you do, you should
+change that bad habit), don't forget to allow your user to read {\bf
+tray-monitor.conf}, and to execute {\bf bacula-tray-monitor} (this is not a
+security issue).
+
+Then log into your graphical environment (KDE, GNOME or something else), run
+{\bf bacula-tray-monitor} as your user, and see if a cassette icon appears
+somewhere on the screen, usually on the task bar.
+If it doesn't, follow the instructions below related to your environment or
+window manager. 
+
+\subsection{GNOME}
+\index[general]{GNOME}
+
+System tray, or notification area if you use the GNOME terminology, has been
+supported in GNOME since version 2.2. To activate it, right-click on one of
+your panels, open the menu {\bf Add to this Panel}, then {\bf Utility} and
+finally click on {\bf Notification Area}. 
+
+\subsection{KDE}
+\index[general]{KDE}
+
+System tray has been supported in KDE since version 3.1. To activate it,
+right-click on one of your panels, open the menu {\bf Add}, then {\bf Applet}
+and finally click on {\bf System Tray}. 
+
+\subsection{Other window managers}
+\index[general]{Managers!Other window}
+\index[general]{Other window managers}
+
+Read the documentation to know if the Freedesktop system tray standard is
+supported by your window manager, and if applicable, how to activate it. 
+
+\section{Modifying the Bacula Configuration Files}
+\index[general]{Modifying the Bacula Configuration Files}
+\index[general]{Files!Modifying the Bacula Configuration}
+
+See the chapter 
+\ilink{Configuring Bacula}{ConfigureChapter} in this manual for
+instructions on how to set Bacula configuration files. 
diff --git a/docs/manuals/en/main/latex2html-init.pl b/docs/manuals/en/main/latex2html-init.pl
new file mode 100644 (file)
index 0000000..14b5c31
--- /dev/null
@@ -0,0 +1,10 @@
+# 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;
diff --git a/docs/manuals/en/main/lesser.tex b/docs/manuals/en/main/lesser.tex
new file mode 100644 (file)
index 0000000..6fcc81e
--- /dev/null
@@ -0,0 +1,573 @@
+%%
+%%
+
+\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 
diff --git a/docs/manuals/en/main/license.tex b/docs/manuals/en/main/license.tex
new file mode 100644 (file)
index 0000000..d4b4ff4
--- /dev/null
@@ -0,0 +1,113 @@
+%%
+%%
+
+\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}}.
+
+\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-2009
+Free Software Foundation Europe e.V.
+
+Portions may be copyrighted by other people.  These files are released
+under different licenses which are compatible with the Bacula GPLv2 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 Kern Sibbald.
+
+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. If you have made
+modifications to the Bacula source code that alter in any significant
+way the way the program functions, you may not distribute it using the
+Bacula name.
+
+\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/en/FLA-bacula.en.pdf}{\url{http://www.bacula.org/en/FLA-bacula.en.pdf}}
+
+and if you are submitting code, you should fill it out then sent to:
+
+\begin{quote}
+     Kern Sibbald \\
+     Cotes-de-Montmoiret 9 \\
+     1012 Lausanne \\
+     Switzerland \\
+\end{quote}
+
+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. 
diff --git a/docs/manuals/en/main/main.kilepr b/docs/manuals/en/main/main.kilepr
new file mode 100644 (file)
index 0000000..ddafc06
--- /dev/null
@@ -0,0 +1,358 @@
+[General]
+img_extIsRegExp=false
+img_extensions=.eps .jpg .jpeg .png .pdf .ps .fig .gif
+kileprversion=2
+kileversion=2.0
+lastDocument=version.tex
+masterDocument=
+name=Concepts
+pkg_extIsRegExp=false
+pkg_extensions=.cls .sty
+src_extIsRegExp=false
+src_extensions=.tex .ltx .latex .dtx .ins
+
+[Tools]
+MakeIndex=
+QuickBuild=
+
+[item:ansi-labels.tex]
+archive=true
+column=0
+encoding=
+highlight=LaTeX
+line=1
+open=false
+order=2
+
+[item:autochangerres.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:autochangers.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:bootstrap.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:bugs.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:concepts.kilepr]
+archive=true
+column=134217831
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:concepts.tex]
+archive=true
+column=0
+encoding=
+highlight=LaTeX
+line=9
+open=false
+order=1
+
+[item:dataencryption.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:disk.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:dvd.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:fdl.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:general.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:gpl.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:lesser.tex]
+archive=true
+column=7864421
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:license.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:migration.tex]
+archive=true
+column=2147483647
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:newfeatures.tex]
+archive=true
+column=30
+encoding=UTF-8
+highlight=LaTeX
+line=341
+open=true
+order=0
+
+[item:pools.tex]
+archive=true
+column=2147483647
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:projects.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:python.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:recycling.tex]
+archive=true
+column=116
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:requirements.tex]
+archive=true
+column=7864421
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:rescue.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:restore.tex]
+archive=true
+column=148292584
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:spooling.tex]
+archive=true
+column=121
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:state.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:strategies.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:stunnel.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:supportedchangers.tex]
+archive=true
+column=147888641
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:supporteddrives.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:supportedoses.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:thanks.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:tls.tex]
+archive=true
+column=25
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:tutorial.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:vars.tex]
+archive=true
+column=147634280
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:verify.tex]
+archive=true
+column=0
+encoding=
+highlight=
+line=0
+open=false
+order=-1
+
+[item:version.tex]
+archive=true
+column=0
+encoding=
+highlight=LaTeX
+line=0
+open=true
+order=1
+
+[item:win32.tex]
+archive=true
+column=7864421
+encoding=
+highlight=
+line=0
+open=false
+order=-1
diff --git a/docs/manuals/en/main/main.tex b/docs/manuals/en/main/main.tex
new file mode 100644 (file)
index 0000000..884539e
--- /dev/null
@@ -0,0 +1,115 @@
+%%
+%%
+%%  The following characters must be preceded by a backslash
+%%    to be entered as printable characters:
+%%
+%%   # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[10pt,a4paper]{book}
+
+\topmargin -0.5in
+\oddsidemargin 0.0in
+\evensidemargin 0.0in
+\textheight 10in
+\textwidth 6.5in
+
+
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+% \usepackage[linkcolor=black,colorlinks=true]{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
+
+\include{coverpage}
+
+\clearpage
+\pagenumbering{roman}
+\tableofcontents
+\clearpage
+
+\pagestyle{myheadings}
+\markboth{Bacula Version \version}{Bacula Version \version}
+\pagenumbering{arabic}
+\include{general}
+\include{newfeatures}
+\include{state}
+\include{requirements}
+\include{supportedoses}
+\include{supporteddrives}
+
+\include{quickstart}   % install
+\include{install}      % install
+\include{critical}     % install
+
+\include{tutorial}
+
+\include{configure}    % install
+\include{dirdconf}     % install
+\include{filedconf}    % install
+\include{storedconf}   % install
+\include{messagesres}  % install
+\include{consoleconf}  % install
+\include{monitorconf}  % install
+
+\include{restore}
+\include{recycling}
+\include{disk}
+\include{pools}
+\include{migration}
+\include{strategies}
+\include{autochangers}
+\include{supportedchangers}
+\include{spooling}
+\include{statistics}
+\include{ansi-labels}
+\include{win32}
+\include{rescue}
+\include{tls}
+\include{dataencryption}
+\include{verify}
+
+\include{mysql}           % catalog
+\include{postgresql}      % catalog
+\include{sqlite}          % catalog
+\include{catmaintenance}  %catalog
+
+\include{tapetesting}   % install
+\include{security}        % install
+
+\include{bootstrap}
+\include{license}
+\include{fdl}
+\include{gpl}
+\include{lesser}
+\include{projects}
+\include{thanks}
+\include{bugs}
+
+% pull in the index
+\clearpage
+\printindex[general]
+\printindex[dir]
+\printindex[fd]
+\printindex[sd]
+\printindex[console]
+
+\end{document}
diff --git a/docs/manuals/en/main/messagesres.tex b/docs/manuals/en/main/messagesres.tex
new file mode 100644 (file)
index 0000000..784602c
--- /dev/null
@@ -0,0 +1,388 @@
+%%
+%%
+
+\chapter{Messages Resource}
+\label{MessagesChapter}
+\index[general]{Resource!Messages}
+\index[general]{Messages Resource}
+
+The Messages resource defines how messages are to be handled and destinations
+to which they should be sent. 
+
+Even though each daemon has a full message handler, within the File daemon and
+the Storage daemon, you will normally choose to send all the appropriate
+messages back to the Director.  This permits all the messages associated with
+a single Job to be combined in the Director and sent as a single email message
+to the user, or logged together in a single file.
+
+Each message that Bacula generates (i.e. that each daemon generates) has an
+associated type such as INFO, WARNING, ERROR, FATAL, etc. Using the message
+resource, you can specify which message types you wish to see and where they
+should be sent. In addition, a message may be sent to multiple destinations.
+For example, you may want all error messages both logged as well as sent to
+you in an email. By defining multiple messages resources, you can have
+different message handling for each type of Job (e.g. Full backups versus
+Incremental backups). 
+
+In general, messages are attached to a Job and are included in the Job report.
+There are some rare cases, where this is not possible, e.g. when no job is
+running, or if a communications error occurs between a daemon and the
+director. In those cases, the message may remain in the system, and should be
+flushed at the end of the next Job. However, since such messages are not
+attached to a Job, any that are mailed will be sent to {\bf
+/usr/lib/sendmail}. On some systems, such as FreeBSD, if your sendmail is in a
+different place, you may want to link it to the the above location. 
+
+The records contained in a Messages resource consist of a {\bf destination}
+specification followed by a list of {\bf message-types} in the format: 
+
+\begin{description}
+
+\item [destination = message-type1, message-type2, message-type3, ...  ]
+\index[dir]{destination}
+\end{description}
+
+or for those destinations that need and address specification (e.g. email): 
+
+\begin{description}
+
+\item [destination = address = message-type1, message-type2,
+   message-type3, ...  ]
+\index[dir]{destination}
+
+   Where {\bf destination} is one of a predefined set of keywords that define
+   where the message is to be sent ({\bf stdout}, {\bf file}, ...), {\bf
+   message-type} is one of a predefined set of keywords that define the type of
+   message generated by {\bf Bacula} ({\bf ERROR}, {\bf WARNING}, {\bf FATAL},
+   ...), and {\bf address} varies according to the {\bf destination} keyword, but
+   is typically an email address or a filename. 
+\end{description}
+
+The following are the list of the possible record definitions that can be used
+in a message resource. 
+
+\begin{description}
+
+\item [Messages]
+\index[dir]{Messages}
+   Start of the Messages records.  
+
+\item [Name = \lt{}name\gt{}]
+\index[dir]{Name}
+   The name of the Messages resource.  The name you specify here will be used to
+   tie this Messages  resource to a Job and/or to the daemon.  
+
+\label{mailcommand}
+\item [MailCommand = \lt{}command\gt{}]
+\index[dir]{MailCommand}
+   In the absence of this resource,  Bacula will send all mail using the
+   following command:  
+
+{\bf mail -s "Bacula Message" \lt{}recipients\gt{}}  
+
+In many cases, depending on your machine, this command may not work.  
+However, by using the {\bf MailCommand}, you can specify exactly how to
+send the mail.  During the processing of the {\bf command} part, normally
+specified as a quoted string, the following substitutions will be used:
+
+\begin{itemize}
+\item \%\% = \%  
+\item \%c = Client's name  
+\item \%d = Director's name  
+\item \%e = Job Exit code (OK, Error, ...)  
+\item \%i = Job Id  
+\item \%j = Unique Job name  
+\item \%l = Job level  
+\item \%n = Job name  
+\item \%r = Recipients  
+\item \%t = Job type (e.g. Backup, ...)  
+\end{itemize}
+
+Please note: any {\bf MailCommand} directive must be specified 
+in the {\bf Messages} resource {\bf before} the desired
+{\bf Mail}, {\bf MailOnSuccess}, or {\bf MailOnError}
+directive. In fact, each of those directives may be preceded by
+a different {\bf MailCommand}.
+
+The following is the command I (Kern) use. Note, the whole  command should
+appear on a single line in the configuration file  rather than split as is
+done here for presentation:  
+
+{\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"}
+
+The {\bf bsmtp} program is provided as part of {\bf Bacula}.  For
+additional details, please see the 
+\ilink{ bsmtp -- Customizing Your Email Messages}{bsmtp} section of
+the  Bacula Utility Programs chapter of this manual. Please test any  {\bf
+mailcommand} that you use to ensure that your bsmtp gateway accepts  the
+addressing form that you use. Certain programs such as Exim can be very 
+selective as to what forms are permitted particularly in the from part.  
+
+\item [OperatorCommand = \lt{}command\gt{}]
+\index[fd]{OperatorCommand}
+   This resource specification is  similar to the {\bf MailCommand} except that
+   it is used for Operator  messages. The substitutions performed for the {\bf
+   MailCommand} are  also done for this command. Normally, you will set this
+   command to the  same value as specified for the {\bf MailCommand}. 
+   The {\bf OperatorCommand} directive must appear in the {\bf Messages}
+   resource before the {\bf Operator} directive.
+
+\item [\lt{}destination\gt{} = \lt{}message-type1\gt{},
+   \lt{}message-type2\gt{}, ...]
+   \index[fd]{\lt{}destination\gt{}}
+
+Where {\bf destination} may be one of the following:  
+
+\begin{description}
+
+\item [stdout]
+   \index[fd]{stdout}
+   Send the message to standard output.  
+
+\item [stderr]
+   \index[fd]{stderr}
+   Send the message to standard error.  
+
+\item [console]
+   \index[console]{console}
+   Send the message to the console (Bacula Console).  These messages are held
+until the console program  connects to the Director.  
+\end{description}
+
+\item {\bf \lt{}destination\gt{} = \lt{}address\gt{} =
+   \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...}
+   \index[console]{\lt{}destination\gt{}}
+
+Where {\bf address} depends on the {\bf destination}. 
+
+The {\bf destination} may be one of the following:  
+
+\begin{description}
+
+\item [director]
+   \index[dir]{director}
+   \index[general]{director}
+   Send the message to the Director whose name  is given in the {\bf address}
+   field. Note, in the current  implementation, the Director Name is ignored, and
+   the message  is sent to the Director that started the Job.  
+
+\item [file]
+\index[dir]{file}
+\index[general]{file}
+   Send the message to the filename given in  the {\bf address} field. If the
+   file already exists, it will be  overwritten.  
+
+\item [append]
+\index[dir]{append}
+\index[general]{append}
+   Append the message to the filename given  in the {\bf address} field. If the
+   file already exists, it will  be appended to. If the file does not exist, it
+   will be created.  
+
+\item [syslog]
+\index[general]{syslog}
+   Send the message to the system log (syslog)  using the facility specified in
+   the {\bf address} field.  Note, for the moment, the {\bf address} field is
+   ignored  and the message is always sent to the LOG\_DAEMON facility with
+   level LOG\_ERR. See {\bf man 3 syslog} for more details. Example:
+
+\begin{verbatim}
+   syslog = all, !skipped
+\end{verbatim}
+
+   Although the {\bf syslog} destination is not used in the default Bacula
+   config files, in certain cases where Bacula encounters errors in trying
+   to deliver a message, as a last resort, it will send it to the system
+   {\bf syslog} to prevent loss of the message, so you might occassionally
+   check the {\bf syslog} for Bacula output (normally {\bf
+   /var/log/syslog}).
+
+\item [mail]
+   \index[general]{mail}
+   Send the message to the email addresses that are given as a comma
+   separated list in the {\bf address} field.  Mail messages are grouped
+   together during a job and then sent as a single email message when the
+   job terminates.  The advantage of this destination is that you are
+   notified about every Job that runs.  However, if you backup five or ten
+   machines every night, the volume of email messages can be important.
+   Some users use filter programs such as {\bf procmail} to automatically
+   file this email based on the Job termination code (see {\bf
+   mailcommand}).
+
+\item [mail on error]
+   \index[general]{mail on error}
+   Send the message to the email addresses that are given as a comma
+   separated list in the {\bf address} field if the Job terminates with an
+   error condition.  MailOnError messages are grouped together during a job
+   and then sent as a single email message when the job terminates.  This
+   destination differs from the {\bf mail} destination in that if the Job
+   terminates normally, the message is totally discarded (for this
+   destination).  If the Job terminates in error, it is emailed.  By using
+   other destinations such as {\bf append} you can ensure that even if the
+   Job terminates normally, the output information is saved.
+
+\item [mail on success]
+   \index[general]{mail on success}
+   Send the message to the email addresses that are given as a comma
+   separated list in the {\bf address} field if the Job terminates
+   normally (no error condition).  MailOnSuccess messages are grouped
+   together during a job and then sent as a single email message when the
+   job terminates.  This destination differs from the {\bf mail}
+   destination in that if the Job terminates abnormally, the message is
+   totally discarded (for this destination).  If the Job terminates
+   normally, it is emailed.
+
+\item [operator]
+   \index[general]{operator}
+   Send the message to the email addresses that are specified as a comma
+   separated list in the {\bf address} field.  This is similar to {\bf
+   mail} above, except that each message is sent as received.  Thus there
+   is one email per message.  This is most useful for {\bf mount} messages
+   (see below).  
+
+\item [console]
+  \index[general]{console}
+  Send the message to the Bacula console.
+
+\item [stdout]
+  \index[general]{stdout}
+  Send the message to the standard output (normally not used).
+
+\item [stderr]
+  \index[general]{stderr}
+  Send the message to the standard error output (normally not used).
+
+\item [catalog]
+   \index[general]{catalog}
+   Send the message to the Catalog database. The message will be
+   written to the table named {\bf Log} and a timestamp field will
+   also be added. This permits Job Reports and other messages to
+   be recorded in the Catalog so that they can be accessed by
+   reporting software.  Bacula will prune the Log records associated
+   with a Job when the Job records are pruned.  Otherwise, Bacula 
+   never uses these records internally, so this destination is only
+   used for special purpose programs (e.g. {\bf bweb}).
+
+\end{description}
+
+   For any destination, the {\bf message-type} field is a comma separated
+   list of the following types or classes of messages:
+
+\begin{description}
+
+\item [info]
+   \index[general]{info}
+   General information messages.  
+
+\item [warning]
+   \index[general]{warning}
+   Warning messages. Generally this is some  unusual condition but not expected
+   to be serious. 
+
+\item [error]
+   \index[general]{error}
+   Non-fatal error messages. The job continues running.  Any error message should
+   be investigated as it means that something  went wrong.  
+
+\item [fatal]
+   \index[general]{fatal}
+   Fatal error messages. Fatal errors cause the  job to terminate.  
+
+\item [terminate]
+   \index[general]{terminate}
+   Message generated when the daemon shuts down.  
+
+\item [notsaved]
+   \index[fd]{notsaved}
+   \index[general]{notsaved}
+   Files not saved because of some error.  Usually because the file cannot be
+   accessed (i.e. it does not  exist or is not mounted).  
+
+\item [skipped]
+   \index[fd]{skipped}
+   \index[general]{skipped}
+   Files that were skipped because of a user supplied option such as an
+   incremental backup or a file that matches an exclusion pattern.  This is
+   not considered an error condition such as the files listed for the {\bf
+   notsaved} type because the configuration file explicitly requests these
+   types of files to be skipped.  For example, any unchanged file during an
+   incremental backup, or any subdirectory if the no recursion option is
+   specified.
+
+\item [mount]
+   \index[dir]{mount}
+   \index[general]{mount}
+   Volume mount or intervention requests from the Storage daemon.  These
+   requests require a specific operator intervention for the job to
+   continue.
+
+\item [restored]
+   \index[fd]{restored}
+   \index[general]{restored}
+   The {\bf ls} style listing generated for each file restored is sent to
+   this message class.
+
+\item [all]
+   \index[general]{all}
+   All message types.  
+
+\item [security]
+   \index[general]{security}
+   Security info/warning messages principally from unauthorized      
+   connection attempts.
+
+\item [alert]
+   \index[general]{alert}
+   Alert messages. These are messages generated by tape alerts.
+
+\item [volmgmt]
+   \index[general]{volmgmt}
+   Volume management messages. Currently there are no volume mangement
+   messages generated.
+\end{description}
+
+\end{description}
+
+The following is an example of a valid Messages resource definition, where
+all messages except files explicitly skipped or daemon termination messages
+are sent by email to enforcement@sec.com.  In addition all mount messages
+are sent to the operator (i.e.  emailed to enforcement@sec.com).  Finally
+all messages other than explicitly skipped files and files saved are sent
+to the 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
+
+With the exception of the email address (changed to avoid junk mail from
+robot's), an example Director's Messages resource is as follows. Note, the {\bf
+mailcommand} and {\bf operatorcommand} are on a single line -- they had to be
+split for this manual: 
+
+\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
diff --git a/docs/manuals/en/main/migration.tex b/docs/manuals/en/main/migration.tex
new file mode 100644 (file)
index 0000000..25d139a
--- /dev/null
@@ -0,0 +1,479 @@
+
+\chapter{Migration and Copy}
+\label{MigrationChapter}
+\index[general]{Migration} 
+\index[general]{Copy} 
+
+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 Copy process is essentially identical to the Migration feature with the
+exception that the Job that is copied is left unchanged.  This essentially
+creates two identical copies of the same backup. However, the copy is treated
+as a copy rather than a backup job, and hence is not directly available for
+restore. If bacula founds a copy when a job record is purged (deleted) from the
+catalog, it will promote the copy as \textsl{real} backup and will make it
+available for automatic restore. 
+
+The Copy and the Migration jobs run without using the File daemon by copying
+the data from the old backup Volume to a different Volume in a different Pool.
+
+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 and Copy 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}, and although a Pool directive must still be
+   specified, no Pool is used, unless you specifically include it in the
+   SQL query.  Note, in any case, the Pool resource defined by the Pool 
+   directove 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.  Note, any original JobId that
+   is migrated will be marked as having been migrated, and the original
+   JobId can nolonger be used for restores; all restores will be done from
+   the new migrated Job.
+
+
+\item [Type = Copy]
+   {\bf Copy} is a new type that defines the job that is run as being a
+   Copy Job.  A Copy 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.  Copy jobs simply check to see if there is anything to
+   Copy then possibly start and control new Backup jobs to copy the data
+   from the specified Pool to another Pool.  Note that when a copy is
+   made, the original JobIds are left unchanged. The new copies can not
+   be used for restoration unless you specifically choose them by JobId.
+   If you subsequently delete a JobId that has a copy, the copy will be
+   automatically upgraded to a Backup rather than a Copy, and it will
+   subsequently be used for restoration.
+\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.
+
+  \item [PoolUncopiedJobs] This selection which copies all jobs from a pool
+        to an other pool which were not copied before is available only for copy Jobs.
+
+  \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.
diff --git a/docs/manuals/en/main/monitorconf.tex b/docs/manuals/en/main/monitorconf.tex
new file mode 100644 (file)
index 0000000..20c70b9
--- /dev/null
@@ -0,0 +1,341 @@
+%%
+%%
+
+\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
diff --git a/docs/manuals/en/main/mtx-changer.txt b/docs/manuals/en/main/mtx-changer.txt
new file mode 100644 (file)
index 0000000..10ef6d1
--- /dev/null
@@ -0,0 +1,215 @@
+#!/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
diff --git a/docs/manuals/en/main/mysql.tex b/docs/manuals/en/main/mysql.tex
new file mode 100644 (file)
index 0000000..75cc6f0
--- /dev/null
@@ -0,0 +1,286 @@
+%%
+%%
+
+\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.
diff --git a/docs/manuals/en/main/newfeatures.tex b/docs/manuals/en/main/newfeatures.tex
new file mode 100644 (file)
index 0000000..5a1d990
--- /dev/null
@@ -0,0 +1,1994 @@
+%%
+
+%%
+
+\chapter{New Features in 3.1.4 (Development Version}
+\label{NewFeaturesChapter}
+
+This chapter presents the new features that are currently under development
+in the 3.1.x versions to be released as Bacula version 3.2.0 sometime in
+late 2009 or early 2010.
+
+\section{Truncate volume after purge}
+\label{sec:actiononpurge}
+
+The Pool directive \textbf{ActionOnPurge=Truncate} instructs Bacula to truncate
+the volume when it is purged. It is useful to prevent disk based volumes from
+consuming too much space. 
+
+\begin{verbatim}
+Pool {
+  Name = Default
+  Action On Purge = Truncate
+  ...
+}
+\end{verbatim}
+
+\section{Maximum Concurent Jobs for Devices}
+\label{sec:maximumconcurentjobdevice}
+
+{\bf Maximum Concurrent Jobs} is a new Device directive in the Storage
+Daemon configuration permits setting the maximum number of Jobs that can
+run concurrently on a specified Device.  Using this directive, it is
+possible to have different Jobs using multiple drives, because when the
+Maximum Concurrent Jobs limit is reached, the Storage Daemon will start new
+Jobs on any other available compatible drive.  This facilitates writing to
+multiple drives with multiple Jobs that all use the same Pool.
+
+\section{Restore from Multiple Storage Daemons}
+\index[general]{Restore}
+
+Previously, you were able to restore from multiple devices in a single Storage
+Daemon. Now, Bacula is able to restore from multiple Storage Daemons. For
+example, if your full backup runs on a Storage Daemon with an autochanger, and
+your incremental jobs use another Storage Daemon with lots of disks, Bacula
+will switch automatically from one Storage Daemon to an other within the same
+Restore job.
+
+You must upgrade your File Daemon to version 3.1.3 or greater to use this feature.
+
+This project was funded by Bacula Systems with the help of Equiinet.
+
+\section{File Deduplication using Base Jobs}
+A base job is sort of like a Full save except that you will want the FileSet to
+contain only files that are unlikely to change in the future (i.e.  a snapshot
+of most of your system after installing it).  After the base job has been run,
+when you are doing a Full save, you specify one or more Base jobs to be used.
+All files that have been backed up in the Base job/jobs but not modified will
+then be excluded from the backup.  During a restore, the Base jobs will be
+automatically pulled in where necessary.
+
+This is something none of the competition does, as far as we know (except
+perhaps BackupPC, which is a Perl program that saves to disk only).  It is big
+win for the user, it makes Bacula stand out as offering a unique optimization
+that immediately saves time and money.  Basically, imagine that you have 100
+nearly identical Windows or Linux machine containing the OS and user files.
+Now for the OS part, a Base job will be backed up once, and rather than making
+100 copies of the OS, there will be only one.  If one or more of the systems
+have some files updated, no problem, they will be automatically restored.
+
+A new Job directive \texttt{Base=Jobx, Joby...} permits to specify the list of
+files that will be used during Full backup as base.
+
+\begin{verbatim}
+Job {
+   Name = BackupLinux
+   Level= Base
+   ...
+}
+
+Job {
+   Name = BackupZog4
+   Base = BackupZog4, BackupLinux
+   Accurate = yes
+   ...
+}
+\end{verbatim}
+
+In this example, the job \texttt{BackupZog4} will use the most recent version
+of all files contained in \texttt{BackupZog4} and \texttt{BackupLinux}
+jobs. Base jobs should have run with \texttt{level=Base} to be used.
+
+By default, Bacula will compare permissions bits, user and group fields,
+modification time, size and the checksum of the file to choose between the
+current backup and the BaseJob file list. You can change this behavior with the
+\texttt{BaseJob} FileSet option. This option works like the \texttt{verify=}
+one, that is described in the \ilink{FileSet}{FileSetResource} chapter.
+
+\begin{verbatim}
+FileSet {
+  Name = Full
+  Include = {
+    Options {
+       BaseJob  = pmugcs5
+       Accurate = mcs5
+       Verify   = pin5
+    }
+    File = /
+  }
+}
+\end{verbatim}
+
+
+This project was funded by Bacula Systems.
+
+
+\section{Accurate Fileset Options}
+\label{sec:accuratefileset}
+
+In previous versions, the accurate code used the file creation and
+modification times to determine if a file was modified or not. Now you can specify
+which attributes to use (time, size, checksum, permission, owner, group,
+\dots), similar to the Verify options.
+
+\begin{verbatim}
+FileSet {
+  Name = Full
+  Include = {
+    Options {
+       Accurate = mcs5
+       Verify   = pin5
+    }
+    File = /
+  }
+}
+\end{verbatim}
+
+\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}
+
+\textbf{Important note:} If you decide to use checksum in Accurate jobs,
+the File Daemon will have to read all files even if they normally would not
+be saved.  This increases the I/O load, but also the accuracy of the
+deduplication.  By default, Bacula will check modification/creation time
+and size.
+
+\section{Tab-completion for Bconsole}
+\label{sec:tabcompletion}
+
+If you build \texttt{bconsole} with readline support, you will be able to use
+the new auto-completion mode. This mode supports all commands, gives help
+inside command, and lists resources when required.
+
+\section{Bvfs API}
+\label{sec:bvfs}
+
+To help developers of restore GUI interfaces, we have added new \textsl{dot
+  commands} that permit browsing the catalog in a very simple way.
+
+\begin{itemize}
+\item \texttt{.bvfs\_update [jobid=x,y,z]} This command is required to update the
+  Bvfs cache in the catalog. You need to run it before any access to the Bvfs
+  layer.
+
+\item \texttt{.bvfs\_lsdirs jobid=x,y,z path=/path | pathid=101} This command
+  will list all directories in the specified \texttt{path} or
+  \texttt{pathid}. Using \texttt{pathid} avoids problems with character
+  encoding of path/filenames.
+
+\item \texttt{.bvfs\_lsfiles jobid=x,y,z path=/path | pathid=101} This command
+  will list all files in the specified \texttt{path} or \texttt{pathid}. Using
+  \texttt{pathid} avoids problems with character encoding.
+\end{itemize}
+
+You can use \texttt{limit=xxx} and \texttt{offset=yyy} to limit the amount of
+data that will be displayed.
+
+\begin{verbatim}
+* .bvfs_update jobid=1,2
+* .bvfs_update
+* .bvfs_lsdir path=/ jobid=1,2
+\end{verbatim}
+
+\section{Testing your Tape Drive}
+\label{sec:btapespeed}
+
+To determine the best configuration of your tape drive, you can run the new
+\texttt{speed} command available in the \texttt{btape} program.
+
+This command can have the following arguments:
+\begin{itemize}
+\item[\texttt{file\_size=n}] Specify the Maximum File Size for this test
+  (between 1 and 5GB). This counter is in GB.
+\item[\texttt{nb\_file=n}] Specify the number of file to be written. The amount
+  of data should be greater than your memory ($file\_size*nb\_file$).
+\item[\texttt{skip\_zero}] This flag permits to skip tests with constant
+  data.
+\item[\texttt{skip\_random}] This flag permits to skip tests with random
+  data.
+\item[\texttt{skip\_raw}] This flag permits to skip tests with raw access.
+\item[\texttt{skip\_block}] This flag permits to skip tests with Bacula block
+  access.
+\end{itemize}
+
+\begin{verbatim}
+*speed file_size=3 skip_raw
+btape.c:1078 Test with zero data and bacula block structure.
+btape.c:956 Begin writing 3 files of 3.221 GB with blocks of 129024 bytes.
+++++++++++++++++++++++++++++++++++++++++++
+btape.c:604 Wrote 1 EOF to "Drive-0" (/dev/nst0)
+btape.c:406 Volume bytes=3.221 GB. Write rate = 44.128 MB/s
+...
+btape.c:383 Total Volume bytes=9.664 GB. Total Write rate = 43.531 MB/s
+
+btape.c:1090 Test with random data, should give the minimum throughput.
+btape.c:956 Begin writing 3 files of 3.221 GB with blocks of 129024 bytes.
++++++++++++++++++++++++++++++++++++++++++++
+btape.c:604 Wrote 1 EOF to "Drive-0" (/dev/nst0)
+btape.c:406 Volume bytes=3.221 GB. Write rate = 7.271 MB/s
++++++++++++++++++++++++++++++++++++++++++++
+...
+btape.c:383 Total Volume bytes=9.664 GB. Total Write rate = 7.365 MB/s
+
+\end{verbatim}
+
+When using compression, the random test will give your the minimum throughput
+of your drive . The test using constant string will give you the maximum speed
+of your hardware chain. (cpu, memory, scsi card, cable, drive, tape).
+
+You can change the block size in the Storage Daemon configuration file.
+
+\section{New {\bf Block Checksum} Device Directive}
+You may now turn off the Block Checksum (CRC32) code
+that Bacula uses when writing blocks to a Volume.  This is
+done by adding:
+
+\begin{verbatim}
+Block Checksum = no
+\end{verbatim}
+
+doing so can reduce the Storage daemon CPU usage slightly.  It
+will also permit Bacula to read a Volume that has corrupted data.
+
+The default is {\bf yes} -- i.e. the checksum is computed on write
+and checked on read. 
+
+We do not recommend to turn this off particularly on older tape
+drives or for disk Volumes where doing so may allow corrupted data
+to go undetected.
+
+\section{New Bat Features}
+
+\subsection{Media List View}
+
+By clicking on ``Media'', you can see the list of all your volumes. You will be
+able to filter by Pool, Media Type, Location,\dots And sort the result directly
+in the table. The old ``Media'' view is now known as ``Pool''.
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=13cm]{\idir bat-mediaview.eps}
+  \label{fig:mediaview}
+\end{figure}
+
+
+\subsection{Media Information View}
+
+By double-clicking on a volume (on the Media list, in the Autochanger content
+or in the Job information panel), you can access a detailed overview of your
+Volume. (cf \ref{fig:mediainfo}.)
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=13cm]{\idir bat11.eps}  
+  \caption{Media information}
+  \label{fig:mediainfo}
+\end{figure}
+
+\subsection{Job Information View}
+
+By double-clicking on a Job record (on the Job run list or in the Media
+information panel), you can access a detailed overview of your Job. (cf
+\ref{fig:jobinfo}.)
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=13cm]{\idir bat12.eps}  
+  \caption{Job information}
+  \label{fig:jobinfo}
+\end{figure}
+
+\subsection{Autochanger Content View}
+
+By double-clicking on a Storage record (on the Storage list panel), you can
+access a detailed overview of your Autochanger. (cf \ref{fig:jobinfo}.)
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=13cm]{\idir bat13.eps}  
+  \caption{Autochanger content}
+  \label{fig:achcontent}
+\end{figure}
+
+\section{Console Timeout Option}
+You can now use the -u option of bconsole to set a timeout for each command.
+
+\chapter{New Features in Released Version 3.0.2}
+
+This chapter presents the new features added to the
+Released Bacula Version 3.0.2.
+
+\section{Full Restore from a Given JobId}
+\index[general]{Restore menu}
+
+This feature allows selecting a single JobId and having Bacula
+automatically select all the other jobs that comprise a full backup up to
+and including the selected date (through JobId).
+
+Assume we start with the following jobs:
+\begin{verbatim}
++-------+--------------+---------------------+-------+----------+------------+
+| jobid | client       | starttime           | level | jobfiles | jobbytes   |
++-------+--------------+---------------------+-------+----------+------------
+| 6     | localhost-fd | 2009-07-15 11:45:49 | I     | 2        | 0          |
+| 5     | localhost-fd | 2009-07-15 11:45:45 | I     | 15       | 44143      |
+| 3     | localhost-fd | 2009-07-15 11:45:38 | I     | 1        | 10         |
+| 1     | localhost-fd | 2009-07-15 11:45:30 | F     | 1527     | 44143073   |
++-------+--------------+---------------------+-------+----------+------------+
+\end{verbatim}
+
+Below is an example of this new feature (which is number 12 in the
+menu).
+
+\begin{verbatim}
+* restore
+To select the JobIds, you have the following choices:
+     1: List last 20 Jobs run
+     2: List Jobs where a given File is saved
+...
+    12: Select full restore to a specified Job date
+    13: Cancel
+
+Select item:  (1-13): 12
+Enter JobId to get the state to restore: 5
+Selecting jobs to build the Full state at 2009-07-15 11:45:45
+You have selected the following JobIds: 1,3,5
+
+Building directory tree for JobId(s) 1,3,5 ...  +++++++++++++++++++
+1,444 files inserted into the tree.
+\end{verbatim}
+
+This project was funded by Bacula Systems.
+
+\section{Source Address}
+\index[general]{Source Address}
+
+A feature has been added which allows the administrator to specify the address
+from which the Director and File daemons will establish connections.  This
+may be used to simplify system configuration overhead when working in complex
+networks utilizing multi-homing and policy-routing.
+
+To accomplish this, two new configuration directives have been implemented:
+\begin{verbatim}
+FileDaemon {
+  FDSourceAddress=10.0.1.20    # Always initiate connections from this address
+}
+
+Director {
+  DirSourceAddress=10.0.1.10   # Always initiate connections from this address
+}
+\end{verbatim}
+
+Simply adding specific host routes on the OS
+would have an undesirable side-effect: any
+application trying to contact the destination host would be forced to use the
+more specific route possibly diverting management traffic onto a backup VLAN.
+Instead of adding host routes for each client connected to a multi-homed backup
+server (for example where there are management and backup VLANs), one can
+use the new directives to specify a specific source address at the application
+level.
+
+Additionally, this allows the simplification and abstraction of firewall rules
+when dealing with a Hot-Standby director or storage daemon configuration.  The
+Hot-standby pair may share a CARP address, which connections must be sourced
+from, while system services listen and act from the unique interface addresses.
+
+This project was funded by Collaborative Fusion, Inc.
+
+\section{Show volume availability when doing restore}
+
+When doing a restore the selection dialog ends by displaying this
+screen:
+
+\begin{verbatim}
+  The job will require the following
+   Volume(s)                 Storage(s)                SD Device(s)
+   ===========================================================================
+   *000741L3                  LTO-4                     LTO3 
+   *000866L3                  LTO-4                     LTO3 
+   *000765L3                  LTO-4                     LTO3 
+   *000764L3                  LTO-4                     LTO3 
+   *000756L3                  LTO-4                     LTO3 
+   *001759L3                  LTO-4                     LTO3 
+   *001763L3                  LTO-4                     LTO3 
+    001762L3                  LTO-4                     LTO3 
+    001767L3                  LTO-4                     LTO3 
+
+Volumes marked with ``*'' are online (in the autochanger).
+\end{verbatim}
+
+This should help speed up large restores by minimizing the time spent
+waiting for the operator to discover that he must change tapes in the library.
+
+This project was funded by Bacula Systems.
+
+\section{Accurate estimate command}
+
+The \texttt{estimate} command can now use the accurate code to detect changes
+and give a better estimation.
+
+You can set the accurate behavior on the command line by using
+\texttt{accurate=yes\vb{}no} or use the Job setting as default value.
+
+\begin{verbatim}
+* estimate listing accurate=yes level=incremental job=BackupJob
+\end{verbatim}
+
+This project was funded by Bacula Systems.
+
+\chapter{New Features in 3.0.0}
+\label{NewFeaturesChapter}
+\index[general]{New Features}
+
+This chapter presents the new features added to the development 2.5.x
+versions to be released as Bacula version 3.0.0 sometime in April 2009.
+
+\section{Accurate Backup}
+\index[general]{Accurate Backup}
+
+As with most other backup programs, by default Bacula decides what files to
+backup for Incremental and Differental backup by comparing the change
+(st\_ctime) and modification (st\_mtime) times of the file to the time the last
+backup completed.  If one of those two times is later than the last backup
+time, then the file will be backed up.  This does not, however, permit tracking
+what files have been deleted and will miss any file with an old time that may
+have been restored to or moved onto the client filesystem.
+
+\subsection{Accurate = \lt{}yes\vb{}no\gt{}}
+If the {\bf Accurate = \lt{}yes\vb{}no\gt{}} directive is enabled (default no) in
+the Job resource, the job will be run as an Accurate Job. For a {\bf Full}
+backup, there is no difference, but for {\bf Differential} and {\bf
+  Incremental} backups, the Director will send a list of all previous files
+backed up, and the File daemon will use that list to determine if any new files
+have been added or or moved and if any files have been deleted. This allows
+Bacula to make an accurate backup of your system to that point in time so that
+if you do a restore, it will restore your system exactly.  
+
+One note of caution
+about using Accurate backup is that it requires more resources (CPU and memory)
+on both the Director and the Client machines to create the list of previous
+files backed up, to send that list to the File daemon, for the File daemon to
+keep the list (possibly very big) in memory, and for the File daemon to do
+comparisons between every file in the FileSet and the list.  In particular,
+if your client has lots of files (more than a few million), you will need
+lots of memory on the client machine.
+
+Accurate must not be enabled when backing up with a plugin that is not
+specially designed to work with Accurate. If you enable it, your restores
+will probably not work correctly.
+
+This project was funded by Bacula Systems.
+                                       
+
+
+\section{Copy Jobs}
+\index[general]{Copy Jobs}
+
+A new {\bf Copy} job type 'C' has been implemented. It is similar to the
+existing Migration feature with the exception that the Job that is copied is
+left unchanged.  This essentially creates two identical copies of the same
+backup. However, the copy is treated as a copy rather than a backup job, and
+hence is not directly available for restore.  The {\bf restore} command lists
+copy jobs and allows selection of copies by using \texttt{jobid=}
+option. If the keyword {\bf copies} is present on the command line, Bacula will
+display the list of all copies for selected jobs.
+
+\begin{verbatim}
+* restore copies
+[...]
+These JobIds have copies as follows:
++-------+------------------------------------+-----------+------------------+
+| JobId | Job                                | CopyJobId | MediaType        |
++-------+------------------------------------+-----------+------------------+
+| 2     | CopyJobSave.2009-02-17_16.31.00.11 | 7         | DiskChangerMedia |
++-------+------------------------------------+-----------+------------------+
++-------+-------+----------+----------+---------------------+------------------+
+| JobId | Level | JobFiles | JobBytes | StartTime           | VolumeName       |
++-------+-------+----------+----------+---------------------+------------------+
+| 19    | F     | 6274     | 76565018 | 2009-02-17 16:30:45 | ChangerVolume002 |
+| 2     | I     | 1        | 5        | 2009-02-17 16:30:51 | FileVolume001    |
++-------+-------+----------+----------+---------------------+------------------+
+You have selected the following JobIds: 19,2
+
+Building directory tree for JobId(s) 19,2 ...  ++++++++++++++++++++++++++++++++++++++++++++
+5,611 files inserted into the tree.
+...
+\end{verbatim}
+
+
+The Copy Job runs without using the File daemon by copying the data from the
+old backup Volume to a different Volume in a different Pool. See the Migration
+documentation for additional details. For copy Jobs there is a new selection
+directive named {\bf PoolUncopiedJobs} which selects all Jobs that were
+not already copied to another Pool. 
+
+As with Migration, the Client, Volume, Job, or SQL query, are
+other possible ways of selecting the Jobs to be copied. Selection
+types like SmallestVolume, OldestVolume, PoolOccupancy and PoolTime also
+work, but are probably more suited for Migration Jobs. 
+
+If Bacula finds a Copy of a job record that is purged (deleted) from the catalog,
+it will promote the Copy to a \textsl{real} backup job and will make it available for
+automatic restore. If more than one Copy is available, it will promote the copy
+with the smallest JobId.
+
+A nice solution which can be built with the new Copy feature is often
+called disk-to-disk-to-tape backup (DTDTT). A sample config could
+look something like the one below:
+
+\begin{verbatim}
+Pool {
+  Name = FullBackupsVirtualPool
+  Pool Type = Backup
+  Purge Oldest Volume = Yes
+  Storage = vtl
+  NextPool = FullBackupsTapePool
+}
+
+Pool {
+  Name = FullBackupsTapePool
+  Pool Type = Backup
+  Recycle = Yes
+  AutoPrune = Yes
+  Volume Retention = 365 days
+  Storage = superloader
+}
+
+#
+# Fake fileset for copy jobs
+#
+Fileset {
+  Name = None
+  Include {
+    Options {
+      signature = MD5
+    }
+  }
+}
+
+#
+# Fake client for copy jobs
+#
+Client {
+  Name = None
+  Address = localhost
+  Password = "NoNe"
+  Catalog = MyCatalog
+}
+
+#
+# Default template for a CopyDiskToTape Job
+#
+JobDefs {
+  Name = CopyDiskToTape
+  Type = Copy
+  Messages = StandardCopy
+  Client = None
+  FileSet = None
+  Selection Type = PoolUncopiedJobs
+  Maximum Concurrent Jobs = 10
+  SpoolData = No
+  Allow Duplicate Jobs = Yes
+  Allow Higher Duplicates = No
+  Cancel Queued Duplicates = No
+  Cancel Running Duplicates = No
+  Priority = 13
+}
+
+Schedule {
+   Name = DaySchedule7:00
+   Run = Level=Full daily at 7:00
+}
+
+Job {
+  Name = CopyDiskToTapeFullBackups
+  Enabled = Yes
+  Schedule = DaySchedule7:00
+  Pool = FullBackupsVirtualPool
+  JobDefs = CopyDiskToTape
+}
+\end{verbatim}
+
+The example above had 2 pool which are copied using the PoolUncopiedJobs
+selection criteria. Normal Full backups go to the Virtual pool and are copied
+to the Tape pool the next morning.
+
+The command \texttt{list copies [jobid=x,y,z]} lists copies for a given
+\textbf{jobid}.
+
+\begin{verbatim}
+*list copies
++-------+------------------------------------+-----------+------------------+
+| JobId | Job                                | CopyJobId | MediaType        |
++-------+------------------------------------+-----------+------------------+
+|     9 | CopyJobSave.2008-12-20_22.26.49.05 |        11 | DiskChangerMedia |
++-------+------------------------------------+-----------+------------------+
+\end{verbatim}
+
+\section{ACL Updates}
+\index[general]{ACL Updates}
+The whole ACL code had been overhauled and in this version each platforms has
+different streams for each type of acl available on such an platform. As ACLs
+between platforms tend to be not that portable (most implement POSIX acls but
+some use an other draft or a completely different format) we currently only
+allow certain platform specific ACL streams to be decoded and restored on the
+same platform that they were created on.  The old code allowed to restore ACL
+cross platform but the comments already mention that not being to wise. For
+backward compatability the new code will accept the two old ACL streams and
+handle those with the platform specific handler. But for all new backups it
+will save the ACLs using the new streams.
+
+Currently the following platforms support ACLs:
+
+\begin{itemize}
+ \item {\bf AIX}
+ \item {\bf Darwin/OSX}
+ \item {\bf FreeBSD}
+ \item {\bf HPUX}
+ \item {\bf IRIX}
+ \item {\bf Linux}
+ \item {\bf Tru64}
+ \item {\bf Solaris}
+\end{itemize}
+
+Currently we support the following ACL types (these ACL streams use a reserved
+part of the stream numbers):
+
+\begin{itemize}
+\item {\bf STREAM\_ACL\_AIX\_TEXT} 1000 AIX specific string representation from
+  acl\_get
+ \item {\bf STREAM\_ACL\_DARWIN\_ACCESS\_ACL} 1001 Darwin (OSX) specific acl\_t
+   string representation from acl\_to\_text (POSIX acl)
+  \item {\bf STREAM\_ACL\_FREEBSD\_DEFAULT\_ACL} 1002 FreeBSD specific acl\_t
+    string representation from acl\_to\_text (POSIX acl) for default acls.
+  \item {\bf STREAM\_ACL\_FREEBSD\_ACCESS\_ACL} 1003 FreeBSD specific acl\_t
+    string representation from acl\_to\_text (POSIX acl) for access acls.
+  \item {\bf STREAM\_ACL\_HPUX\_ACL\_ENTRY} 1004 HPUX specific acl\_entry
+    string representation from acltostr (POSIX acl)
+  \item {\bf STREAM\_ACL\_IRIX\_DEFAULT\_ACL} 1005 IRIX specific acl\_t string
+    representation from acl\_to\_text (POSIX acl) for default acls.
+  \item {\bf STREAM\_ACL\_IRIX\_ACCESS\_ACL} 1006 IRIX specific acl\_t string
+    representation from acl\_to\_text (POSIX acl) for access acls.
+  \item {\bf STREAM\_ACL\_LINUX\_DEFAULT\_ACL} 1007 Linux specific acl\_t
+    string representation from acl\_to\_text (POSIX acl) for default acls.
+  \item {\bf STREAM\_ACL\_LINUX\_ACCESS\_ACL} 1008 Linux specific acl\_t string
+    representation from acl\_to\_text (POSIX acl) for access acls.
+  \item {\bf STREAM\_ACL\_TRU64\_DEFAULT\_ACL} 1009 Tru64 specific acl\_t
+    string representation from acl\_to\_text (POSIX acl) for default acls.
+  \item {\bf STREAM\_ACL\_TRU64\_DEFAULT\_DIR\_ACL} 1010 Tru64 specific acl\_t
+    string representation from acl\_to\_text (POSIX acl) for default acls.
+  \item {\bf STREAM\_ACL\_TRU64\_ACCESS\_ACL} 1011 Tru64 specific acl\_t string
+    representation from acl\_to\_text (POSIX acl) for access acls.
+  \item {\bf STREAM\_ACL\_SOLARIS\_ACLENT} 1012 Solaris specific aclent\_t
+    string representation from acltotext or acl\_totext (POSIX acl)
+  \item {\bf STREAM\_ACL\_SOLARIS\_ACE} 1013 Solaris specific ace\_t string
+    representation from from acl\_totext (NFSv4 or ZFS acl)
+\end{itemize}
+
+In future versions we might support conversion functions from one type of acl
+into an other for types that are either the same or easily convertable. For now
+the streams are seperate and restoring them on a platform that doesn't
+recognize them will give you a warning.
+
+\section{Extended Attributes}
+\index[general]{Extended Attributes}
+Something that was on the project list for some time is now implemented for
+platforms that support a similar kind of interface. Its the support for backup
+and restore of so called extended attributes. As extended attributes are so
+platform specific these attributes are saved in seperate streams for each
+platform.  Restores of the extended attributes can only be performed on the
+same platform the backup was done.  There is support for all types of extended
+attributes, but restoring from one type of filesystem onto an other type of
+filesystem on the same platform may lead to supprises.  As extended attributes
+can contain any type of data they are stored as a series of so called
+value-pairs.  This data must be seen as mostly binary and is stored as such.
+As security labels from selinux are also extended attributes this option also
+stores those labels and no specific code is enabled for handling selinux
+security labels.
+
+Currently the following platforms support extended attributes:
+\begin{itemize}
+ \item {\bf Darwin/OSX}
+ \item {\bf FreeBSD}
+ \item {\bf Linux}
+ \item {\bf NetBSD}
+\end{itemize}
+
+On linux acls are also extended attributes, as such when you enable ACLs on a
+Linux platform it will NOT save the same data twice e.g. it will save the ACLs
+and not the same exteneded attribute.
+
+To enable the backup of extended attributes please add the following to your
+fileset definition.
+\begin{verbatim}
+  FileSet {
+    Name = "MyFileSet"
+    Include {
+      Options {
+        signature = MD5
+        xattrsupport = yes
+      }
+      File = ...
+    }
+  }
+\end{verbatim}
+
+\section{Shared objects}
+\index[general]{Shared objects}
+A default build of Bacula will now create the libraries as shared objects
+(.so) rather than static libraries as was previously the case.  
+The shared libraries are built using {\bf libtool} so it should be quite
+portable.
+
+An important advantage of using shared objects is that on a machine with the
+Directory, File daemon, the Storage daemon, and a console, you will have only
+one copy of the code in memory rather than four copies.  Also the total size of
+the binary release is smaller since the library code appears only once rather
+than once for every program that uses it; this results in significant reduction
+in the size of the binaries particularly for the utility tools.
+In order for the system loader to find the shared objects when loading the
+Bacula binaries, the Bacula shared objects must either be in a shared object
+directory known to the loader (typically /usr/lib) or they must be in the
+directory that may be specified on the {\bf ./configure} line using the {\bf
+  {-}{-}libdir} option as:
+
+\begin{verbatim}
+  ./configure --libdir=/full-path/dir
+\end{verbatim}
+
+the default is /usr/lib. If {-}{-}libdir is specified, there should be
+no need to modify your loader configuration provided that
+the shared objects are installed in that directory (Bacula
+does this with the make install command). The shared objects
+that Bacula references are:
+
+\begin{verbatim}
+libbaccfg.so
+libbacfind.so
+libbacpy.so
+libbac.so
+\end{verbatim}
+
+These files are symbolically linked to the real shared object file,
+which has a version number to permit running multiple versions of
+the libraries if desired (not normally the case).
+
+If you have problems with libtool or you wish to use the old
+way of building static libraries, or you want to build a static
+version of Bacula you may disable
+libtool on the configure command line with:
+
+\begin{verbatim}
+  ./configure --disable-libtool
+\end{verbatim}
+
+
+\section{Building Static versions of Bacula}
+\index[general]{Static linking}
+In order to build static versions of Bacula, in addition
+to configuration options that were needed you now must
+also add --disable-libtool.  Example
+
+\begin{verbatim}
+  ./configure --enable-static-client-only --disable-libtool
+\end{verbatim}
+
+
+\section{Virtual Backup (Vbackup)}
+\index[general]{Virtual Backup}
+\index[general]{Vbackup}
+
+Bacula's virtual backup feature is often called Synthetic Backup or
+Consolidation in other backup products.  It permits you to consolidate the
+previous Full backup plus the most recent Differential backup and any
+subsequent Incremental backups into a new Full backup.  This new Full
+backup will then be considered as the most recent Full for any future
+Incremental or Differential backups.  The VirtualFull backup is
+accomplished without contacting the client by reading the previous backup
+data and writing it to a volume in a different pool.
+
+In some respects the Vbackup feature works similar to a Migration job, in
+that Bacula normally reads the data from the pool specified in the 
+Job resource, and writes it to the {\bf Next Pool} specified in the 
+Job resource. Note, this means that usually the output from the Virtual
+Backup is written into a different pool from where your prior backups
+are saved. Doing it this way guarantees that you will not get a deadlock
+situation attempting to read and write to the same volume in the Storage
+daemon. If you then want to do subsequent backups, you may need to
+move the Virtual Full Volume back to your normal backup pool.
+Alternatively, you can set your {\bf Next Pool} to point to the current
+pool.  This will cause Bacula to read and write to Volumes in the
+current pool. In general, this will work, because Bacula will
+not allow reading and writing on the same Volume. In any case, once
+a VirtualFull has been created, and a restore is done involving the
+most current Full, it will read the Volume or Volumes by the VirtualFull 
+regardless of in which Pool the Volume is found.
+
+The Vbackup is enabled on a Job by Job in the Job resource by specifying
+a level of {\bf VirtualFull}.
+
+A typical Job resource definition might look like the following:
+
+\begin{verbatim}
+Job {
+  Name = "MyBackup"
+  Type = Backup
+  Client=localhost-fd
+  FileSet = "Full Set"
+  Storage = File
+  Messages = Standard
+  Pool = Default
+  SpoolData = yes
+}
+
+# Default pool definition
+Pool {
+  Name = Default
+  Pool Type = Backup
+  Recycle = yes            # Automatically recycle Volumes
+  AutoPrune = yes          # Prune expired volumes
+  Volume Retention = 365d  # one year
+  NextPool = Full
+  Storage = File
+}
+
+Pool {
+  Name = Full
+  Pool Type = Backup
+  Recycle = yes            # Automatically recycle Volumes
+  AutoPrune = yes          # Prune expired volumes
+  Volume Retention = 365d  # one year
+  Storage = DiskChanger
+}
+
+# Definition of file storage device
+Storage {
+  Name = File
+  Address = localhost
+  Password = "xxx"
+  Device = FileStorage
+  Media Type = File
+  Maximum Concurrent Jobs = 5
+}
+
+# Definition of DDS Virtual tape disk storage device
+Storage {
+  Name = DiskChanger
+  Address = localhost  # N.B. Use a fully qualified name here
+  Password = "yyy"
+  Device = DiskChanger
+  Media Type = DiskChangerMedia
+  Maximum Concurrent Jobs = 4
+  Autochanger = yes
+}
+\end{verbatim}
+
+Then in bconsole or via a Run schedule, you would run the job as:
+
+\begin{verbatim}
+run job=MyBackup level=Full
+run job=MyBackup level=Incremental
+run job=MyBackup level=Differential
+run job=MyBackup level=Incremental
+run job=MyBackup level=Incremental
+\end{verbatim}
+
+So providing there were changes between each of those jobs, you would end up
+with a Full backup, a Differential, which includes the first Incremental
+backup, then two Incremental backups.  All the above jobs would be written to
+the {\bf Default} pool.
+
+To consolidate those backups into a new Full backup, you would run the
+following:
+
+\begin{verbatim}
+run job=MyBackup level=VirtualFull
+\end{verbatim}
+
+And it would produce a new Full backup without using the client, and the output
+would be written to the {\bf Full} Pool which uses the Diskchanger Storage.
+
+If the Virtual Full is run, and there are no prior Jobs, the Virtual Full will
+fail with an error.
+
+Note, the Start and End time of the Virtual Full backup is set to the
+values for the last job included in the Virtual Full (in the above example,
+it is an Increment). This is so that if another incremental is done, which
+will be based on the Virtual Full, it will backup all files from the
+last Job included in the Virtual Full rather than from the time the Virtual
+Full was actually run.
+
+
+
+\section{Catalog Format}
+\index[general]{Catalog Format}
+Bacula 3.0 comes with some changes to the catalog format.  The upgrade
+operation will convert the FileId field of the File table from 32 bits (max 4
+billion table entries) to 64 bits (very large number of items).  The
+conversion process can take a bit of time and will likely DOUBLE THE SIZE of
+your catalog during the conversion.  Also you won't be able to run jobs during
+this conversion period.  For example, a 3 million file catalog will take 2
+minutes to upgrade on a normal machine.  Please don't forget to make a valid
+backup of your database before executing the upgrade script. See the 
+ReleaseNotes for additional details.
+
+\section{64 bit Windows Client}
+\index[general]{Win64 Client}
+Unfortunately, Microsoft's implementation of Volume Shadown Copy (VSS) on
+their 64 bit OS versions is not compatible with a 32 bit Bacula Client.
+As a consequence, we are also releasing a 64 bit version of the Bacula 
+Windows Client (win64bacula-3.0.0.exe) that does work with VSS. 
+These binaries should only be installed on 64 bit Windows operating systems.
+What is important is not your hardware but whether or not you have
+a 64 bit version of the Windows OS.  
+
+Compared to the Win32 Bacula Client, the 64 bit release contains a few differences:
+\begin{enumerate}
+\item Before installing the Win64 Bacula Client, you must totally
+      deinstall any prior 2.4.x Client installation using the 
+      Bacula deinstallation (see the menu item). You may want
+      to save your .conf files first.
+\item Only the Client (File daemon) is ported to Win64, the Director
+      and the Storage daemon are not in the 64 bit Windows installer.
+\item bwx-console is not yet ported.
+\item bconsole is ported but it has not been tested.
+\item The documentation is not included in the installer.
+\item Due to Vista security restrictions imposed on a default installation
+      of Vista, before upgrading the Client, you must manually stop
+      any prior version of Bacula from running, otherwise the install
+      will fail.
+\item Due to Vista security restrictions imposed on a default installation
+      of Vista, attempting to edit the conf files via the menu items
+      will fail. You must directly edit the files with appropriate 
+      permissions.  Generally double clicking on the appropriate .conf
+      file will work providing you have sufficient permissions.
+\item All Bacula files are now installed in 
+      {\bf C:/Program Files/Bacula} except the main menu items,
+      which are installed as before. This vastly simplifies the installation.
+\item If you are running on a foreign language version of Windows, most
+      likely {\bf C:/Program Files} does not exist, so you should use the
+      Custom installation and enter an appropriate location to install
+      the files.
+\item The 3.0.0 Win32 Client continues to install files in the locations used
+      by prior versions. For the next version we will convert it to use
+      the same installation conventions as the Win64 version.
+\end{enumerate}
+
+This project was funded by Bacula Systems.
+
+
+\section{Duplicate Job Control}
+\index[general]{Duplicate Jobs}
+The new version of Bacula provides four new directives that
+give additional control over what Bacula does if duplicate jobs 
+are started.  A duplicate job in the sense we use it here means
+a second or subsequent job with the same name starts.  This
+happens most frequently when the first job runs longer than expected because no 
+tapes are available.
+
+The four directives each take as an argument a {\bf yes} or {\bf no} value and
+are specified in the Job resource.
+
+They are:
+
+\subsection{Allow Duplicate Jobs = \lt{}yes\vb{}no\gt{}}
+\index[general]{Allow Duplicate Jobs}
+  If this directive is enabled duplicate jobs will be run.  If
+  the directive is set to {\bf no} (default) then only one job of a given name
+  may run at one time, and the action that Bacula takes to ensure only
+  one job runs is determined by the other directives (see below).
+  If {\bf Allow Duplicate Jobs} is set to {\bf no} and two jobs
+  are present and none of the three directives given below permit
+  cancelling a job, then the current job (the second one started)
+  will be cancelled.
+
+
+\subsection{Allow Higher Duplicates = \lt{}yes\vb{}no\gt{}}
+\index[general]{Allow Higher Duplicates}
+  If this directive is set to {\bf yes} (default) the job with a higher
+  priority (lower priority number) will be permitted to run, and
+  the current job will be cancelled.  If the
+  priorities of the two jobs are the same, the outcome is determined by
+  other directives (see below).
+
+\subsection{Cancel Queued Duplicates = \lt{}yes\vb{}no\gt{}}
+\index[general]{Cancel Queued Duplicates}
+  If {\bf Allow Duplicate Jobs} is set to {\bf no} and
+  if this directive is set to {\bf yes} any job that is
+  already queued to run but not yet running will be canceled.
+  The default is {\bf no}. 
+
+\subsection{Cancel Running Duplicates = \lt{}yes\vb{}no\gt{}}
+\index[general]{Cancel Running Duplicates}
+  If {\bf Allow Duplicate Jobs} is set to {\bf no} and
+  if this directive is set to {\bf yes} any job that is already running
+  will be canceled.  The default is {\bf no}.
+
+
+\section{TLS Authentication}
+\index[general]{TLS Authentication}
+In Bacula version 2.5.x and later, in addition to the normal Bacula
+CRAM-MD5 authentication that is used to authenticate each Bacula
+connection, you can specify that you want TLS Authentication as well,
+which will provide more secure authentication.
+
+This new feature uses Bacula's existing TLS code (normally used for
+communications encryption) to do authentication.  To use it, you must
+specify all the TLS directives normally used to enable communications
+encryption (TLS Enable, TLS Verify Peer, TLS Certificate, ...) and
+a new directive:
+
+\subsection{TLS Authenticate = yes}
+\begin{verbatim}
+TLS Authenticate = yes
+\end{verbatim}
+
+in the main daemon configuration resource (Director for the Director,
+Client for the File daemon, and Storage for the Storage daemon).
+
+When {\bf TLS Authenticate} is enabled, after doing the CRAM-MD5
+authentication, Bacula will also do TLS authentication, then TLS 
+encryption will be turned off, and the rest of the communication between
+the two Bacula daemons will be done without encryption.
+
+If you want to encrypt communications data, use the normal TLS directives
+but do not turn on {\bf TLS Authenticate}.
+
+\section{bextract non-portable Win32 data}
+\index[general]{bextract handles Win32 non-portable data}
+{\bf bextract} has been enhanced to be able to restore
+non-portable Win32 data to any OS.  Previous versions were 
+unable to restore non-portable Win32 data to machines that
+did not have the Win32 BackupRead and BackupWrite API calls.
+
+\section{State File updated at Job Termination}
+\index[general]{State File}
+In previous versions of Bacula, the state file, which provides a
+summary of previous jobs run in the {\bf status} command output was
+updated only when Bacula terminated, thus if the daemon crashed, the
+state file might not contain all the run data.  This version of
+the Bacula daemons updates the state file on each job termination.
+
+\section{MaxFullInterval = \lt{}time-interval\gt{}}
+\index[general]{MaxFullInterval}
+The new Job resource directive {\bf Max Full Interval = \lt{}time-interval\gt{}}
+can be used to specify the maximum time interval between {\bf Full} backup
+jobs. When a job starts, if the time since the last Full backup is
+greater than the specified interval, and the job would normally be an
+{\bf Incremental} or {\bf Differential}, it will be automatically
+upgraded to a {\bf Full} backup.
+
+\section{MaxDiffInterval = \lt{}time-interval\gt{}}
+\index[general]{MaxDiffInterval}
+The new Job resource directive {\bf Max Diff Interval = \lt{}time-interval\gt{}}
+can be used to specify the maximum time interval between {\bf Differential} backup
+jobs. When a job starts, if the time since the last Differential backup is
+greater than the specified interval, and the job would normally be an
+{\bf Incremental}, it will be automatically
+upgraded to a {\bf Differential} backup.
+
+\section{Honor No Dump Flag = \lt{}yes\vb{}no\gt{}}
+\index[general]{MaxDiffInterval}
+On FreeBSD systems, each file has a {\bf no dump flag} that can be set
+by the user, and when it is set it is an indication to backup programs
+to not backup that particular file.  This version of Bacula contains a
+new Options directive within a FileSet resource, which instructs Bacula to
+obey this flag.  The new directive is:
+
+\begin{verbatim}
+  Honor No Dump Flag = yes\vb{}no
+\end{verbatim}
+
+The default value is {\bf no}.
+
+
+\section{Exclude Dir Containing = \lt{}filename-string\gt{}}
+\index[general]{IgnoreDir}
+The {\bf ExcludeDirContaining = \lt{}filename\gt{}} is a new directive that
+can be added to the Include section of the FileSet resource.  If the specified
+filename ({\bf filename-string}) is found on the Client in any directory to be
+backed up, the whole directory will be ignored (not backed up).  For example:
+
+\begin{verbatim}
+  # List of files to be backed up
+  FileSet {
+    Name = "MyFileSet"
+    Include {
+      Options {
+        signature = MD5
+      }
+      File = /home
+      Exclude Dir Containing = .excludeme
+    }
+  }
+\end{verbatim}
+
+But in /home, there may be hundreds of directories of users and some
+people want to indicate that they don't want to have certain
+directories backed up. For example, with the above FileSet, if
+the user or sysadmin creates a file named {\bf .excludeme} in 
+specific directories, such as
+
+\begin{verbatim}
+   /home/user/www/cache/.excludeme
+   /home/user/temp/.excludeme
+\end{verbatim}
+
+then Bacula will not backup the two directories named:
+
+\begin{verbatim}
+   /home/user/www/cache
+   /home/user/temp
+\end{verbatim}
+
+NOTE: subdirectories will not be backed up.  That is, the directive
+applies to the two directories in question and any children (be they
+files, directories, etc).
+
+
+\section{Bacula Plugins}
+\index[general]{Plugin}
+Support for shared object plugins has been implemented in the Linux, Unix
+and Win32 File daemons. The API will be documented separately in
+the Developer's Guide or in a new document.  For the moment, there is
+a single plugin named {\bf bpipe} that allows an external program to
+get control to backup and restore a file.
+
+Plugins are also planned (partially implemented) in the Director and the
+Storage daemon.  
+
+\subsection{Plugin Directory}
+\index[general]{Plugin Directory}
+Each daemon (DIR, FD, SD) has a new {\bf Plugin Directory} directive that may
+be added to the daemon definition resource. The directory takes a quoted 
+string argument, which is the name of the directory in which the daemon can
+find the Bacula plugins. If this directive is not specified, Bacula will not
+load any plugins. Since each plugin has a distinctive name, all the daemons
+can share the same plugin directory. 
+
+\subsection{Plugin Options}
+\index[general]{Plugin Options}
+The {\bf Plugin Options} directive takes a quoted string
+arguement (after the equal sign) and may be specified in the
+Job resource.  The options specified will be passed to all plugins
+when they are run.  This each plugin must know what it is looking
+for. The value defined in the Job resource can be modified
+by the user when he runs a Job via the {\bf bconsole} command line 
+prompts.
+
+Note: this directive may be specified, and there is code to modify
+the string in the run command, but the plugin options are not yet passed to
+the plugin (i.e. not fully implemented).
+
+\subsection{Plugin Options ACL}
+\index[general]{Plugin Options ACL}
+The {\bf Plugin Options ACL} directive may be specified in the
+Director's Console resource. It functions as all the other ACL commands
+do by permitting users running restricted consoles to specify a 
+{\bf Plugin Options} that overrides the one specified in the Job
+definition. Without this directive restricted consoles may not modify
+the Plugin Options.
+
+\subsection{Plugin = \lt{}plugin-command-string\gt{}}
+\index[general]{Plugin}
+The {\bf Plugin} directive is specified in the Include section of
+a FileSet resource where you put your {\bf File = xxx} directives.
+For example:
+
+\begin{verbatim}
+  FileSet {
+    Name = "MyFileSet"
+    Include {
+      Options {
+        signature = MD5
+      }
+      File = /home
+      Plugin = "bpipe:..."
+    }
+  }
+\end{verbatim}
+
+In the above example, when the File daemon is processing the directives
+in the Include section, it will first backup all the files in {\bf /home}
+then it will load the plugin named {\bf bpipe} (actually bpipe-dir.so) from
+the Plugin Directory.  The syntax and semantics of the Plugin directive
+require the first part of the string up to the colon (:) to be the name
+of the plugin. Everything after the first colon is ignored by the File daemon but
+is passed to the plugin. Thus the plugin writer may define the meaning of the
+rest of the string as he wishes.
+
+Please see the next section for information about the {\bf bpipe} Bacula
+plugin.
+
+\section{The bpipe Plugin}
+\index[general]{The bpipe Plugin}
+The {\bf bpipe} plugin is provided in the directory src/plugins/fd/bpipe-fd.c of
+the Bacula source distribution. When the plugin is compiled and linking into
+the resulting dynamic shared object (DSO), it will have the name {\bf bpipe-fd.so}.
+
+The purpose of the plugin is to provide an interface to any system program for
+backup and restore. As specified above the {\bf bpipe} plugin is specified in
+the Include section of your Job's FileSet resource.  The full syntax of the
+plugin directive as interpreted by the {\bf bpipe} plugin (each plugin is free
+to specify the sytax as it wishes) is:
+
+\begin{verbatim}
+  Plugin = "<field1>:<field2>:<field3>:<field4>"
+\end{verbatim}
+
+where
+\begin{description}
+\item {\bf field1} is the name of the plugin with the trailing {\bf -fd.so}
+stripped off, so in this case, we would put {\bf bpipe} in this field.
+
+\item {\bf field2} specifies the namespace, which for {\bf bpipe} is the
+pseudo path and filename under which the backup will be saved. This pseudo
+path and filename will be seen by the user in the restore file tree.
+For example, if the value is {\bf /MYSQL/regress.sql}, the data
+backed up by the plugin will be put under that "pseudo" path and filename.
+You must be careful to choose a naming convention that is unique to avoid
+a conflict with a path and filename that actually exists on your system.
+
+\item {\bf field3} for the {\bf bpipe} plugin 
+specifies the "reader" program that is called by the plugin during
+backup to read the data. {\bf bpipe} will call this program by doing a
+{\bf popen} on it.
+
+\item {\bf field4} for the {\bf bpipe} plugin
+specifies the "writer" program that is called by the plugin during
+restore to write the data back to the filesystem.  
+\end{description}
+
+Putting it all together, the full plugin directive line might look
+like the following:
+
+\begin{verbatim}
+Plugin = "bpipe:/MYSQL/regress.sql:mysqldump -f 
+          --opt --databases bacula:mysql"
+\end{verbatim}
+
+The directive has been split into two lines, but within the {\bf bacula-dir.conf} file
+would be written on a single line.
+
+This causes the File daemon to call the {\bf bpipe} plugin, which will write
+its data into the "pseudo" file {\bf /MYSQL/regress.sql} by calling the 
+program {\bf mysqldump -f --opt --database bacula} to read the data during
+backup. The mysqldump command outputs all the data for the database named
+{\bf bacula}, which will be read by the plugin and stored in the backup.
+During restore, the data that was backed up will be sent to the program
+specified in the last field, which in this case is {\bf mysql}.  When
+{\bf mysql} is called, it will read the data sent to it by the plugn
+then write it back to the same database from which it came ({\bf bacula}
+in this case).
+
+The {\bf bpipe} plugin is a generic pipe program, that simply transmits 
+the data from a specified program to Bacula for backup, and then from Bacula to 
+a specified program for restore.
+
+By using different command lines to {\bf bpipe},
+you can backup any kind of data (ASCII or binary) depending
+on the program called.
+
+\section{Microsoft Exchange Server 2003/2007 Plugin}
+\index[general]{Microsoft Exchange Server 2003/2007 Plugin}
+\subsection{Background}
+The Exchange plugin was made possible by a funded development project
+between Equiinet Ltd -- www.equiinet.com (many thanks) and Bacula Systems.
+The code for the plugin was written by James Harper, and the Bacula core
+code by Kern Sibbald.  All the code for this funded development has become
+part of the Bacula project.  Thanks to everyone who made it happen.
+
+\subsection{Concepts}
+Although it is possible to backup Exchange using Bacula VSS the Exchange 
+plugin adds a good deal of functionality, because while Bacula VSS
+completes a full backup (snapshot) of Exchange, it does
+not support Incremental or Differential backups, restoring is more
+complicated, and a single database restore is not possible.
+
+Microsoft Exchange organises its storage into Storage Groups with
+Databases inside them. A default installation of Exchange will have a
+single Storage Group called 'First Storage Group', with two Databases
+inside it, "Mailbox Store (SERVER NAME)" and 
+"Public Folder Store (SERVER NAME)", 
+which hold user email and public folders respectively.
+
+In the default configuration, Exchange logs everything that happens to
+log files, such that if you have a backup, and all the log files since,
+you can restore to the present time. Each Storage Group has its own set
+of log files and operates independently of any other Storage Groups. At
+the Storage Group level, the logging can be turned off by enabling a
+function called "Enable circular logging". At this time the Exchange
+plugin will not function if this option is enabled.
+
+The plugin allows backing up of entire storage groups, and the restoring
+of entire storage groups or individual databases. Backing up and
+restoring at the individual mailbox or email item is not supported but
+can be simulated by use of the "Recovery" Storage Group (see below).
+
+\subsection{Installing}
+The Exchange plugin requires a DLL that is shipped with Microsoft
+Exchanger Server called {\bf esebcli2.dll}. Assuming Exchange is installed
+correctly the Exchange plugin should find this automatically and run
+without any additional installation.
+
+If the DLL can not be found automatically it will need to be copied into
+the Bacula installation
+directory (eg C:\verb+\+Program Files\verb+\+Bacula\verb+\+bin). The Exchange API DLL is
+named esebcli2.dll and is found in C:\verb+\+Program Files\verb+\+Exchsrvr\verb+\+bin on a
+default Exchange installation.
+
+\subsection{Backup up}
+To back up an Exchange server the Fileset definition must contain at
+least {\bf Plugin = "exchange:/@EXCHANGE/Microsoft Information Store"} for
+the backup to work correctly. The 'exchange:' bit tells Bacula to look
+for the exchange plugin, the '@EXCHANGE' bit makes sure all the backed
+up files are prefixed with something that isn't going to share a name
+with something outside the plugin, and the 'Microsoft Information Store'
+bit is required also. It is also possible to add the name of a storage
+group to the "Plugin =" line, eg \\
+{\bf Plugin = "exchange:/@EXCHANGE/Microsoft Information Store/First Storage Group"} \\
+if you want only a single storage group backed up.
+
+Additionally, you can suffix the 'Plugin =' directive with
+":notrunconfull" which will tell the plugin not to truncate the Exchange
+database at the end of a full backup.
+
+An Incremental or Differential backup will backup only the database logs
+for each Storage Group by inspecting the "modified date" on each
+physical log file. Because of the way the Exchange API works, the last
+logfile backed up on each backup will always be backed up by the next
+Incremental or Differential backup too. This adds 5MB to each
+Incremental or Differential backup size but otherwise does not cause any
+problems.
+
+By default, a normal VSS fileset containing all the drive letters will
+also back up the Exchange databases using VSS. This will interfere with
+the plugin and Exchange's shared ideas of when the last full backup was
+done, and may also truncate log files incorrectly. It is important,
+therefore, that the Exchange database files be excluded from the backup,
+although the folders the files are in should be included, or they will
+have to be recreated manually if a baremetal restore is done.
+
+\begin{verbatim}
+FileSet {
+   Include {
+      File = C:/Program Files/Exchsrvr/mdbdata
+      Plugin = "exchange:..."
+   }
+   Exclude {
+      File = C:/Program Files/Exchsrvr/mdbdata/E00.chk
+      File = C:/Program Files/Exchsrvr/mdbdata/E00.log
+      File = C:/Program Files/Exchsrvr/mdbdata/E000000F.log
+      File = C:/Program Files/Exchsrvr/mdbdata/E0000010.log
+      File = C:/Program Files/Exchsrvr/mdbdata/E0000011.log
+      File = C:/Program Files/Exchsrvr/mdbdata/E00tmp.log
+      File = C:/Program Files/Exchsrvr/mdbdata/priv1.edb
+   }
+}
+\end{verbatim}
+
+The advantage of excluding the above files is that you can significantly
+reduce the size of your backup since all the important Exchange files
+will be properly saved by the Plugin.
+
+
+\subsection{Restoring}
+The restore operation is much the same as a normal Bacula restore, with
+the following provisos:
+
+\begin{itemize}
+\item  The {\bf Where} restore option must not be specified
+\item Each Database directory must be marked as a whole. You cannot just
+     select (say) the .edb file and not the others.
+\item If a Storage Group is restored, the directory of the Storage Group
+     must be marked too.
+\item  It is possible to restore only a subset of the available log files,
+     but they {\bf must} be contiguous. Exchange will fail to restore correctly
+     if a log file is missing from the sequence of log files
+\item Each database to be restored must be dismounted and marked as "Can be
+    overwritten by restore"
+\item If an entire Storage Group is to be restored (eg all databases and
+   logs in the Storage Group), then it is best to manually delete the
+   database files from the server (eg C:\verb+\+Program Files\verb+\+Exchsrvr\verb+\+mdbdata\verb+\+*)
+   as Exchange can get confused by stray log files lying around.
+\end{itemize}
+
+\subsection{Restoring to the Recovery Storage Group}
+The concept of the Recovery Storage Group is well documented by
+Microsoft 
+\elink{http://support.microsoft.com/kb/824126}{http://support.microsoft.com/kb/824126}, 
+but to briefly summarize...
+
+Microsoft Exchange allows the creation of an additional Storage Group
+called the Recovery Storage Group, which is used to restore an older
+copy of a database (e.g. before a mailbox was deleted) into without
+messing with the current live data. This is required as the Standard and
+Small Business Server versions of Exchange can not ordinarily have more
+than one Storage Group.
+
+To create the Recovery Storage Group, drill down to the Server in Exchange
+System Manager, right click, and select
+{\bf "New -> Recovery Storage Group..."}.  Accept or change the file
+locations and click OK. On the Recovery Storage Group, right click and
+select {\bf "Add Database to Recover..."} and select the database you will
+be restoring.
+
+Restore only the single database nominated as the database in the
+Recovery Storage Group. Exchange will redirect the restore to the
+Recovery Storage Group automatically.
+Then run the restore.
+
+\subsection{Restoring on Microsoft Server 2007}
+Apparently the {\bf Exmerge} program no longer exists in Microsoft Server
+2007, and henc you use a new proceedure for recovering a single mail box.
+This procedure is ducomented by Microsoft at:
+\elink{http://technet.microsoft.com/en-us/library/aa997694.aspx}{http://technet.microsoft.com/en-us/library/aa997694.aspx},
+and involves using the {\bf Restore-Mailbox} and {\bf
+Get-MailboxStatistics} shell commands.
+
+\subsection{Caveats}
+This plugin is still being developed, so you should consider it
+currently in BETA test, and thus use in a production environment
+should be done only after very careful testing.
+
+When doing a full backup, the Exchange database logs are truncated by
+Exchange as soon as the plugin has completed the backup. If the data
+never makes it to the backup medium (eg because of spooling) then the
+logs will still be truncated, but they will also not have been backed
+up. A solution to this is being worked on. You will have to schedule a
+new Full backup to ensure that your next backups will be usable.
+
+The "Enable Circular Logging" option cannot be enabled or the plugin
+will fail.
+
+Exchange insists that a successful Full backup must have taken place if
+an Incremental or Differential backup is desired, and the plugin will
+fail if this is not the case. If a restore is done, Exchange will
+require that a Full backup be done before an Incremental or Differential
+backup is done.
+
+The plugin will most likely not work well if another backup application
+(eg NTBACKUP) is backing up the Exchange database, especially if the
+other backup application is truncating the log files.
+
+The Exchange plugin has not been tested with the {\bf Accurate} option, so
+we recommend either carefully testing or that you avoid this option for
+the current time.
+
+The Exchange plugin is not called during processing the bconsole {\bf
+estimate} command, and so anything that would be backed up by the plugin
+will not be added to the estimate total that is displayed.
+
+
+\section{libdbi Framework}
+\index[general]{libdbi Framework}
+As a general guideline, Bacula has support for a few catalog database drivers
+(MySQL, PostgreSQL, SQLite)
+coded natively by the Bacula team.  With the libdbi implementation, which is a
+Bacula driver that uses libdbi to access the catalog, we have an open field to
+use many different kinds database engines following the needs of users.
+
+The according to libdbi (http://libdbi.sourceforge.net/) project: libdbi
+implements a database-independent abstraction layer in C, similar to the
+DBI/DBD layer in Perl. Writing one generic set of code, programmers can
+leverage the power of multiple databases and multiple simultaneous database
+connections by using this framework.
+
+Currently the libdbi driver in Bacula project only supports the same drivers
+natively coded in Bacula.  However the libdbi project has support for many
+others database engines. You can view the list at
+http://libdbi-drivers.sourceforge.net/. In the future all those drivers can be
+supported by Bacula, however, they must be tested properly by the Bacula team.
+
+Some of benefits of using libdbi are:
+\begin{itemize}
+\item The possibility to use proprietary databases engines in which your
+  proprietary licenses prevent the Bacula team from developing the driver.
+ \item The possibility to use the drivers written for the libdbi project.
+ \item The possibility to use other database engines without recompiling Bacula
+   to use them.  Just change one line in bacula-dir.conf
+ \item Abstract Database access, this is, unique point to code and profiling
+   catalog database access.
+ \end{itemize}
+ The following drivers have been tested:
+ \begin{itemize}
+ \item PostgreSQL, with and without batch insert
+ \item Mysql, with and without batch insert
+ \item SQLite
+ \item SQLite3
+ \end{itemize}
+
+ In the future, we will test and approve to use others databases engines
+ (proprietary or not) like DB2, Oracle, Microsoft SQL.
+
+ To compile Bacula to support libdbi we need to configure the code with the
+ --with-dbi and --with-dbi-driver=[database] ./configure options, where
+ [database] is the database engine to be used with Bacula (of course we can
+ change the driver in file bacula-dir.conf, see below).  We must configure the
+ access port of the database engine with the option --with-db-port, because the
+ libdbi framework doesn't know the default access port of each database.
+
+The next phase is checking (or configuring) the bacula-dir.conf, example:
+\begin{verbatim}
+Catalog {
+  Name = MyCatalog
+  dbdriver = dbi:mysql; dbaddress = 127.0.0.1; dbport = 3306
+  dbname = regress; user = regress; password = ""
+}
+\end{verbatim}
+
+The parameter {\bf dbdriver} indicates that we will use the driver dbi with a
+mysql database.  Currently the drivers supported by Bacula are: postgresql,
+mysql, sqlite, sqlite3; these are the names that may be added to string "dbi:".
+
+The following limitations apply when Bacula is set to use the libdbi framework:
+ - Not tested on the Win32 platform
+ - A little performance is lost if comparing with native database driver. 
+   The reason is bound with the database driver provided by libdbi and the 
+   simple fact that one more layer of code was added.
+
+It is important to remember, when compiling Bacula with libdbi, the
+following packages are needed:
+ \begin{itemize}
+  \item libdbi version 1.0.0, http://libdbi.sourceforge.net/
+  \item libdbi-drivers 1.0.0, http://libdbi-drivers.sourceforge.net/
+ \end{itemize}
+ You can download them and compile them on your system or install the packages
+ from your OS distribution.
+
+\section{Console Command Additions and Enhancements}
+\index[general]{Console Additions}                                 
+
+\subsection{Display Autochanger Content}
+\index[general]{StatusSlots}
+
+The {\bf status slots storage=\lt{}storage-name\gt{}} command displays
+autochanger content.
+
+\footnotesize
+\begin{verbatim}
+ Slot |  Volume Name  |  Status  |  Media Type       |   Pool     |
+------+---------------+----------+-------------------+------------|
+    1 |         00001 |   Append |  DiskChangerMedia |    Default |
+    2 |         00002 |   Append |  DiskChangerMedia |    Default |
+    3*|         00003 |   Append |  DiskChangerMedia |    Scratch |
+    4 |               |          |                   |            |
+\end{verbatim}
+\normalsize
+
+If you an asterisk ({\bf *}) appears after the slot number, you must run an
+{\bf update slots} command to synchronize autochanger content with your
+catalog.
+
+\subsection{list joblog job=xxx or jobid=nnn}
+\index[general]{list joblog}
+A new list command has been added that allows you to list the contents
+of the Job Log stored in the catalog for either a Job Name (fully qualified)
+or for a particular JobId.  The {\bf llist} command will include a line with
+the time and date of the entry.
+
+Note for the catalog to have Job Log entries, you must have a directive 
+such as:
+
+\begin{verbatim}
+  catalog = all
+\end{verbatim}
+
+In your Director's {\bf Messages} resource.
+
+\subsection{Use separator for multiple commands}
+\index[general]{Command Separator}
+  When using bconsole with readline, you can set the command separator with 
+  \textbf{@separator} command to one
+  of those characters to write commands who require multiple input in one line.
+\begin{verbatim}
+  !$%&'()*+,-/:;<>?[]^`{|}~
+\end{verbatim}
+
+\subsection{Deleting Volumes}
+The delete volume bconsole command has been modified to
+require an asterisk (*) in front of a MediaId otherwise the
+value you enter is a taken to be a Volume name. This is so that
+users may delete numeric Volume names. The previous Bacula versions
+assumed that all input that started with a number was a MediaId.
+
+This new behavior is indicated in the prompt if you read it
+carefully.
+
+\section{Bare Metal Recovery}
+The old bare metal recovery project is essentially dead. One
+of the main features of it was that it would build a recovery
+CD based on the kernel on your system. The problem was that
+every distribution has a different boot procedure and different 
+scripts, and worse yet, the boot procedures and scripts change
+from one distribution to another.  This meant that maintaining
+(keeping up with the changes) the rescue CD was too much work.
+
+To replace it, a new bare metal recovery USB boot stick has been developed
+by Bacula Systems.  This technology involves remastering a Ubuntu LiveCD to
+boot from a USB key.  
+
+Advantages: 
+\begin{enumerate} 
+\item Recovery can be done from within graphical environment.  
+\item Recovery can be done in a shell.  
+\item Ubuntu boots on a large number of Linux systems.  
+\item The process of updating the system and adding new
+   packages is not too difficult. 
+\item The USB key can easily be upgraded to newer Ubuntu versions.
+\item The USB key has writable partitions for modifications to
+   the OS and for modification to your home directory.
+\item You can add new files/directories to the USB key very easily.
+\item You can save the environment from multiple machines on
+   one USB key.
+\item Bacula Systems is funding its ongoing development.
+\end{enumerate}
+
+The disadvantages are:
+\begin{enumerate}
+\item The USB key is usable but currently under development.
+\item Not everyone may be familiar with Ubuntu (no worse
+  than using Knoppix)
+\item Some older OSes cannot be booted from USB. This can
+   be resolved by first booting a Ubuntu LiveCD then plugging
+   in the USB key.
+\item Currently the documentation is sketchy and not yet added
+   to the main manual. See below ...
+\end{enumerate}
+
+The documentation and the code can be found in the {\bf rescue} package
+in the directory {\bf linux/usb}.
+
+\section{Miscellaneous}
+\index[general]{Misc New Features}
+
+\subsection{Allow Mixed Priority = \lt{}yes\vb{}no\gt{}}
+\index[general]{Allow Mixed Priority}
+   This directive is only implemented in version 2.5 and later.  When
+   set to {\bf yes} (default {\bf no}), this job may run even if lower
+   priority jobs are already running.  This means a high priority job
+   will not have to wait for other jobs to finish before starting.
+   The scheduler will only mix priorities when all running jobs have
+   this set to true.
+
+   Note that only higher priority jobs will start early.  Suppose the
+   director will allow two concurrent jobs, and that two jobs with
+   priority 10 are running, with two more in the queue.  If a job with
+   priority 5 is added to the queue, it will be run as soon as one of
+   the running jobs finishes.  However, new priority 10 jobs will not
+   be run until the priority 5 job has finished.
+
+\subsection{Bootstrap File Directive -- FileRegex}
+\index[general]{Bootstrap File Directive}
+  {\bf FileRegex} is a new command that can be added to the bootstrap
+  (.bsr) file.  The value is a regular expression.  When specified, only
+  matching filenames will be restored.
+
+  During a restore, if all File records are pruned from the catalog
+  for a Job, normally Bacula can restore only all files saved. That
+  is there is no way using the catalog to select individual files.
+  With this new feature, Bacula will ask if you want to specify a Regex
+  expression for extracting only a part of the full backup.
+
+\begin{verbatim}
+  Building directory tree for JobId(s) 1,3 ...
+  There were no files inserted into the tree, so file selection
+  is not possible.Most likely your retention policy pruned the files
+  
+  Do you want to restore all the files? (yes\vb{}no): no
+  
+  Regexp matching files to restore? (empty to abort): /tmp/regress/(bin|tests)/
+  Bootstrap records written to /tmp/regress/working/zog4-dir.restore.1.bsr
+\end{verbatim}
+
+\subsection{Bootstrap File Optimization Changes}
+In order to permit proper seeking on disk files, we have extended the bootstrap
+file format to include a {\bf VolStartAddr} and {\bf VolEndAddr} records. Each
+takes a 64 bit unsigned integer range (i.e. nnn-mmm) which defines the start
+address range and end address range respectively.  These two directives replace
+the {\bf VolStartFile}, {\bf VolEndFile}, {\bf VolStartBlock} and {\bf
+  VolEndBlock} directives.  Bootstrap files containing the old directives will
+still work, but will not properly take advantage of proper disk seeking, and
+may read completely to the end of a disk volume during a restore.  With the new
+format (automatically generated by the new Director), restores will seek
+properly and stop reading the volume when all the files have been restored.
+
+\subsection{Solaris ZFS/NFSv4 ACLs}
+This is an upgrade of the previous Solaris ACL backup code
+to the new library format, which will backup both the old
+POSIX(UFS) ACLs as well as the ZFS ACLs.
+
+The new code can also restore POSIX(UFS) ACLs to a ZFS filesystem
+(it will translate the POSIX(UFS)) ACL into a ZFS/NFSv4 one) it can also
+be used to transfer from UFS to ZFS filesystems.
+
+
+\subsection{Virtual Tape Emulation}
+\index[general]{Virtual Tape Emulation}
+We now have a Virtual Tape emulator that allows us to run though 99.9\% of
+the tape code but actually reading and writing to a disk file. Used with the
+\textbf{disk-changer} script, you can now emulate an autochanger with 10 drives
+and 700 slots. This feature is most useful in testing.  It is enabled
+by using {\bf Device Type = vtape} in the Storage daemon's Device
+directive. This feature is only implemented on Linux machines and should not be
+used for production.
+
+\subsection{Bat Enhancements}
+\index[general]{Bat Enhancements}
+Bat (the Bacula Administration Tool) GUI program has been significantly
+enhanced and stabilized. In particular, there are new table based status 
+commands; it can now be easily localized using Qt4 Linguist.
+
+The Bat communications protocol has been significantly enhanced to improve
+GUI handling. Note, you {\bf must} use a the bat that is distributed with
+the Director you are using otherwise the communications protocol will not
+work.
+
+\subsection{RunScript Enhancements}
+\index[general]{RunScript Enhancements}
+The {\bf RunScript} resource has been enhanced to permit multiple
+commands per RunScript.  Simply specify multiple {\bf Command} directives
+in your RunScript.
+
+\begin{verbatim}
+Job {
+  Name = aJob
+  RunScript {
+    Command = "/bin/echo test"
+    Command = "/bin/echo an other test"
+    Command = "/bin/echo 3 commands in the same runscript"
+    RunsWhen = Before
+  }
+ ...
+}
+\end{verbatim}
+
+A new Client RunScript {\bf RunsWhen} keyword of {\bf AfterVSS} has been
+implemented, which runs the command after the Volume Shadow Copy has been made.
+
+Console commands can be specified within a RunScript by using:
+{\bf Console = \lt{}command\gt{}}, however, this command has not been 
+carefully tested and debugged and is known to easily crash the Director.
+We would appreciate feedback.  Due to the recursive nature of this command, we
+may remove it before the final release.
+
+\subsection{Status Enhancements}
+\index[general]{Status Enhancements}
+The bconsole {\bf status dir} output has been enhanced to indicate
+Storage daemon job spooling and despooling activity.
+
+\subsection{Connect Timeout}
+\index[general]{Connect Timeout}
+The default connect timeout to the File
+daemon has been set to 3 minutes. Previously it was 30 minutes.
+
+\subsection{ftruncate for NFS Volumes}
+\index[general]{ftruncate for NFS Volumes}
+If you write to a Volume mounted by NFS (say on a local file server),
+in previous Bacula versions, when the Volume was recycled, it was not
+properly truncated because NFS does not implement ftruncate (file 
+truncate). This is now corrected in the new version because we have
+written code (actually a kind user) that deletes and recreates the Volume,
+thus accomplishing the same thing as a truncate.
+
+\subsection{Support for Ubuntu}
+The new version of Bacula now recognizes the Ubuntu (and Kubuntu)
+version of Linux, and thus now provides correct autostart routines.
+Since Ubuntu officially supports Bacula, you can also obtain any
+recent release of Bacula from the Ubuntu repositories.
+
+\subsection{Recycle Pool = \lt{}pool-name\gt{}}
+\index[general]{Recycle Pool}
+The new \textbf{RecyclePool} 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.
+
+\subsection{FD Version}
+\index[general]{FD Version}
+The File daemon to Director protocol now includes a version 
+number, which although there is no visible change for users, 
+will help us in future versions automatically determine
+if a File daemon is not compatible.
+
+\subsection{Max Run Sched Time = \lt{}time-period-in-seconds\gt{}}
+\index[general]{Max Run Sched Time}
+The time specifies the maximum allowed time that a job may run, counted from
+when the job was scheduled. This can be useful to prevent jobs from running
+during working hours. We can see it like \texttt{Max Start Delay + Max Run
+  Time}.
+
+\subsection{Max Wait Time = \lt{}time-period-in-seconds\gt{}}
+\index[general]{Max Wait Time}
+Previous \textbf{MaxWaitTime} directives aren't working as expected, instead
+of checking the maximum allowed time that a job may block for a resource,
+those directives worked like \textbf{MaxRunTime}. Some users are reporting to
+use \textbf{Incr/Diff/Full Max Wait Time} to control the maximum run time of
+their job depending on the level. Now, they have to use
+\textbf{Incr/Diff/Full Max Run Time}.  \textbf{Incr/Diff/Full Max Wait Time}
+directives are now deprecated.
+
+\subsection{Incremental|Differential Max Wait Time = \lt{}time-period-in-seconds\gt{}} 
+\index[general]{Incremental Max Wait Time}
+\index[general]{Differential Max Wait Time}
+
+These directives have been deprecated in favor of
+\texttt{Incremental|Differential Max Run Time}.
+
+\subsection{Max Run Time directives}
+\index[general]{Max Run Time directives}
+Using \textbf{Full/Diff/Incr Max Run Time}, it's now possible to specify the
+maximum allowed time that a job can run depending on the level.
+
+\addcontentsline{lof}{figure}{Job time control directives}
+\includegraphics{\idir different_time.eps}
+
+\subsection{Statistics Enhancements}
+\index[general]{Statistics Enhancements}
+If you (or probably your boss) want to have statistics on your backups to
+provide some \textit{Service Level Agreement} indicators, you could use a few
+SQL queries on the Job table to report how many:
+
+\begin{itemize}
+\item jobs have run
+\item jobs have been successful
+\item files have been backed up
+\item ...
+\end{itemize}
+
+However, these statistics are accurate only if your job retention is greater
+than your statistics period. Ie, if jobs are purged from the catalog, you won't
+be able to use them. 
+
+Now, you can use the \textbf{update stats [days=num]} console command to fill
+the JobHistory table with new Job records. If you want to be sure to take in
+account only \textbf{good jobs}, ie if one of your important job has failed but
+you have fixed the problem and restarted it on time, you probably want to
+delete the first \textit{bad} job record and keep only the successful one. For
+that simply let your staff do the job, and update JobHistory table after two or
+three days depending on your organization using the \textbf{[days=num]} option.
+
+These statistics records aren't used for restoring, but mainly for
+capacity planning, billings, etc.
+
+The Bweb interface provides a statistics module that can use this feature. You
+can also use tools like Talend or extract information by yourself.
+
+The \textbf{Statistics Retention = \lt{}time\gt{}} director directive defines
+the length of time that Bacula will keep statistics job records in the Catalog
+database after the Job End time. (In \texttt{JobHistory} table) When this time
+period expires, and if user runs \texttt{prune stats} command, Bacula will
+prune (remove) Job records that are older than the specified period.
+
+You can use the following Job resource in your nightly \textbf{BackupCatalog}
+job to maintain statistics.
+\begin{verbatim}
+Job {
+  Name = BackupCatalog
+  ...
+  RunScript {
+    Console = "update stats days=3"
+    Console = "prune stats yes"
+    RunsWhen = After
+    RunsOnClient = no
+  }
+}
+\end{verbatim}
+
+\subsection{ScratchPool = \lt{}pool-resource-name\gt{}}
+\index[general]{ScratchPool}
+This directive permits to specify a specific \textsl{Scratch} pool for the
+current pool. This is useful when using multiple storage sharing the same
+mediatype or when you want to dedicate volumes to a particular set of pool.
+
+\subsection{Enhanced Attribute Despooling}
+\index[general]{Attribute Despooling}
+If the storage daemon and the Director are on the same machine, the spool file
+that contains attributes is read directly by the Director instead of being
+transmitted across the network. That should reduce load and speedup insertion.
+
+\subsection{SpoolSize = \lt{}size-specification-in-bytes\gt{}}
+\index[general]{SpoolSize}
+A new Job directive permits to specify the spool size per job. This is used
+in advanced job tunning. {\bf SpoolSize={\it bytes}}
+
+\subsection{MaxConsoleConnections = \lt{}number\gt{}}
+\index[general]{MaxConsoleConnections}
+A new director directive permits to specify the maximum number of Console
+Connections that could run concurrently. The default is set to 20, but you may
+set it to a larger number.
+
+\subsection{VerId = \lt{}string\gt{}}
+\index[general]{VerId}
+A new director directive permits to specify a personnal identifier that will be
+displayed in the \texttt{version} command.
+
+\subsection{dbcheck enhancements}
+\index[general]{dbcheck enhancements}
+If you are using Mysql, dbcheck will now ask you if you want to create
+temporary indexes to speed up orphaned Path and Filename elimination. 
+
+A new \texttt{-B} option allows you to print catalog information in a simple
+text based format. This is useful to backup it in a secure way.
+
+\begin{verbatim}
+ $ dbcheck -B 
+ catalog=MyCatalog
+ db_type=SQLite
+ db_name=regress
+ db_driver=
+ db_user=regress
+ db_password=
+ db_address=
+ db_port=0
+ db_socket=
+\end{verbatim} %$
+
+You can now specify the database connection port in the command line.
+
+\subsection{{-}{-}docdir configure option}
+\index[general]{{-}{-}docdir configure option}
+You can use {-}{-}docdir= on the ./configure command to
+specify the directory where you want Bacula to install the
+LICENSE, ReleaseNotes, ChangeLog, ... files.   The default is 
+{\bf /usr/share/doc/bacula}.
+      
+\subsection{{-}{-}htmldir configure option}
+\index[general]{{-}{-}htmldir configure option}
+You can use {-}{-}htmldir= on the ./configure command to
+specify the directory where you want Bacula to install the bat html help
+files. The default is {\bf /usr/share/doc/bacula/html}
+
+\subsection{{-}{-}with-plugindir configure option}
+\index[general]{{-}{-}plugindir configure option}
+You can use {-}{-}plugindir= on the ./configure command to
+specify the directory where you want Bacula to install
+the plugins (currently only bpipe-fd). The default is
+/usr/lib.
diff --git a/docs/manuals/en/main/pools.tex b/docs/manuals/en/main/pools.tex
new file mode 100644 (file)
index 0000000..10217f8
--- /dev/null
@@ -0,0 +1,429 @@
+%%
+%%
+
+\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
diff --git a/docs/manuals/en/main/postgresql.tex b/docs/manuals/en/main/postgresql.tex
new file mode 100644 (file)
index 0000000..f688ff1
--- /dev/null
@@ -0,0 +1,470 @@
+%%
+%%
+
+\chapter{Installing and Configuring PostgreSQL}
+\label{PostgreSqlChapter}
+\index[general]{PostgreSQL!Installing and Configuring }
+\index[general]{Installing and Configuring PostgreSQL }
+\index[general]{Upgrading}
+
+If you are considering using PostreSQL, you should be aware
+of their philosophy of upgrades, which could be 
+destabilizing for a production shop.  Basically at every major version
+upgrade, you are required to dump your database in an ASCII format, 
+do the upgrade, and then reload your database (or databases). This is
+because they frequently update the "data format" from version to   
+version, and they supply no tools to automatically do the conversion.
+If you forget to do the ASCII dump, your database may become totally
+useless because none of the new tools can access it due to the format
+change, and the PostgreSQL server will not be able to start.
+
+If you are building PostgreSQL from source, please be sure to add
+the {\bf \verb:--:enable-thread-safety} option when doing the ./configure
+for PostgreSQL.  
+
+\section{Installing PostgreSQL}
+\index[general]{PostgreSQL!Installing }
+
+If you use the {\bf ./configure \verb:--:with-postgresql=PostgreSQL-Directory}
+statement for configuring {\bf Bacula}, you will need PostgreSQL version 7.4
+or later installed. NOTE! PostgreSQL versions earlier than 7.4 do not work
+with Bacula. If PostgreSQL is installed in the standard system location, you
+need only enter {\bf \verb:--:with-postgresql} since the configure program will
+search all the standard locations. If you install PostgreSQL in your home
+directory or some other non-standard directory, you will need to provide the
+full path with the {\bf \verb:--:with-postgresql} option. 
+
+Installing and configuring PostgreSQL is not difficult but can be confusing
+the first time. If you prefer, you may want to use a package provided by your
+chosen operating system. Binary packages are available on most PostgreSQL
+mirrors. 
+
+If you prefer to install from source, we recommend following the instructions
+found in the 
+\elink{PostgreSQL documentation}{http://www.postgresql.org/docs/}. 
+
+If you are using FreeBSD, 
+\elink{this FreeBSD Diary article}{http://www.freebsddiary.org/postgresql.php}
+will be useful. Even if you are not using FreeBSD, the article will contain
+useful configuration and setup information. 
+
+If you configure the Batch Insert code in Bacula (attribute inserts are
+10 times faster), you {\bf must} be using a PostgreSQL that was built with
+the {\bf \verb:--:enable-thread-safety} option, otherwise you will get
+data corruption. Most major Linux distros have thread safety turned on, but
+it is better to check.  One way is to see if the PostgreSQL library that
+Bacula will be linked against references pthreads.  This can be done
+with a command such as:
+
+\footnotesize
+\begin{verbatim}
+  nm /usr/lib/libpq.a | grep pthread_mutex_lock
+\end{verbatim}
+\normalsize
+
+The above command should print a line that looks like:
+
+\footnotesize
+\begin{verbatim}
+         U pthread_mutex_lock
+\end{verbatim}
+\normalsize
+
+if does, then everything is OK. If it prints nothing, do not enable batch
+inserts when building Bacula.
+
+After installing PostgreSQL, 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 PostgreSQL installation are created during the Bacula
+Installation. You must still come back to complete the second phase of the 
+PostgreSQL installation even if you installed binaries (e.g. rpm, deb,
+...).
+
+
+\label{PostgreSQL_configure}
+\section{Configuring PostgreSQL}
+\index[general]{PostgreSQL!Configuring PostgreSQL -- }
+
+At this point, you should have built and installed PostgreSQL, or already have
+a running PostgreSQL, 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-postgresql=PostgreSQL-directory}, where {\bf
+PostgreSQL-directory} is the directory name that you specified on the
+./configure command for configuring PostgreSQL (if you didn't specify a
+directory or PostgreSQL is installed in a default location, you do not need to
+specify the directory). This is needed so that Bacula can find the necessary
+include headers and library files for interfacing to PostgreSQL. 
+
+{\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\_postgresql\_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 PostgreSQL database and the tables that Bacula
+uses. These instructions assume that you already have PostgreSQL running. You
+will need to perform these steps as a user that is able to create new
+databases. This can be the PostgreSQL user (on most systems, this is the pgsql
+user). 
+
+\begin{enumerate}
+\item cd \lt{}install-directory\gt{}
+
+   This directory contains the Bacula catalog  interface routines.  
+
+\item ./create\_bacula\_database
+
+   This script creates the PostgreSQL {\bf bacula} database.  
+   Before running this command, you should carefully think about
+   what encoding sequence you want for the text fields (paths, files, ...).
+   Ideally, the encoding should be set to UTF8. However, many Unix systems
+   have filenames that are not encoded in UTF8, either because you have
+   not set UTF8 as your default character set or because you have imported
+   files from elsewhere (e.g. MacOS X).  For this reason, Bacula uses
+   SQL\_ASCII as the default encoding.  If you want to change this,
+   please modify the script before running it, but be forewarned that
+   Bacula backups will fail if PostgreSQL finds any non-UTF8 sequences.
+
+   If running the script fails, it is probably because the database is
+   owned by a user other than yourself.  On many systems, the database
+   owner is {\bf pgsql} and on others such as Red Hat and Fedora it is {\bf
+   postgres}.  You can find out which it is by examining your /etc/passwd
+   file.  To create a new user under either your name or with say the name
+   {\bf bacula}, you can do the following:
+
+\begin{verbatim}
+   su
+   (enter root password)
+   su pgsql (or postgres)
+   createuser kern (or perhaps 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) (choose
+         what you want)
+   exit
+\end{verbatim}
+    
+    At this point, you should be able to execute the
+    ./create\_bacula\_database command.
+
+\item ./make\_bacula\_tables
+
+   This script creates the PostgreSQL tables used by {\bf Bacula}.  
+\item ./grant\_bacula\_privileges
+
+   This script creates the database user {\bf bacula}  with restricted access
+rights. You may  want to modify it to suit your situation. Please note that 
+this database is not password protected.  
+
+\end{enumerate}
+
+Each of the three scripts (create\_bacula\_database, make\_bacula\_tables, and
+grant\_bacula\_privileges) allows the addition of a command line argument.
+This can be useful for specifying the user name. For example, you might need
+to add {\bf -h hostname} to the command line to specify a remote database
+server. 
+
+To take a closer look at the access privileges that you have setup with the
+above, you can do: 
+
+\footnotesize
+\begin{verbatim}
+PostgreSQL-directory/bin/psql --command \\dp bacula
+\end{verbatim}
+\normalsize
+
+Also, I had an authorization problem with the password. In the end,
+I had to modify my {\bf pg\_hba.conf} file (in /var/lib/pgsql/data on my machine)
+from:
+
+\footnotesize
+\begin{verbatim}
+  local   all    all        ident  sameuser
+to
+  local   all    all        trust
+\end{verbatim}
+\normalsize
+
+This solved the problem for me, but it is not always a good thing
+to do from a security standpoint.  However, it allowed me to run
+my regression scripts without having a password.
+
+A more secure way to perform database authentication is with md5
+password hashes.  Begin by editing the {\bf pg\_hba.conf} file, and
+just prior the the existing ``local'' and ``host'' lines, add the line:
+
+\footnotesize
+\begin{verbatim}
+  local bacula bacula md5
+\end{verbatim}
+\normalsize
+
+and restart the Postgres database server (frequently, this can be done
+using "/etc/init.d/postgresql restart" or "service postgresql restart") to
+put this new authentication rule into effect.
+
+Next, become the Postgres administrator, postgres, either by logging
+on as the postgres user, or by using su to become root and then using
+su - postgres to become postgres.  Add a password to the bacula
+database for the bacula user using:
+
+\footnotesize
+\begin{verbatim}
+  \$ psql bacula
+  bacula=# alter user bacula with password 'secret';
+  ALTER USER
+  bacula=# \\q
+\end{verbatim}
+\normalsize
+
+You'll have to add this password to two locations in the
+bacula-dir.conf file: once to the Catalog resource and once to the
+RunBeforeJob entry in the BackupCatalog Job resource.  With the
+password in place, these two lines should look something like:
+
+\footnotesize
+\begin{verbatim}
+  dbname = bacula; user = bacula; password = "secret"
+    ... and ...
+  # WARNING!!! Passing the password via the command line is insecure.
+  # see comments in make_catalog_backup for details.
+  RunBeforeJob = "/etc/make_catalog_backup bacula bacula secret"
+\end{verbatim}
+\normalsize
+
+Naturally, you should choose your own significantly more random
+password, and ensure that the bacula-dir.conf file containing this
+password is readable only by the root.
+
+Even with the files containing the database password properly
+restricted, there is still a security problem with this approach: on
+some platforms, the environment variable that is used to supply the
+password to Postgres is available to all users of the
+local system.  To eliminate this problem, the Postgres team have
+deprecated the use of the environment variable password-passing
+mechanism and recommend the use of a .pgpass file instead.  To use
+this mechanism, create a file named .pgpass containing the single
+line:
+
+\footnotesize
+\begin{verbatim}
+  localhost:5432:bacula:bacula:secret
+\end{verbatim}
+\normalsize
+
+This file should be copied into the home directory of all accounts
+that will need to gain access to the database: typically, root,
+bacula, and any users who will make use of any of the console
+programs.  The files must then have the owner and group set to match
+the user (so root:root for the copy in ~root, and so on), and the mode
+set to 600, limiting access to the owner of the file.
+
+\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_bacula_tables
+  ./make_bacula_tables
+  ./grant_bacula_privileges
+\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{Installing PostgreSQL from RPMs}
+\index[general]{PostgreSQL!Installing from RPMs}
+\index[general]{Installing PostgreSQL from RPMs}
+If you are installing PostgreSQL from RPMs, you will need to install
+both the PostgreSQL binaries and the client libraries.  The client
+libraries are usually found in a devel package, so you must
+install:
+
+\footnotesize
+\begin{verbatim}
+  postgresql
+  postgresql-devel
+  postgresql-server
+  postgresql-libs
+\end{verbatim}
+\normalsize
+
+These will be similar with most other package managers too.  After
+installing from rpms, you will still need to run the scripts that set up
+the database and create the tables as described above.
+
+
+\section{Converting from MySQL to PostgreSQL}
+\index[general]{PostgreSQL!Converting from MySQL to }
+\index[general]{Converting from MySQL to PostgreSQL }
+
+The conversion procedure presented here was worked out by Norm Dressler
+\lt{}ndressler at dinmar dot com\gt{} 
+
+This process was tested using the following software versions: 
+
+\begin{itemize}
+\item Linux Mandrake 10/Kernel 2.4.22-10 SMP 
+\item Mysql Ver 12.21 Distrib 4.0.15, for mandrake-linux-gnu (i586) 
+\item PostgreSQL 7.3.4 
+\item Bacula 1.34.5 
+   \end{itemize}
+
+WARNING: Always as a precaution, take a complete backup of your databases
+before proceeding with this process! 
+
+\begin{enumerate}
+\item Shutdown bacula (cd /etc/bacula;./bacula stop)  
+\item Run the following command to dump your Mysql database:  
+
+   \footnotesize
+\begin{verbatim}
+       mysqldump -f -t -n >bacula-backup.dmp
+    
+\end{verbatim}
+\normalsize
+
+\item Make a backup of your /etc/bacula directory (but leave the  original in
+   place).  
+\item Go to your Bacula source directory and rebuild it to include  PostgreSQL
+   support rather then Mysql support. Check the  config.log file for your
+   original configure command and replace  enable-mysql with enable-postgresql.  
+\item Recompile Bacula with a make and if everything compiles  completely,
+   perform a make install.  
+\item Shutdown Mysql. 
+\item Start PostgreSQL on your system.  
+\item Create a bacula user in Postgres with the createuser command.  Depending on
+   your Postgres install, you may have to SU to the  user who has privileges to
+   create a user.  
+\item Verify your pg\_hba.conf file contains sufficient permissions to  allow
+   bacula to access the server. Mine has the following since  it's on a secure
+   network:  
+
+\footnotesize
+\begin{verbatim}
+local all all trust
+                
+host all all 127.0.0.1 255.255.255.255 trust
+                
+NOTE: you should restart your postgres server if you
+      made changes
+      
+\end{verbatim}
+\normalsize
+
+\item Change into the /etc/bacula directory and prepare the database  and
+   tables with the following commands:  
+
+\footnotesize
+\begin{verbatim}
+./create_postgresql_database
+                                
+./make_postgresql_tables
+                                
+./grant_postgresql_privileges
+       
+\end{verbatim}
+\normalsize
+
+\item Verify you have access to the database:  
+
+   \footnotesize
+\begin{verbatim}
+  
+psql -Ubacula bacula
+      
+\end{verbatim}
+\normalsize
+
+You should not get any errors.  
+\item Load your database from the Mysql database dump with:  
+
+   \footnotesize
+\begin{verbatim}
+psql -Ubacula bacula <bacula-backup.dmp>
+      
+\end{verbatim}
+\normalsize
+
+\item Resequence your tables with the following commands:  
+
+   \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 At this point, start up Bacula, verify your volume library and  perform
+   a test backup to make sure everything is working  properly. 
+\end{enumerate}
+
+\section{Upgrading PostgreSQL}
+\index[general]{Upgrading PostgreSQL }
+\index[general]{Upgrading!PostgreSQL }
+\index[general]{Upgrading}
+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{Tuning PostgreSQL}
+\index[general]{Tuning} 
+
+If you despool attributes for many jobs at the same time, you can tune the
+sequence object for the \texttt{FileId} field.
+\begin{verbatim}
+psql -Ubacula bacula
+
+ALTER SEQUENCE file_fileid_seq CACHE 1000;
+\end{verbatim}
+
+\section{Credits}
+\index[general]{Credits }
+Many thanks to Dan Langille for writing the PostgreSQL driver. This will
+surely become the most popular database that Bacula supports. 
diff --git a/docs/manuals/en/main/quickstart.tex b/docs/manuals/en/main/quickstart.tex
new file mode 100644 (file)
index 0000000..e99a018
--- /dev/null
@@ -0,0 +1,389 @@
+%%
+%%
+
+\chapter{Getting Started with Bacula}
+\label{QuickStartChapter}
+\index[general]{Getting Started with Bacula }
+
+If you are like me, you want to get Bacula running immediately to get a feel
+for it, then later you want to go back and read about all the details. This
+chapter attempts to accomplish just that: get you going quickly without all
+the details. If you want to skip the section on Pools, Volumes and Labels, you
+can always come back to it, but please read to the end of this chapter, and in
+particular follow the instructions for testing your tape drive. 
+
+We assume that you have managed to build and install Bacula, if not, you might
+want to first look at the 
+\ilink{System Requirements}{SysReqs} then at the 
+\ilink{Compiling and Installing Bacula}{InstallChapter} chapter of
+this manual. 
+
+\label{JobsandSchedules}
+\section{Understanding Jobs and Schedules}
+\index[general]{Jobs!Understanding}
+\index[general]{Schedules!Understanding}
+
+In order to make Bacula as flexible as possible, the directions given 
+to Bacula are specified in several pieces.  The main instruction is the 
+job resource, which defines a job.  A backup job generally consists of a 
+FileSet, a Client, a Schedule for one or several levels or times of backups, 
+a Pool, as well as additional instructions. Another way of looking
+at it is the FileSet is what to backup; the Client is who to backup; the
+Schedule defines when, and the Pool defines where (i.e. what Volume).
+
+Typically one FileSet/Client combination will have one corresponding job.
+Most of the directives, such as FileSets, Pools, Schedules, can be mixed
+and matched among the jobs.  So you might have two different Job
+definitions (resources) backing up different servers using the same
+Schedule, the same Fileset (backing up the same directories on two machines)
+and maybe even the same Pools.  The Schedule will define what type of
+backup will run when (e.g. Full on Monday, incremental the rest of the
+week), and when more than one job uses the same schedule, the job priority
+determines which actually runs first.  If you have a lot of jobs, you might
+want to use JobDefs, where you can set defaults for the jobs, which can
+then be changed in the job resource, but this saves rewriting the
+identical parameters for each job.  In addition to the FileSets you want to
+back up, you should also have a job that backs up your catalog.
+
+Finally, be aware that in addition to the backup jobs there are 
+restore, verify, and admin jobs, which have different requirements.
+
+\label{PoolsVolsLabels}
+\section{Understanding Pools, Volumes and Labels}
+\index[general]{Labels!Understanding Pools Volumes and }
+\index[general]{Understanding Pools, Volumes and Labels }
+
+If you have been using a program such as {\bf tar} to backup your system,
+Pools, Volumes, and labeling may be a bit confusing at first. A Volume is a
+single physical tape (or possibly a single file) on which Bacula will write
+your backup data. Pools group together Volumes so that a backup is not
+restricted to the length of a single Volume (tape). Consequently, rather than
+explicitly naming Volumes in your Job, you specify a Pool, and Bacula will
+select the next appendable Volume from the Pool and request you to mount it. 
+% TODO: can't it mount it itself if already available?
+
+Although the basic Pool options are specified in the Director's Pool resource,
+the {\bf real} Pool is maintained in the Bacula Catalog. It contains
+information taken from the Pool resource (bacula-dir.conf) as well as
+information on all the Volumes that have been added to the Pool. Adding
+Volumes to a Pool is usually done manually with the Console program using the
+{\bf label} command. 
+
+For each Volume, Bacula maintains a fair amount of catalog information such as
+the first write date/time, the last write date/time, the number of files on
+the Volume, the number of bytes on the Volume, the number of Mounts, etc. 
+
+Before Bacula will read or write a Volume, the physical Volume must have a
+Bacula software label so that Bacula can be sure the correct Volume is
+mounted. This is usually done using the {\bf label} command in the Console
+program. 
+
+The steps for creating a Pool, adding Volumes to it, and writing software
+labels to the Volumes, may seem tedious at first, but in fact, they are quite
+simple to do, and they allow you to use multiple Volumes (rather than being
+limited to the size of a single tape). Pools also give you significant
+flexibility in your backup process. For example, you can have a "Daily" Pool
+of Volumes for Incremental backups and a "Weekly" Pool of Volumes for Full
+backups. By specifying the appropriate Pool in the daily and weekly backup
+Jobs, you thereby insure that no daily Job ever writes to a Volume in the
+Weekly Pool and vice versa, and Bacula will tell you what tape is needed and
+when. 
+
+For more on Pools, see the 
+\ilink{Pool Resource}{PoolResource} section of the Director
+Configuration chapter, or simply read on, and we will come back to this
+subject later. 
+
+\section{Setting Up Bacula Configuration Files}
+\label{config}
+\index[general]{Setting Up Bacula Configuration Files }
+\index[general]{Files!Setting Up Bacula Configuration }
+
+% TODO: this assumes installation from source:
+After running the appropriate {\bf ./configure} command and doing
+a {\bf make}, and a {\bf make install}, if this is the first time
+you are running Bacula, you must create valid configuration files
+for the Director, the File daemon, the Storage daemon, and the
+Console programs.  If you have followed our recommendations,
+default configuration files as well as the daemon binaries will
+be located in your installation directory.  In any case, the
+binaries are found in the directory you specified on the {\bf
+\verb:--:sbindir} option to the {\bf ./configure} command, and
+the configuration files are found in the directory you specified
+on the {\bf \verb:--:sysconfdir} option.
+
+When initially setting up Bacula you will need to invest a bit of time in
+modifying the default configuration files to suit your environment. This may
+entail starting and stopping Bacula a number of times until you get everything
+right. Please do not despair. Once you have created your configuration files,
+you will rarely need to change them nor will you stop and start Bacula very
+often. Most of the work will simply be in changing the tape when it is full. 
+
+\subsection{Configuring the Console Program}
+\index[general]{Configuring the Console Program }
+\index[general]{Program!Configuring the Console }
+
+The Console program is used by the administrator to interact with the Director
+and to manually start/stop Jobs or to obtain Job status information. 
+
+The Console configuration file is found in the directory specified on the
+{\bf \verb:--:sysconfdir} option that you specified on the {\bf
+./configure} command and by default is named {\bf bconsole.conf}.
+
+If you choose to build the GNOME console with the {\bf
+\verb:--:enable-gnome} option, you also find a default configuration file
+for it, named {\bf bgnome-console.conf}.
+
+The same applies to the wxWidgets console, which is build with the {\bf
+\verb:--:enable-bwx-console} option, and the name of the default
+configuration file is, in this case, {\bf bwx-console.conf}.
+
+Normally, for first time users, no change is needed to these files. Reasonable
+defaults are set. 
+
+Further details are in the
+\ilink{Console configuration}{ConsoleConfChapter} chapter.
+
+\subsection{Configuring the Monitor Program}
+\index[general]{Program!Configuring the Monitor }
+\index[general]{Configuring the Monitor Program }
+
+The Monitor program is typically an icon in the system tray. However, once the
+icon is expanded into a full window, the administrator or user can obtain
+status information about the Director or the backup status on the local
+workstation or any other Bacula daemon that is configured. 
+
+\addcontentsline{lof}{figure}{Bacula Tray Monitor}
+\includegraphics{\idir Bacula-tray-monitor.eps} 
+
+% TODO: image may be too wide for 6" wide printed page.
+The image shows a tray-monitor configured for three daemons. By clicking on
+the radio buttons in the upper left corner of the image, you can see the
+status for each of the daemons. The image shows the status for the Storage
+daemon (MainSD) that is currently selected. 
+
+The Monitor configuration file is found in the directory specified on the {\bf
+\verb:--:sysconfdir} option that you specified on the {\bf ./configure} command
+and
+by default is named {\bf tray-monitor.conf}. Normally, for first time users,
+you just need to change the permission of this file to allow non-root users to
+run the Monitor, as this application must run as the same user as the
+graphical environment (don't forget to allow non-root users to execute {\bf
+bacula-tray-monitor}). This is not a security problem as long as you use the
+default settings. 
+
+More information is in the
+\ilink{Monitor configuration}{_MonitorChapter} chapter.
+
+\subsection{Configuring the File daemon}
+\index[general]{Daemon!Configuring the File }
+\index[general]{Configuring the File daemon }
+
+The File daemon is a program that runs on each (Client) machine. At the
+request of the Director, finds the files to be backed up and sends them (their
+data) to the Storage daemon. 
+
+The File daemon configuration file is found in the directory specified on
+the {\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure}
+command. By default, the File daemon's configuration file is named {\bf
+bacula-fd.conf}. Normally, for first time users, no change is needed to this
+file. Reasonable defaults are set. However, if you are going to back up more
+than one machine, you will need to install the File daemon with a unique
+configuration file on each machine to be backed up. The information about each
+File daemon must appear in the Director's configuration file. 
+% TODO: point to section about how to install just the File daemon
+% TODO: and creating the unique configuration file.
+
+Further details are in the 
+\ilink{File daemon configuration}{FiledConfChapter} chapter.
+
+\subsection{Configuring the Director}
+\index[general]{Director!Configuring the }
+\index[general]{Configuring the Director }
+
+The Director is the central control program for all the other daemons. It
+schedules and monitors all jobs to be backed up. 
+
+The Director configuration file is found in the directory specified on the
+{\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure}
+command. Normally the Director's configuration file is named {\bf bacula-dir.conf}. 
+
+In general, the only change you must make is modify the FileSet resource so
+that the {\bf Include} configuration directive contains at least one line with
+a valid name of a directory (or file) to be saved. 
+
+% TODO: is DLT still the default config?
+If you do not have a DLT tape drive, you will probably want to edit the
+Storage resource to contain names that are more representative of your actual
+storage device. You can always use the existing names as you are free to
+arbitrarily assign them, but they must agree with the corresponding names in
+the Storage daemon's configuration file. 
+
+You may also want to change the email address for notification from the
+default {\bf root} to your email address. 
+
+Finally, if you have multiple systems to be backed up, you will need a
+separate File daemon or Client specification for each system, specifying its
+% TODO: I don't see any example "File" configuraton in the default
+% TODO: bacula-dir.conf; I do see FileDaemon config in the default
+% TODO: bacula-fd.conf. Be more clear about this or point to explanation
+% TODO: about this.
+name, address, and password. We have found that giving your daemons the same
+% TODO: what passwords should I use? I have different ones in the
+% TODO: different configs on different systems. Point to explanation of
+% this.
+name as your system but post fixed with {\bf -fd} helps a lot in debugging.
+That is, if your system name is {\bf foobaz}, you would give the File daemon
+the name {\bf foobaz-fd}. For the Director, you should use {\bf foobaz-dir},
+and for the storage daemon, you might use {\bf foobaz-sd}. 
+Each of your Bacula components {\bf must} have a unique name.  If you
+make them all the same, aside from the fact that you will not
+know what daemon is sending what message, if they share the same
+working directory, the daemons temporary file names will not
+be unique, and you will get many strange failures.
+% TODO: why not check for that and not allow sharing working directory?
+
+More information is in the
+\ilink{Director configuration}{DirectorChapter} chapter.
+
+\subsection{Configuring the Storage daemon}
+\index[general]{Daemon!Configuring the Storage }
+\index[general]{Configuring the Storage daemon }
+
+The Storage daemon is responsible, at the Director's request, for accepting
+data from a File daemon and placing it on Storage media, or in the case of a
+restore request, to find the data and send it to the File daemon. 
+
+The Storage daemon's configuration file is found in the directory specified on
+the {\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure}
+command. By default, the Storage daemon's file is named {\bf bacula-sd.conf}.
+Edit this file to contain the correct Archive device names for any tape
+devices that you have. If the configuration process properly detected your
+system, they will already be correctly set. These Storage resource name and
+Media Type must be the same as the corresponding ones in the Director's
+configuration file {\bf bacula-dir.conf}. If you want to backup to a file
+instead of a tape, the Archive device must point to a directory in which the
+Volumes will be created as files when you label the Volume. 
+\label{ConfigTesting}
+
+Further information is in the
+\ilink{Storage daemon configuration}{StoredConfChapter} chapter.
+
+\section{Testing your Configuration Files}
+\index[general]{Testing your Configuration Files }
+\index[general]{Files!Testing your Configuration }
+
+You can test if your configuration file is syntactically correct by running
+the appropriate daemon with the {\bf -t} option. The daemon will process the
+configuration file and print any error messages then terminate. For example,
+assuming you have installed your binaries and configuration files in the same
+directory. 
+% TODO: why assume that? common default install has the executable
+% TODO: is in ./sbin and the configs are in ./etc. So maybe just have
+% TODO: example correct or change default install to be same.
+
+\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
+./bgnome-console -t -c bgnome-console.conf
+./bwx-console -t -c bwx-console.conf
+./bat -t -c bat.conf
+su <normal user> -c "./bacula-tray-monitor -t -c tray-monitor.conf"
+\end{verbatim}
+\normalsize
+
+will test the configuration files of each of the main programs. If the
+configuration file is OK, the program will terminate without printing
+anything. Please note that, depending on the configure options you choose,
+some, or even all, of the three last commands will not be available on your
+system. If you have installed the binaries in traditional Unix locations
+rather than a single file, you will need to modify the above commands
+appropriately (no ./ in front of the command name, and a path in front of the
+conf file name). 
+\label{TapeTesting}
+
+\section{Testing Compatibility with Your Tape Drive}
+\index[general]{Drive!Testing Bacula Compatibility with Your Tape}
+\index[general]{Testing Bacula Compatibility with Your Tape Drive}
+
+Before spending a lot of time on Bacula only to find that it doesn't work
+with your tape drive, please read the {\bf Testing Your Tape
+Drive} chapter of this manual.  If you have a modern
+standard SCSI tape drive on a Linux or Solaris, most likely it will work,
+but better test than be sorry.  For FreeBSD (and probably other xBSD
+flavors), reading the above mentioned tape testing chapter is a must.
+Also, for FreeBSD, please see \elink{The FreeBSD
+Diary}{\url{http://www.freebsddiary.org/bacula.php}} for a detailed description
+%TODO: fix elink so it shows URL in PDF
+on how to make Bacula work on your system.  In addition, users of FreeBSD
+prior to 4.9-STABLE dated Mon Dec 29 15:18:01 2003 UTC who plan to use tape
+devices, please see the file {\bf platforms/freebsd/pthreads-fix.txt} in
+the main Bacula directory concerning important information concerning
+compatibility of Bacula and your system.  \label{notls}
+
+\section{Get Rid of the /lib/tls Directory}
+\index[general]{Directory!Get Rid of the /lib/tls }
+\index[general]{Get Rid of the /lib/tls Directory }
+The new pthreads library {\bf /lib/tls} installed by default on recent Red
+Hat systems running Linux kernel 2.4.x is defective.  You must remove it or
+rename it, then reboot your system before running Bacula otherwise after a
+week or so of running, Bacula will either block for long periods or
+deadlock entirely.  You may want to use the loader environment variable
+override rather than removing /lib/tls.  Please see \ilink{ Supported
+Operating Systems}{SupportedOSes} for more information on this problem.
+
+This problem does not occur on systems running Linux 2.6.x kernels. 
+
+\label{Running1}
+
+\section{Running Bacula}
+\index[general]{Bacula!Running }
+\index[general]{Running Bacula }
+
+Probably the most important part of running Bacula is being able to restore
+files. If you haven't tried recovering files at least once, when you actually
+have to do it, you will be under a lot more pressure, and prone to make
+errors, than if you had already tried it once. 
+
+To get a good idea how to use Bacula in a short time, we {\bf strongly}
+recommend that you follow the example in the 
+\ilink{Running Bacula Chapter}{TutorialChapter} of this manual where
+you will get detailed instructions on how to run Bacula. 
+
+\section{Log Rotation}
+\index[general]{Rotation!Log }
+\index[general]{Log Rotation }
+If you use the default {\bf bacula-dir.conf} or some variation of it, you will
+note that it logs all the Bacula output to a file. To avoid that this file
+grows without limit, we recommend that you copy the file {\bf logrotate} from
+the {\bf scripts/logrotate} to {\bf /etc/logrotate.d/bacula}. This will cause
+the log file to be rotated once a month and kept for a maximum of five months.
+You may want to edit this file to change the default log rotation preferences.
+
+\section{Log Watch}
+\index[general]{Watch!Log}
+\index[general]{Log Watch}
+Some systems such as Red Hat and Fedora run the logwatch program
+every night, which does an analysis of your log file and sends an
+email report.  If you wish to include the output from your Bacula 
+jobs in that report, please look in the {\bf scripts/logwatch}
+directory.  The {\bf README} file in that directory gives a brief
+explanation on how to install it and what kind of output to expect.
+
+
+\section{Disaster Recovery}
+\index[general]{Recovery!Disaster }
+\index[general]{Disaster Recovery }
+
+If you intend to use Bacula as a disaster recovery tool rather than simply a
+program to restore lost or damaged files, you will want to read the 
+\ilink{Disaster Recovery Using Bacula Chapter}{RescueChapter} of
+this manual. 
+
+In any case, you are strongly urged to carefully test restoring some files
+that you have saved rather than wait until disaster strikes. This way, you
+will be prepared.
diff --git a/docs/manuals/en/main/recycling.tex b/docs/manuals/en/main/recycling.tex
new file mode 100644 (file)
index 0000000..f2cdfed
--- /dev/null
@@ -0,0 +1,723 @@
+%%
+%%
+
+\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 the 
+Volume Status is {\bf Purged}. At that point, it will choose the oldest 
+purged volume and recycle it.
+
+If there are no volumes with Status {\bf Purged}, then 
+the recycling occurs in two steps:
+The first is that the Catalog for a Volume must be pruned of all Jobs (i.e.
+Purged).  Files contained on that Volume, and the second step is the actual
+recycling of the Volume.  Only Volumes marked {\bf Full} or {\bf Used} will
+be considerd for pruning.  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. 
diff --git a/docs/manuals/en/main/requirements.tex b/docs/manuals/en/main/requirements.tex
new file mode 100644 (file)
index 0000000..9dbeed9
--- /dev/null
@@ -0,0 +1,67 @@
+%%
+%%
+
+\chapter{System Requirements}
+\label{SysReqs}
+\index[general]{System Requirements }
+\index[general]{Requirements!System }
+
+\begin{itemize}
+\item {\bf Bacula} has been compiled and run on OpenSuSE Linux, FreeBSD, and
+   Solaris systems. 
+\item It requires GNU C++ version 2.95 or higher to compile. You can try  with
+   other compilers and older versions, but you are on your own.  We have
+   successfully compiled and used Bacula using GNU C++ version 4.1.3.
+   Note, in general GNU C++ is a separate package (e.g.  RPM) from GNU C, so you
+   need them both loaded. On Red Hat systems, the C++ compiler is part of the
+   {\bf gcc-c++} rpm package. 
+\item There are certain third party packages that Bacula may need.  Except for
+   MySQL and PostgreSQL, they can all be found in the  {\bf depkgs} and {\bf
+   depkgs1} releases. However, most current Linux and FreeBSD systems
+   provide these as system packages.
+\item The minimum versions for each of the databases supported by Bacula
+   are:
+
+   \begin{itemize}
+   \item MySQL 4.1
+   \item PostgreSQL 7.4
+   \item SQLite 2.8.16 or SQLite 3
+   \end{itemize}
+
+\item If you want to build the Win32 binaries, please see the
+   README.mingw32 file in the src/win32 directory. We cross-compile the
+   Win32 release on Linux. We provide documentation on building the Win32
+   version, but due to the complexity, you are pretty much on your own
+   if you want to build it yourself.
+\item {\bf Bacula} requires a good implementation of pthreads to work.  This
+   is not the case on some of the BSD systems. 
+\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. 
+\item The GNOME Console program is developed and tested under GNOME 2.x.
+   GNOME 1.4 is no longer supported.
+\item The wxWidgets Console program is developed and tested with the latest 
+   stable ANSI or Unicode version of 
+   \elink{wxWidgets}{\url{http://www.wxwidgets.org/}} (2.6.1).  It works fine with the
+   Windows and GTK+-2.x version of wxWidgets, and should  also work on other
+   platforms supported by wxWidgets. 
+\item The Tray Monitor program is developed for GTK+-2.x. It needs  GNOME less
+   or equal to 2.2, KDE greater or equal to 3.1 or any window manager supporting
+   the  
+   \elink{ FreeDesktop system tray
+   standard}{\url{http://www.freedesktop.org/Standards/systemtray-spec}}. 
+\item If you want to enable command line editing and history, you will  need
+   to have /usr/include/termcap.h and either the termcap or the  ncurses library
+   loaded (libtermcap-devel or ncurses-devel). 
+\item If you want to use DVD as backup medium, you will need to download the
+   \elink{dvd+rw-tools 5.21.4.10.8}{\url{http://fy.chalmers.se/~appro/linux/DVD+RW/}},
+   apply the patch that is in the {\bf patches} directory of the main
+   source tree
+   to make these tools compatible with Bacula, then compile and install them.
+   There is also a patch for dvd+rw-tools version 6.1, and we hope that the
+   patch is integrated into a later version.
+   Do not use the dvd+rw-tools provided by your distribution, unless you
+   are sure it contains the patch. dvd+rw-tools without the patch will not
+   work with Bacula. DVD media is not recommended for serious or important
+   backups because of its low reliability.
+\end{itemize}
diff --git a/docs/manuals/en/main/rescue.tex b/docs/manuals/en/main/rescue.tex
new file mode 100644 (file)
index 0000000..573bf01
--- /dev/null
@@ -0,0 +1,804 @@
+%%
+%%
+
+\chapter{Disaster Recovery Using Bacula}
+\label{RescueChapter}
+\index[general]{Disaster Recovery Using Bacula}
+\index[general]{Bacula!Disaster Recovery Using}
+\index[general]{Recovery!Disaster Recovery}
+\index[general]{Rescue!Disaster Recovery}
+
+\section{General}
+\index[general]{General}
+
+When disaster strikes, you must have a plan, and you must have prepared in
+advance otherwise the work of recovering your system and your files will be
+considerably greater.  For example, if you have not previously saved the
+partitioning information for your hard disk, how can you properly rebuild
+it if the disk must be replaced?
+
+Unfortunately, many of the steps one must take before and immediately after
+a disaster are very operating system dependent.  As a consequence, this
+chapter will discuss in detail disaster recovery (also called Bare Metal
+Recovery) for {\bf Linux} and {\bf Solaris}.  For Solaris, the procedures
+are still quite manual.  For FreeBSD the same procedures may be used but
+they are not yet developed.  For Win32, a number of Bacula users have
+reported success using BartPE.
+
+
+\label{considerations1}
+\section{Important Considerations}
+\index[general]{Important Considerations}
+\index[general]{Considerations!Important}
+
+Here are a few important considerations concerning disaster recovery that
+you should take into account before a disaster strikes.
+
+\begin{itemize}
+\item If the building which houses your computers burns down or is otherwise 
+   destroyed, do you have off-site backup data? 
+\item Disaster recovery is much easier if you have several machines. If  you
+   have a single machine, how will you handle unforeseen events  if your only
+   machine is down? 
+\item Do you want to protect your whole system and use Bacula to  recover
+   everything? or do you want to try to restore your system from  the original
+   installation disks and apply any other updates and  only restore user files? 
+\end{itemize}
+
+\label{steps1}
+\section{Steps to Take Before Disaster Strikes}
+\index[general]{Steps to Take Before Disaster Strikes}
+\index[general]{Strikes!Steps to Take Before Disaster}
+
+\begin{itemize}
+\item Create a rescue or CDROM for each of your Linux systems. Generally,
+   they are offered by each distribution, and there are many good 
+   rescue disks on the Web (Knoppix, sysrescuecd, PLD Linux rescue CD,
+   tomsrtbt, RIP ...
+
+\item Create a bacula-hostname directory on 
+   each machine and save it somewhere -- possibly on a USB key.
+\item Ensure that you always have a valid bootstrap file for your backup and 
+   that it is saved to an alternate machine.  This will permit you to
+   easily do a full restore of your system.
+\item If possible copy your catalog nightly to an alternate machine.  If you
+   have a valid bootstrap file, this is not necessary, but  can be very useful if
+   you do not want to reload everything. .  
+\item Ensure that you always have a valid bootstrap file for your  catalog
+   backup that is saved to an alternate machine. This will  permit you to restore
+   your catalog more easily if needed.  
+\item Test using the Rescue CDROM before you are forced to use it in
+   an emergency situation.
+\item Make a copy of your Bacula .conf files, particularly your
+   bacula-dir.conf, and your bacula-sd.conf files, because if your server
+   goes down, these files will be needed to get it back up and running,
+   and they can be difficult to rebuild from memory.
+\end{itemize}
+
+\label{rescueCDROM}
+\section{Bare Metal Recovery on Linux with a Rescue CD}
+\index[general]{Bare Metal Recovery on Linux with a Rescue CD}
+\index[general]{CDROM!Bare Metal Recovery on Linux with a Rescue}
+
+As an alternative to creating a Rescue CD, please see the
+section below entitled \ilink{Bare Metal Recovery using a LiveCD}{LiveCD}.
+
+Bacula previously had a Rescue CD.  Unfortunately, this CD did not work
+on every Linux Distro, and in addition, Linux is evolving with different
+boot methods, more and more complex hardware configurations (LVM, RAID, 
+WiFi, USB, ...).  As a consequence, the Bacula Rescue CD as it was
+originally envisioned no longer exists.
+
+However there are many other good rescue disks available.
+A so called "Bare Metal" recovery is one where you start with an empty hard
+disk and you restore your machine. There are also cases where you may lose a
+file or a directory and want it restored. Please see the previous chapter for
+more details for those cases. 
+
+Bare Metal Recovery assumes that you have the following items for your system:
+
+\begin{itemize}
+\item A Rescue CDROM containing a copy of your OS.
+\item Perhaps a copy of your
+   hard disk information, as well as a statically linked version of the
+   Bacula File daemon.  
+\item A full Bacula backup of your system possibly including  Incremental or
+   Differential backups since the last Full  backup 
+\item A second system running the Bacula Director, the Catalog, and the
+   Storage daemon.  (this is not an absolute requirement, but how to get
+   around it is not yet documented here)
+\end{itemize}
+
+\section{Requirements}
+\index[general]{Requirements}
+
+
+\label{restore_client}
+\section{Restoring a Client System}
+\index[general]{Restoring a Client System}
+\index[general]{System!Restoring a Client}
+
+Now, let's assume that your hard disk has just died and that you have replaced
+it with an new identical drive. In addition, we assume that you have: 
+
+\begin{enumerate}
+\item A recent Bacula backup (Full plus Incrementals)  
+\item A Rescue CDROM.  
+\item Your Bacula Director, Catalog, and Storage daemon running  on another
+   machine on your local network. 
+\end{enumerate}
+
+This is a relatively simple case, and later in this chapter, as time permits,
+we will discuss how you might recover from a situation where the machine that
+crashes is your main Bacula server (i.e. has the Director, the Catalog, and
+the Storage daemon). 
+
+You will take the following steps to get your system back up and running: 
+
+\begin{enumerate}
+\item Boot with your Rescue CDROM.  
+\item Start the Network (local network)  
+\item Re-partition your hard disk(s) as it was before  
+\item Re-format your partitions  
+\item Restore the Bacula File daemon (static version)  
+\item Perform a Bacula restore of all your files  
+\item Re-install your boot loader  
+\item Reboot 
+\end{enumerate}
+
+Now for the details ... 
+
+\section{Boot with your Rescue CDROM}
+\index[general]{CDROM!Boot with your Rescue}
+\index[general]{Boot with your Rescue CDROM}
+
+Each rescue disk boots somewhat differently.  Please see the
+instructions that go with your CDROM.
+
+
+\paragraph*{Start the Network:}
+
+\normalsize
+
+You can test it by pinging another machine, or pinging your broken machine
+machine from another machine. Do not proceed until your network is up. 
+
+\paragraph*{Partition Your Hard Disk(s):}
+
+\paragraph*{Format Your Hard Disk(s):}
+
+\paragraph*{Mount the Newly Formatted Disks:}
+
+
+\paragraph*{Somehow get the static File daemon loaded on your system}
+Put the static file daemon and its conf file in /tmp.
+
+\paragraph*{Restore and Start the File Daemon:}
+\footnotesize
+\begin{verbatim}
+chroot /mnt/disk /tmp/bacula-fd -c /tmp/bacula-fd.conf
+\end{verbatim}
+\normalsize
+
+The above command starts the Bacula File daemon with the proper root disk
+location (i.e. {\bf /mnt/disk/tmp}. If Bacula does not start, correct the
+problem and start it. You can check if it is running by entering: 
+
+\footnotesize
+\begin{verbatim}
+ps fax
+\end{verbatim}
+\normalsize
+
+You can kill Bacula by entering: 
+
+\footnotesize
+\begin{verbatim}
+kill -TERM <pid>
+\end{verbatim}
+\normalsize
+
+where {\bf pid} is the first number printed in front of the first occurrence
+of {\bf bacula-fd} in the {\bf ps fax} command. 
+
+Now, you should be able to use another computer with Bacula installed to check
+the status by entering: 
+
+\footnotesize
+\begin{verbatim}
+status client=xxxx
+\end{verbatim}
+\normalsize
+
+into the Console program, where xxxx is the name of the client you are
+restoring. 
+
+One common problem is that your {\bf bacula-dir.conf} may contain machine
+addresses that are not properly resolved on the stripped down system to be
+restored because it is not running DNS. This is particularly true for the
+address in the Storage resource of the Director, which may be very well
+resolved on the Director's machine, but not on the machine being restored and
+running the File daemon. In that case, be prepared to edit {\bf
+bacula-dir.conf} to replace the name of the Storage daemon's domain name with
+its IP address. 
+
+\paragraph*{Restore Your Files:}
+
+On the computer that is running the Director, you now run a {\bf restore}
+command and select the files to be restored (normally everything), but before
+starting the restore, there is one final change you must make using the {\bf
+mod} option. You must change the {\bf Where} directory to be the root by using
+the {\bf mod} option just before running the job and selecting {\bf Where}.
+Set it to: 
+
+\footnotesize
+\begin{verbatim}
+/
+\end{verbatim}
+\normalsize
+
+then run the restore. 
+
+You might be tempted to avoid using {\bf chroot} and running Bacula directly
+and then using a {\bf Where} to specify a destination of {\bf /mnt/disk}. This
+is possible, however, the current version of Bacula always restores files to
+the new location, and thus any soft links that have been specified with
+absolute paths will end up with {\bf /mnt/disk} prefixed to them. In general
+this is not fatal to getting your system running, but be aware that you will
+have to fix these links if you do not use {\bf chroot}. 
+
+\paragraph*{Final Step:}
+
+
+
+\footnotesize
+\begin{verbatim}
+/sbin/grub-install --root-directory=/mnt/disk /dev/hda
+\end{verbatim}
+\normalsize
+
+Note, in this case, you omit the chroot command, and you must
+replace /dev/hda with your boot device.  If you don't know what your
+boot device is, run the ./run\_grub script once and it will tell
+you.
+
+Finally, I've even run into a case where grub-install was unable to
+rewrite the boot block. In my case, it produced the following error
+message:
+
+\footnotesize
+\begin{verbatim}
+/dev/hdx does not have any corresponding BIOS drive.
+\end{verbatim}
+\normalsize
+
+The solution is to insure that all your disks are properly mounted on
+/mnt/disk, then do the following:
+
+\footnotesize
+\begin{verbatim}
+chroot /mnt/disk
+mount /dev/pts
+\end{verbatim}
+\normalsize
+
+Then edit the file {\bf /boot/grub/grub.conf} and uncomment the line
+that reads:
+
+\footnotesize
+\begin{verbatim}
+#boot=/dev/hda
+\end{verbatim}
+\normalsize
+
+So that it reads:
+
+\footnotesize
+\begin{verbatim}
+boot=/dev/hda
+\end{verbatim}
+\normalsize
+
+Note, the /dev/hda may be /dev/sda or possibly some other drive depending
+on your configuration, but in any case, it is the same as the one that
+you previously tried with {\bf grub-install}.
+
+Then, enter the following commands:
+
+\footnotesize
+\begin{verbatim}
+grub --batch --device-map=/boot/grub/device.map \
+  --config-file=/boot/grub/grub.conf --no-floppy
+root (hd0,0)
+setup (hd0)
+quit
+\end{verbatim}
+\normalsize
+
+If the {\bf grub} call worked, you will get a prompt of {\bf grub\gt{}}   
+before the {\bf root}, {\bf setup}, and {\bf quit} commands, and after 
+entering the {\bf setup} command, it should indicate that it successfully
+wrote the MBR (master boot record).
+
+
+\paragraph*{Reboot:}
+
+First unmount all your hard disks, otherwise they will not be cleanly
+shutdown, then reboot your machine by entering {\bf exit} until you get to the
+main prompt then enter {\bf Ctrl-d}. Once back to the main CDROM prompt, you
+will need to turn the power off, then back on to your machine to get it to
+reboot. 
+
+If everything went well, you should now be back up and running. If not,
+re-insert the emergency boot CDROM, boot, and figure out what is wrong. 
+
+\label{restore_server}
+\section{Restoring a Server}
+\index[general]{Restoring a Server}
+\index[general]{Server!Restoring a}
+
+Above, we considered how to recover a client machine where a valid Bacula
+server was running on another machine. However, what happens if your server
+goes down and you no longer have a running Director, Catalog, or Storage
+daemon? There are several solutions: 
+
+\begin{enumerate}
+\item Bring up static versions of your Director, Catalog, and Storage  daemon 
+   on the damaged machine.
+
+\item Move your server to another machine. 
+
+\item Use a Hot Spare Server on another Machine.
+\end{enumerate}
+
+The first option, is very difficult because it requires you to have created a
+static version of the Director and the Storage daemon as well as the Catalog.
+If the Catalog uses MySQL or PostgreSQL, this may or may not be possible. In
+addition, to loading all these programs on a bare system (quite possible), you
+will need to make sure you have a valid driver for your tape drive. 
+
+The second suggestion is probably a much simpler solution, and one I have done
+myself. To do so, you might want to consider the following steps: 
+
+\begin{itemize}
+\item If you are using MySQL or PostgreSQL, configure, build and install it
+   from source (or use rpms) on your new system.  
+\item Load the Bacula source code onto your new system, configure,  install
+   it, and create the Bacula database.  
+\item Ideally, you will have a copy of all the Bacula conf files that
+   were being used on your server. If not, you will at a minimum need
+   create a bacula-dir.conf that has the same Client resource that
+   was used to backup your system.
+\item If you have a valid saved Bootstrap file as created for your  damaged
+   machine with WriteBootstrap, use it to restore the files to the damaged
+   machine, where you have loaded a static Bacula File daemon using the
+   Rescue disk).  This is done by using the restore command and at
+   the yes/mod/no prompt, selecting {\bf mod} then specifying the path to
+   the bootstrap file.
+\item If you have the Bootstrap file, you should now be back up and  running,
+   if you do not have a Bootstrap file, continue with the  suggestions below.  
+\item Using {\bf bscan} scan the last set of backup tapes into your  MySQL,
+   PostgreSQL or SQLite database.  
+\item Start Bacula, and using the Console {\bf restore} command,  restore the
+   last valid copy of the Bacula database and the Bacula configuration
+   files.  
+\item Move the database to the correct location. 
+\item Start the database, and restart Bacula. Then use the Console {\bf
+   restore} command, restore all the files  on the damaged machine, where you
+   have loaded a Bacula File  daemon using the Rescue disk. 
+\end{itemize}
+
+For additional details of restoring your database, please see the
+\ilink{Restoring When Things Go Wrong}{database_restore} section
+of the Console Restore Command chapter of this manual.
+
+
+\label{problems2}
+\section{Linux Problems or Bugs}
+\index[general]{Bugs!Linux Problems or}
+\index[general]{Linux Problems or Bugs}
+
+Since every flavor and every release of Linux is different, there are likely
+to be some small difficulties with the scripts, so please be prepared to edit
+them in a minimal environment. A rudimentary knowledge of {\bf vi} is very
+useful. Also, these scripts do not do everything. You will need to reformat
+Windows partitions by hand, for example. 
+
+Getting the boot loader back can be a problem if you are using {\bf grub}
+because it is so complicated. If all else fails, reboot your system from your
+floppy but using the restored disk image, then proceed to a reinstallation of
+grub (looking at the run-grub script can help). By contrast, lilo is a piece
+of cake. 
+
+\label{LiveCD}
+\section{Bare Metal Recovery using a LiveCD}
+\index[general]{Bare Metal Recovery using a LiveCD}
+\index[general]{Recovery!Bare Metal Recovery using a LiveCD}
+\index[general]{Rescue!Bare Metal Recovery using a LiveCD}
+\index[general]{LiveCD!Bare Metal Recovery using a LiveCD}
+
+As an alternative to the old now defunct Bacula Rescue CDROM, you can use any
+system rescue or LiveCD to recover your system. The big problem
+with most rescue or LiveCDs is that they are not designed to
+capture the current state of your system, so when you boot them on
+a damaged system, you might be somewhat lost -- e.g. how many of
+you remember your exact hard disk partitioning.
+
+This lack can be easily corrected by running the part of the
+Bacula Rescue code that creates a directory containing a   
+static-bacula-fd, a snapshot of your current system disk
+configuration, and scripts that help restoring it.
+
+Before a disaster strikes:
+\begin{enumerate}
+\item Run only the {\bf make bacula} part of the
+  Bacula Rescue procedure to create the static Bacula
+  File daemon, and system disk snapshot. 
+\item Save the directory generated (more details below)
+  preferrably on a CDROM or alternatively to some other
+  system.
+\item Possibly run {\bf make bacula} every night as
+  part of your backup process to ensure that you have
+  a current snapshot of your system.
+\end{enumerate}
+
+Then when disaster strikes, do the following:
+
+\begin{enumerate}
+\item Boot with your system rescue disk or LiveCD
+   (e.g. Knoppix).
+\item Start the Network (local network).  
+\item Copy the Bacula recovery directory to the 
+   damaged system using ftp, scp, wget or if your
+   boot disk permits it reading it directly from a
+   CDROM.
+\item Continue as documented above.
+\item Re-partition your hard disk(s) as it was before,  
+   if necessary.
+\item Re-format your partitions, if necessary.  
+\item Restore the Bacula File daemon (static version).  
+\item Perform a Bacula restore of all your files.  
+\item Re-install your boot loader.  
+\item Reboot. 
+\end{enumerate}
+
+In order to create the Bacula recovery directory, you need
+a copy of the Bacula Rescue code as described above, and
+you must first configure that directory.
+
+Once the configuration is done, you can do the following
+to create the Bacula recovery directory:
+
+\footnotesize
+\begin{verbatim}
+cd <bacula-rescue-source>/linux/cdrom
+su (become root)
+make bacula
+\end{verbatim}
+\normalsize
+
+The directory you want to save will be created in
+the current directory with the name {\bf bacula}.  You
+need only save that directory either as a directory or
+possibly as a compressed tar file.  If you run this procedure
+on multiple machines, you will probably want to rename this directory
+to something like {\bf bacula-hostname}.
+
+
+
+\label{FreeBSD1}
+\section{FreeBSD Bare Metal Recovery}
+\index[general]{Recovery!FreeBSD Bare Metal}
+\index[general]{Rescue!FreeBSD Bare Metal}
+\index[general]{FreeBSD Bare Metal Recovery}
+
+The same basic techniques described above also apply to FreeBSD. Although we
+don't yet have a fully automated procedure, Alex Torres Molina has provided us
+with the following instructions with a few additions from Jesse Guardiani and
+Dan Langille: 
+
+\begin{enumerate}
+\item Boot with the FreeBSD installation disk 
+\item Go to Custom, Partition and create your slices and go to Label and 
+   create the partitions that you want. Apply changes. 
+\item Go to Fixit to start an emergency console. 
+\item Create devs ad0 .. .. if they don't exist under /mnt2/dev (in my  situation)
+   with MAKEDEV. The device or devices you  create depend on what hard drives you
+   have. ad0 is your  first ATA drive. da0 would by your first SCSI drive.  Under
+OS version 5 and greater, your device files are  most likely automatically
+created for you. 
+\item mkdir /mnt/disk
+   this is the root of the new disk 
+\item mount /mnt2/dev/ad0s1a /mnt/disk
+   mount /mnt2/dev/ad0s1c /mnt/disk/var
+   mount /mnt2/dev/ad0s1d /mnt/disk/usr
+.....
+The same hard drive issues as above apply here too.  Note, under OS version 5
+or higher, your disk devices may  be in /dev not /mnt2/dev. 
+\item Network configuration (ifconfig xl0 ip/mask + route add default 
+   ip-gateway) 
+\item mkdir /mnt/disk/tmp 
+\item cd /mnt/disk/tmp 
+\item Copy bacula-fd and bacula-fd.conf to this path 
+\item If you need to, use sftp to copy files, after which you must do this:
+   ln -s /mnt2/usr/bin /usr/bin 
+\item chmod u+x bacula-fd 
+\item Modify bacula-fd.conf to fit this machine 
+\item Copy /bin/sh to /mnt/disk, necessary for chroot 
+\item Don't forget to put your bacula-dir's IP address and domain  name in
+   /mnt/disk/etc/hosts if it's not on a public net.  Otherwise the FD on the
+   machine you are restoring to  won't be able to contact the SD and DIR on the
+remote machine. 
+\item mkdir -p /mnt/disk/var/db/bacula 
+\item chroot /mnt/disk /tmp/bacula-fd -c /tmp/bacula-fd.conf
+   to start bacula-fd 
+\item Now you can go to bacula-dir and restore the job with the entire 
+   contents of the broken server. 
+\item You must create /proc 
+\end{enumerate}
+
+\label{solaris}
+\section{Solaris Bare Metal Recovery}
+\index[general]{Solaris Bare Metal Recovery}
+\index[general]{Recovery!Solaris Bare Metal}
+
+The same basic techniques described above apply to Solaris: 
+
+\begin{itemize}
+\item the same restrictions as those given for Linux apply  
+\item you will need to create a Rescue disk 
+   \end{itemize}
+
+However, during the recovery phase, the boot and disk preparation procedures
+are different: 
+
+\begin{itemize}
+\item there is no need to create an emergency boot disk  since it is an
+   integrated part of the Solaris boot.  
+\item you must partition and format your hard disk by hand  following manual
+   procedures as described in W. Curtis Preston's  book "Unix Backup \&
+   Recovery" 
+\end{itemize}
+
+Once the disk is partitioned, formatted and mounted, you can continue with
+bringing up the network and reloading Bacula. 
+
+\section{Preparing Solaris Before a Disaster}
+\index[general]{Preparing Solaris Before a Disaster}
+\index[general]{Disaster!Preparing Solaris Before a}
+
+As mentioned above, before a disaster strikes, you should prepare the
+information needed in the case of problems. To do so, in the {\bf
+rescue/solaris} subdirectory enter: 
+
+\footnotesize
+\begin{verbatim}
+su
+./getdiskinfo
+./make_rescue_disk
+\end{verbatim}
+\normalsize
+
+The {\bf getdiskinfo} script will, as in the case of Linux described above,
+create a subdirectory {\bf diskinfo} containing the output from several system
+utilities. In addition, it will contain the output from the {\bf SysAudit}
+program as described in Curtis Preston's book. This file {\bf
+diskinfo/sysaudit.bsi} will contain the disk partitioning information that
+will allow you to manually follow the procedures in the "Unix Backup \&
+Recovery" book to repartition and format your hard disk. In addition, the
+{\bf getdiskinfo} script will create a {\bf start\_network} script. 
+
+Once you have your disks repartitioned and formatted, do the following: 
+
+\begin{itemize}
+\item Start Your Network with the {\bf start\_network} script  
+\item Restore the Bacula File daemon as documented above  
+\item Perform a Bacula restore of all your files using the same  commands as
+   described above for Linux  
+\item Re-install your boot loader using the instructions outlined  in the
+   "Unix Backup \& Recovery" book  using installboot 
+\end{itemize}
+
+\label{genbugs}
+
+\section{Bugs and Other Considerations}
+\index[general]{Considerations!Bugs and Other}
+\index[general]{Bugs and Other Considerations}
+
+\paragraph*{Directory Modification and Access Times are Modified on pre-1.30
+Baculas :}
+
+When a pre-1.30 version of Bacula restores a directory, it first must create
+the directory, then it populates the directory with its files and
+subdirectories. The act of creating the files and subdirectories updates both
+the modification and access times associated with the directory itself. As a
+consequence, all modification and access times of all directories will be
+updated to the time of the restore. 
+
+This has been corrected in Bacula version 1.30 and later. The directory
+modification and access times are reset to the value saved in the backup after
+all the files and subdirectories have been restored. This has been tested and
+verified on normal restore operations, but not verified during a bare metal
+recovery. 
+
+\paragraph*{Strange Bootstrap Files:}
+
+If any of you look closely at the bootstrap file that is produced and used for
+the restore (I sure do), you will probably notice that the FileIndex item does
+not include all the files saved to the tape. This is because in some instances
+there are duplicates (especially in the case of an Incremental save), and in
+such circumstances, {\bf Bacula} restores only the last of multiple copies of
+a file or directory. 
+
+\label{Win3233}
+\section{Disaster Recovery of Win32 Systems}
+\index[general]{Systems!Disaster Recovery of Win32}
+\index[general]{Disaster Recovery of Win32 Systems}
+
+Due to open system files, and registry problems, Bacula cannot save and
+restore a complete Win2K/XP/NT environment. 
+
+A suggestion by Damian Coutts using Microsoft's NTBackup utility in
+conjunction with Bacula should permit a Full bare metal restore of Win2K/XP
+(and possibly NT systems). 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. This command
+can be put in a Client Run Before Job directive so that it is automatically
+run during each backup, and thus saved to a Bacula Volume.
+
+To restore the system state, you first reload a base operating system, then
+you would use Bacula to restore all the users files and to recover the {\bf
+c:\textbackslash{}systemstate.bkf} file, and finally, 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. 
+
+This procedure has been confirmed to work by Ludovic Strappazon -- many
+thanks! 
+
+A new tool is provided in the form of a bacula plugin for the BartPE rescue
+CD. BartPE is a self-contained WindowsXP boot CD which you can make using the
+PeBuilder tools available at 
+\elink{http://www.nu2.nu/pebuilder/}{\url{http://www.nu2.nu/pebuilder/}} and a valid
+Windows XP SP1 CDROM. The plugin is provided as a zip archive. Unzip the file
+and copy the bacula directory into the plugin directory of your BartPE
+installation. Edit the configuration files to suit your installation and build
+your CD according to the instructions at Bart's site. This will permit you to
+boot from the cd, configure and start networking, start the bacula file client
+and access your director with the console program. The programs menu on the
+booted CD contains entries to install the file client service, start the file
+client service, and start the WX-Console. You can also open a command line
+window and CD Programs\textbackslash{}Bacula and run the command line console
+bconsole. 
+
+\section{Ownership and Permissions on Win32 Systems}
+\index[general]{Systems!Resetting Directory and File Ownership and Permissions
+on Win32}
+\index[general]{Resetting Directory and File Ownership and Permissions on
+Win32 Systems}
+% TODO: should this be in the win32 chapter?
+
+Bacula versions after 1.31 should properly restore ownership and permissions
+on all WinNT/XP/2K systems. If you do experience problems, generally in
+restores to alternate directories because higher level directories were not
+backed up by Bacula, you can correct any problems with the {\bf SetACL}
+available under the GPL license at: 
+\elink{http://sourceforge.net/projects/setacl/}{\url{http://sourceforge.net/project%
+s/setacl/}}. 
+
+\section{Alternate Disaster Recovery Suggestion for Win32 Systems}
+\index[general]{Systems!Alternate Disaster Recovery Suggestion for Win32}
+\index[general]{Alternate Disaster Recovery Suggestion for Win32 Systems}
+% TODO: should this be in the win32 chapter??
+
+Ludovic Strappazon has suggested an interesting way to backup and restore
+complete Win32 partitions. Simply boot your Win32 system with a Linux Rescue
+disk as described above for Linux, install a statically linked Bacula, and
+backup any of the raw partitions you want. Then to restore the system, you
+simply restore the raw partition or partitions. Here is the email that Ludovic
+recently sent on that subject: 
+
+\footnotesize
+\begin{verbatim}
+I've just finished testing my brand new cd LFS/Bacula
+with a raw Bacula backup and restore of my portable.
+I can't resist sending you the results: look at the rates !!!
+hunt-dir: Start Backup JobId 100, Job=HuntBackup.2003-04-17_12.58.26
+hunt-dir: Bacula 1.30 (14Apr03): 17-Apr-2003 13:14
+JobId:                  100
+Job:                    HuntBackup.2003-04-17_12.58.26
+FileSet:                RawPartition
+Backup Level:           Full
+Client:                 sauvegarde-fd
+Start time:             17-Apr-2003 12:58
+End time:               17-Apr-2003 13:14
+Files Written:          1
+Bytes Written:          10,058,586,272
+Rate:                   10734.9 KB/s
+Software Compression:   None
+Volume names(s):        000103
+Volume Session Id:      2
+Volume Session Time:    1050576790
+Last Volume Bytes:      10,080,883,520
+FD termination status:  OK
+SD termination status:  OK
+Termination:            Backup OK
+hunt-dir: Begin pruning Jobs.
+hunt-dir: No Jobs found to prune.
+hunt-dir: Begin pruning Files.
+hunt-dir: No Files found to prune.
+hunt-dir: End auto prune.
+hunt-dir: Start Restore Job RestoreFilesHunt.2003-04-17_13.21.44
+hunt-sd: Forward spacing to file 1.
+hunt-dir: Bacula 1.30 (14Apr03): 17-Apr-2003 13:54
+JobId:                  101
+Job:                    RestoreFilesHunt.2003-04-17_13.21.44
+Client:                 sauvegarde-fd
+Start time:             17-Apr-2003 13:21
+End time:               17-Apr-2003 13:54
+Files Restored:         1
+Bytes Restored:         10,056,130,560
+Rate:                   5073.7 KB/s
+FD termination status:  OK
+Termination:            Restore OK
+hunt-dir: Begin pruning Jobs.
+hunt-dir: No Jobs found to prune.
+hunt-dir: Begin pruning Files.
+hunt-dir: No Files found to prune.
+hunt-dir: End auto prune.
+\end{verbatim}
+\normalsize
+
+\label{running}
+
+\section{Restoring to a Running System}
+\index[general]{System!Restoring to a Running}
+\index[general]{Restoring to a Running System}
+
+If for some reason you want to do a Full restore to a system that has a
+working kernel (not recommended), you will need to take care not to
+overwrite the following files:
+
+\footnotesize
+\begin{verbatim}
+/etc/grub.conf
+/etc/X11/Conf
+/etc/fstab
+/etc/mtab
+/lib/modules
+/usr/modules
+/usr/X11R6
+/etc/modules.conf
+\end{verbatim}
+\normalsize
+
+\label{Resources}
+
+\section{Additional Resources}
+\index[general]{Additional Resources}
+\index[general]{Resources!Additional}
+
+Many thanks to Charles Curley who wrote 
+\elink{Linux Complete Backup and Recovery HOWTO}
+{\url{http://www.tldp.org/HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO/index.html%
+}} for the 
+\elink{The Linux Documentation Project}{\url{http://www.tldp.org/}}. This is an
+excellent document on how to do Bare Metal Recovery on Linux systems, and it
+was this document that made me realize that Bacula could do the same thing. 
+
+You can find quite a few additional resources, both commercial and free at 
+\elink{Storage Mountain}{\url{http://www.backupcentral.com}}, formerly known as
+Backup Central. 
+
+And finally, the O'Reilly book, "Unix Backup \& Recovery" by W. Curtis
+Preston covers virtually every backup and recovery topic including bare metal
+recovery for a large range of Unix systems. 
diff --git a/docs/manuals/en/main/restore.tex b/docs/manuals/en/main/restore.tex
new file mode 100644 (file)
index 0000000..4f2083c
--- /dev/null
@@ -0,0 +1,1470 @@
+%%
+%%
+\chapter{The Restore Command}
+\label{RestoreChapter}
+\index[general]{Command!Console Restore}
+\index[general]{Console Restore Command}
+
+\section{General}
+\index[general]{General }
+
+Below, we will discuss restoring files with the Console {\bf restore} command,
+which is the recommended way of doing restoring files. It is not possible
+to restore files by automatically starting a job as you do with Backup,
+Verify, ... jobs.  However, in addition to the console restore command,
+there is a standalone program named {\bf bextract}, which also permits
+restoring files.  For more information on this program, please see the
+\ilink{Bacula Utility Programs}{bextract} chapter of this manual. We 
+don't particularly recommend the {\bf bextract} program because it
+lacks many of the features of the normal Bacula restore, such as the 
+ability to restore Win32 files to Unix systems, and the ability to
+restore access control lists (ACL).  As a consequence, we recommend,
+wherever possible to use Bacula itself for restores as described below.
+
+You may also want to look at the {\bf bls} program in the same chapter,
+which allows you to list the contents of your Volumes.  Finally, if you
+have an old Volume that is no longer in the catalog, you can restore the
+catalog entries using the program named {\bf bscan}, documented in the same
+\ilink{Bacula Utility Programs}{bscan} chapter.
+
+In general, to restore a file or a set of files, you must run a {\bf restore}
+job. That is a job with {\bf Type = Restore}. As a consequence, you will need
+a predefined {\bf restore} job in your {\bf bacula-dir.conf} (Director's
+config) file. The exact parameters (Client, FileSet, ...) that you define are
+not important as you can either modify them manually before running the job or
+if you use the {\bf restore} command, explained below, Bacula will  
+automatically set them for you. In fact, you can no longer simply run a restore
+job.  You must use the restore command.                                  
+
+Since Bacula is a network backup program, you must be aware that when you
+restore files, it is up to you to ensure that you or Bacula have selected the
+correct Client and the correct hard disk location for restoring those files.
+{\bf Bacula} will quite willingly backup client A, and restore it by sending
+the files to a different directory on client B. Normally, you will want to
+avoid this, but assuming the operating systems are not too different in their
+file structures, this should work perfectly well, if so desired. 
+By default, Bacula will restore data to the same Client that was backed
+up, and those data will be restored not to the original places but to
+{\bf /tmp/bacula-restores}.  You may modify any of these defaults when the
+restore command prompts you to run the job by selecting the {\bf mod}
+option.
+
+\label{Example1}
+\section{The Restore Command}
+\index[general]{Command!Restore}
+\index[general]{Restore Command}
+
+Since Bacula maintains a catalog of your files and on which Volumes (disk or
+tape), they are stored, it can do most of the bookkeeping work, allowing you
+simply to specify what kind of restore you want (current, before a particular
+date), and what files to restore. Bacula will then do the rest. 
+
+This is accomplished using the {\bf restore} command in the Console. First you
+select the kind of restore you want, then the JobIds are selected,
+the File records for those Jobs are placed in an internal Bacula directory
+tree, and the restore enters a file selection mode that allows you to
+interactively walk up and down the file tree selecting individual files to be
+restored. This mode is somewhat similar to the standard Unix {\bf restore}
+program's interactive file selection mode. 
+
+If a Job's file records have been pruned from the catalog, the {\bf restore}
+command will be unable to find any files to restore. Bacula will ask if you
+want to restore all of them or if you want to use a regular expression to
+restore only a selection while reading media. See \ilink{FileRegex
+  option}{FileRegex} and below for more details on this.
+
+Within the Console program, after entering the {\bf restore} command, you are
+presented with the following selection prompt:  
+
+\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
+
+There are a lot of options, and as a point of reference, most people will
+want to slect item 5 (the most recent backup for a client). The details
+of the above options are:
+
+\begin{itemize}
+\item Item 1 will list the last 20 jobs run. If you find the Job you want,
+   you can then select item 3 and enter its JobId(s).
+
+\item Item 2 will list all the Jobs where a specified file is saved.  If you
+   find the Job you want, you can then select item 3 and enter the JobId.
+
+\item Item 3 allows you the enter a list of comma separated JobIds whose 
+   files will be put into the directory tree. You may then select which
+   files from those JobIds to restore. Normally, you would use this option
+   if you have a particular version of a file that you want to restore and
+   you know its JobId. The most common options (5 and 6) will not select
+   a job that did not terminate normally, so if you know a file is 
+   backed up by a Job that failed (possibly because of a system crash), you
+   can access it through this option by specifying the JobId. 
+
+\item Item 4 allows you to enter any arbitrary SQL command.  This is
+   probably the most primitive way of finding the desired JobIds, but at
+   the same time, the most flexible.  Once you have found the JobId(s), you
+   can select item 3 and enter them.
+
+\item Item 5 will automatically select the most recent Full backup and all
+   subsequent incremental and differential backups for a specified Client.
+   These are the Jobs and Files which, if reloaded, will restore your
+   system to the most current saved state.  It automatically enters the
+   JobIds found into the directory tree in an optimal way such that only
+   the most recent copy of any particular file found in the set of Jobs
+   will be restored.  This is probably the most convenient of all the above
+   options to use if you wish to restore a selected Client to its most
+   recent state.
+
+   There are two important things to note. First, this automatic selection
+   will never select a job that failed (terminated with an error status).
+   If you have such a job and want to recover one or more files from it,
+   you will need to explicitly enter the JobId in item 3, then choose the
+   files to restore.
+
+   If some of the Jobs that are needed to do the restore have had their 
+   File records pruned, the restore will be incomplete. Bacula currently
+   does not correctly detect this condition.  You can however, check for
+   this by looking carefully at the list of Jobs that Bacula selects and
+   prints. If you find Jobs with the JobFiles column set to zero, when
+   files should have been backed up, then you should expect problems.
+
+   If all the File records have been pruned, Bacula will realize that there
+   are no file records in any of the JobIds chosen and will inform you. It
+   will then propose doing a full restore (non-selective) of those JobIds.
+   This is possible because Bacula still knows where the beginning of the
+   Job data is on the Volumes, even if it does not know where particular
+   files are located or what their names are.
+
+\item Item 6 allows you to specify a date and time, after which Bacula  will
+   automatically select the most recent Full backup and all  subsequent
+   incremental and differential backups that started  before the specified date
+   and time.  
+
+\item Item 7 allows you to specify one or more filenames  (complete path
+   required) to be restored. Each filename  is entered one at a time or if you
+   prefix a filename  with the less-than symbol (\lt{}) Bacula will read that 
+   file and assume it is a list of filenames to be restored.  If you
+   prefix the filename with a question mark (?), then the filename will
+   be interpreted as an SQL table name, and Bacula will include the rows
+   of that table in the list to be restored. The table must contain the
+   JobId in the first column and the FileIndex in the second column. 
+   This table feature is intended for external programs that want to build
+   their own list of files to be restored.
+   The filename entry mode is terminated by entering a  blank line.
+
+\item Item 8 allows you to specify a date and time before  entering the
+   filenames. See Item 7 above for more  details.
+
+\item Item 9 allows you find the JobIds of the most recent backup for
+   a client. This is much like option 5 (it uses the same code), but
+   those JobIds are retained internally as if you had entered them
+   manually.  You may then select item 11 (see below) to restore one
+   or more directories.
+
+\item Item 10 is the same as item 9, except that it allows you to enter
+   a before date (as with item 6). These JobIds will then be retained
+   internally.
+
+\index[general]{Restore Directories}
+\item Item 11 allows you to enter a list of JobIds from which you can
+   select directories to be restored. The list of JobIds can have been
+   previously created by using either item 9 or 10 on the menu.  You
+   may then enter a full path to a directory name or a filename preceded
+   by a less than sign (\lt{}). The filename should contain a list
+   of directories to be restored.  All files in those directories will
+   be restored, but if the directory contains subdirectories, nothing
+   will be restored in the subdirectory unless you explicitly enter its
+   name.
+
+\item Item 12 allows you to cancel the restore command.  
+\end{itemize}
+
+As an example, suppose that we select item 5 (restore to most recent state).
+If you have not specified a client=xxx on the command line, it
+it will then ask for the desired Client, which on my system, will print all
+the Clients found in the database as follows:  
+
+\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
+
+You will probably have far fewer Clients than this example, and if you have
+only one Client, it will be automatically selected.  In this case, I enter
+{\bf Rufus} to select the Client. Then  Bacula needs to know what FileSet is
+to be restored, so it prompts with:  
+
+\footnotesize
+\begin{verbatim}
+The defined FileSet resources are:
+     1: Full Set
+     2: Other Files
+Select FileSet resource (1-2):
+\end{verbatim}
+\normalsize
+
+If you have only one FileSet defined for the Client, it will be selected
+automatically.  I choose item 1, which is my full backup.  Normally, you
+will only have a single FileSet for each Job, and if your machines are
+similar (all Linux) you may only have one FileSet for all your Clients.
+
+At this point, {\bf Bacula} has all the information it needs to find the most
+recent set of backups. It will then query the database, which may take a bit
+of time, and it will come up with something like the following. Note, some of
+the columns are truncated here for presentation: 
+
+\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
+
+Depending on the number of {\bf JobFiles} for each JobId, the {\bf Building
+directory tree ..."} can take a bit of time. If you notice ath all the
+JobFiles are zero, your Files have probably been pruned and you will not be
+able to select any individual files -- it will be restore everything or
+nothing.
+
+In our example, Bacula found four Jobs that comprise the most recent backup of
+the specified Client and FileSet. Two of the Jobs have the same JobId because
+that Job wrote on two different Volumes. The third Job was an incremental
+backup to the previous Full backup, and it only saved 254 Files compared to
+128,374 for the Full backup. The fourth Job was also an incremental backup
+that saved 15 files. 
+
+Next Bacula entered those Jobs into the directory tree, with no files marked
+to be restored as a default, tells you how many files are in the tree, and
+tells you that the current working directory ({\bf cwd}) is /. Finally, Bacula
+prompts with the dollar sign (\$) to indicate that you may enter commands to
+move around the directory tree and to select files. 
+             
+If you want all the files to automatically be marked when the directory
+tree is built, you could have entered the command {\bf restore all}, or
+at the \$ prompt, you can simply enter {\bf mark *}.
+
+Instead of choosing item 5 on the first menu (Select the most recent backup
+for a client), if we had chosen item 3 (Enter list of JobIds to select) and we
+had entered the JobIds {\bf 1792,1797,1798} we would have arrived at the same
+point.                 
+
+One point to note, if you are manually entering JobIds, is that you must enter
+them in the order they were run (generally in increasing JobId order). If you
+enter them out of order and the same file was saved in two or more of the
+Jobs, you may end up with an old version of that file (i.e. not the most
+recent). 
+
+Directly entering the JobIds can also permit you to recover data from
+a Job that wrote files to tape but that terminated with an error status.
+
+While in file selection mode, you can enter {\bf help} or a question mark (?)
+to produce a summary of the available commands:  
+
+\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
+
+As a default no files have been selected for restore (unless you
+added {\bf all} to the command line. If you want to restore
+everything, at this point, you should enter {\bf mark *}, and then {\bf done}
+and {\bf Bacula} will write the bootstrap records to a file and request your
+approval to start a restore job. 
+
+If you do not enter the above mentioned {\bf mark *} command, you will start
+with an empty slate. Now you can simply start looking at the tree and {\bf
+mark} particular files or directories you want restored. It is easy to make
+a mistake in specifying a file to mark or unmark, and Bacula's error handling
+is not perfect, so please check your work by using the {\bf ls} or {\bf dir}
+commands to see what files are actually selected. Any selected file has its
+name preceded by an asterisk. 
+
+To check what is marked or not marked, enter the {\bf count} command, which
+displays:  
+
+\footnotesize
+\begin{verbatim}
+128401 total files. 128401 marked to be restored.
+     
+\end{verbatim}
+\normalsize
+
+Each of the above commands will be described in more detail in the next
+section. We continue with the above example, having accepted to restore all
+files as Bacula set by default. On entering the {\bf done} command, Bacula
+prints:  
+
+\footnotesize
+\begin{verbatim}
+Bootstrap records written to /home/kern/bacula/working/restore.bsr
+The job will require the following   
+   Volume(s)                 Storage(s)                SD Device(s)
+===========================================================================
+
+   DLT-19Jul02               Tape                      DLT8000
+   DLT-04Aug02               Tape                      DLT8000
+
+128401 files selected to restore.
+Run Restore job
+JobName:    kernsrestore
+Bootstrap:  /home/kern/bacula/working/restore.bsr
+Where:      /tmp/bacula-restores
+Replace:    always
+FileSet:    Other Files
+Client:     Rufus
+Storage:    Tape
+When:       2006-12-11 18:20:33
+Catalog:    MyCatalog
+Priority:   10
+OK to run? (yes/mod/no):
+    
+\end{verbatim}
+\normalsize
+
+Please examine each of the items very carefully to make sure that they are
+correct.  In particular, look at {\bf Where}, which tells you where in the
+directory structure the files will be restored, and {\bf Client}, which
+tells you which client will receive the files.  Note that by default the
+Client which will receive the files is the Client that was backed up.
+These items will not always be completed with the correct values depending
+on which of the restore options you chose.  You can change any of these
+default items by entering {\bf mod} and responding to the prompts.
+
+The above assumes that you have defined a {\bf Restore} Job resource in your
+Director's configuration file. Normally, you will only need one Restore Job
+resource definition because by its nature, restoring is a manual operation,
+and using the Console interface, you will be able to modify the Restore Job to
+do what you want. 
+
+An example Restore Job resource definition is given below. 
+
+Returning to the above example, you should verify that the Client name is
+correct before running the Job. However, you may want to modify some of the
+parameters of the restore job. For example, in addition to checking the Client
+it is wise to check that the Storage device chosen by Bacula is indeed
+correct. Although the {\bf FileSet} is shown, it will be ignored in restore.
+The restore will choose the files to be restored either by reading the {\bf
+Bootstrap} file, or if not specified, it will restore all files associated
+with the specified backup {\bf JobId} (i.e. the JobId of the Job that
+originally backed up the files). 
+
+Finally before running the job, please note that the default location for
+restoring files is {\bf not} their original locations, but rather the directory
+{\bf /tmp/bacula-restores}. You can change this default by modifying your {\bf
+bacula-dir.conf} file, or you can modify it using the {\bf mod} option. If you
+want to restore the files to their original location, you must have {\bf
+Where} set to nothing or to the root, i.e. {\bf /}. 
+
+If you now enter {\bf yes}, Bacula will run the restore Job. The Storage
+daemon will first request Volume {\bf DLT-19Jul02} and after the appropriate
+files have been restored from that volume, it will request Volume {\bf
+DLT-04Aug02}. 
+
+\subsection{Restore a pruned job using a pattern}
+  During a restore, if all File records are pruned from the catalog
+  for a Job, normally Bacula can restore only all files saved. That
+  is there is no way using the catalog to select individual files.
+  With this new feature, Bacula will ask if you want to specify a Regex
+  expression for extracting only a part of the full backup.
+
+\begin{verbatim}
+  Building directory tree for JobId(s) 1,3 ...
+  There were no files inserted into the tree, so file selection
+  is not possible.Most likely your retention policy pruned the files
+  
+  Do you want to restore all the files? (yes|no): no
+  
+  Regexp matching files to restore? (empty to abort): /tmp/regress/(bin|tests)/
+  Bootstrap records written to /tmp/regress/working/zog4-dir.restore.1.bsr
+\end{verbatim}
+
+  See also \ilink{FileRegex bsr option}{FileRegex} for more information.
+
+\section{Selecting Files by Filename}
+\index[general]{Selecting Files by Filename }
+\index[general]{Filename!Selecting Files by }
+
+If you have a small number of files to restore, and you know the filenames,
+you can either put the list of filenames in a file to be read by Bacula, or
+you can enter the names one at a time. The filenames must include the full
+path and filename. No wild cards are used. 
+
+To enter the files, after the {\bf restore}, you select item number 7 from the
+prompt list: 
+
+\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
+
+which then prompts you for the client name: 
+
+\footnotesize
+\begin{verbatim}
+Defined Clients:
+     1: Timmy
+     2: Tibs
+     3: Rufus
+Select the Client (1-3): 3
+\end{verbatim}
+\normalsize
+
+Of course, your client list will be different, and if you have only one
+client, it will be automatically selected. And finally, Bacula requests you to
+enter a filename: 
+
+\footnotesize
+\begin{verbatim}
+Enter filename:
+\end{verbatim}
+\normalsize
+
+At this point, you can enter the full path and filename 
+
+\footnotesize
+\begin{verbatim}
+Enter filename: /home/kern/bacula/k/Makefile.in
+Enter filename:
+\end{verbatim}
+\normalsize
+
+as you can see, it took the filename. If Bacula cannot find a copy of the
+file, it prints the following: 
+
+\footnotesize
+\begin{verbatim}
+Enter filename: junk filename
+No database record found for: junk filename
+Enter filename:
+\end{verbatim}
+\normalsize
+
+If you want Bacula to read the filenames from a file, you simply precede the
+filename with a less-than symbol (\lt{}). When you have entered all the
+filenames, you enter a blank line, and Bacula will write the bootstrap file,
+tells you what tapes will be used, and proposes a Restore job to be run: 
+
+\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:    Other Files
+Client:     Rufus
+Storage:    DDS-4
+When:       2003-09-11 10:20:53
+Priority:   10
+OK to run? (yes/mod/no):
+\end{verbatim}
+\normalsize
+
+It is possible to automate the selection by file by putting your list of files
+in say {\bf /tmp/file-list}, then using the following command: 
+
+\footnotesize
+\begin{verbatim}
+restore client=Rufus file=</tmp/file-list
+\end{verbatim}
+\normalsize
+
+If in modifying the parameters for the Run Restore job, you find that Bacula
+asks you to enter a Job number, this is because you have not yet specified
+either a Job number or a Bootstrap file. Simply entering zero will allow you
+to continue and to select another option to be modified. 
+
+\label{Replace}
+
+\section{Replace Options}
+
+When restoring, you have the option to specify a Replace option.  This 
+directive determines the action to be taken when restoring a file or 
+directory that already exists.  This directive can be set by selecting 
+the {\bf mod} option.  You will be given a list of parameters to choose
+from.  Full details on this option can be found in the Job Resource section
+of the Director documentation.
+
+\label{CommandArguments}
+
+\section{Command Line Arguments}
+\index[general]{Arguments!Command Line }
+\index[general]{Command Line Arguments }
+
+If all the above sounds complicated, you will probably agree that it really
+isn't after trying it a few times. It is possible to do everything that was
+shown above, with the exception of selecting the FileSet, by using command
+line arguments with a single command by entering: 
+
+\footnotesize
+\begin{verbatim}
+restore client=Rufus select current all done yes
+\end{verbatim}
+\normalsize
+
+The {\bf client=Rufus} specification will automatically select Rufus as the
+client, the {\bf current} tells Bacula that you want to restore the system to
+the most current state possible, and the {\bf yes} suppresses the final {\bf
+yes/mod/no} prompt and simply runs the restore. 
+
+The full list of possible command line arguments are: 
+
+\begin{itemize}
+\item {\bf all} -- select all Files to be restored.  
+\item {\bf select} -- use the tree selection method.  
+\item {\bf done} -- do not prompt the user in tree mode.  
+\item {\bf current} -- automatically select the most current set of  backups
+   for the specified client.  
+\item {\bf client=xxxx} -- initially specifies the client from which the
+   backup was made and the client to which the restore will be make.  See also
+   "restoreclient" keyword.
+\item {\bf restoreclient=xxxx} -- if the keyword is specified, then the
+   restore is written to that client.
+\item {\bf jobid=nnn} -- specify a JobId or comma separated list of  JobIds to
+   be restored.  
+\item {\bf before=YYYY-MM-DD HH:MM:SS} -- specify a date and time to  which
+   the system should be restored. Only Jobs started before  the specified
+   date/time will be selected, and as is the case  for {\bf current} Bacula will
+   automatically find the most  recent prior Full save and all Differential and
+   Incremental  saves run before the date you specify. Note, this command is  not
+   too user friendly in that you must specify the date/time  exactly as shown. 
+\item {\bf file=filename} -- specify a filename to be restored. You  must
+   specify the full path and filename. Prefixing the entry  with a less-than
+   sign
+   (\lt{}) will cause Bacula to assume that the  filename is on your system and
+   contains a list of files to be  restored. Bacula will thus read the list from
+   that file. Multiple  file=xxx specifications may be specified on the command
+   line. 
+\item {\bf jobid=nnn} -- specify a JobId to be restored. 
+\item {\bf pool=pool-name} -- specify a Pool name to be used for selection  of
+   Volumes when specifying options 5 and 6 (restore current system,  and restore
+   current system before given date). This permits you to  have several Pools,
+   possibly one offsite, and to select the Pool to  be used for restoring.  
+\item {\bf where=/tmp/bacula-restore} -- restore files in {\bf where} directory.
+\item {\bf yes} -- automatically run the restore without prompting  for
+   modifications (most useful in batch scripts). 
+\item {\bf strip\_prefix=/prod} -- remove a part of the filename when restoring.
+\item {\bf add\_prefix=/test} -- add a prefix to all files when restoring (like
+  where) (can't be used with {\bf where=}).
+\item {\bf add\_suffix=.old} -- add a suffix to all your files.
+\item {\bf regexwhere=!a.pdf!a.bkp.pdf!} -- do complex filename manipulation
+  like with sed unix command. Will overwrite other filename manipulation.
+\end{itemize}
+
+\label{restorefilerelocation}
+\section{Using File Relocation}
+\index[general]{Using File Relocation}
+\label{filerelocation}
+
+\subsection{Introduction}
+
+The \textbf{where=} option is simple, but not very powerful. With file
+relocation, Bacula can restore a file to the same directory, but with a
+different name, or in an other directory without recreating the full path.
+
+You can also do filename and path manipulations, implemented in Bacula
+2.1.8 or later, such as adding a suffix to all your files, renaming files
+or directories, etc.  Theses options will overwrite {\bf where=} option.
+
+
+For example, many users use OS snapshot features so that file
+\texttt{/home/eric/mbox} will be backed up from the directory
+\texttt{/.snap/home/eric/mbox}, which can complicate restores.  If you use
+\textbf{where=/tmp}, the file will be restored to
+\texttt{/tmp/.snap/home/eric/mbox} and you will have to move the file to
+\texttt{/home/eric/mbox.bkp} by hand.  
+
+However, case, you could use the
+\textbf{strip\_prefix=/.snap} and \textbf{add\_suffix=.bkp} options and
+Bacula will restore the file to its original location -- that is
+\texttt{/home/eric/mbox}.
+
+To use this feature, there are command line options as described in 
+the \ilink{restore section}{restorefilerelocation} of this manual;
+you can modify your restore job before running it; or you can
+add options to your restore job in as described in 
+\ilink{bacula-dir.conf}{confaddprefix}.
+
+\begin{verbatim}
+Parameters to modify:
+     1: Level
+     2: Storage
+    ...
+    10: File Relocation
+    ...
+Select parameter to modify (1-12):
+
+
+This will replace your current Where value
+     1: Strip prefix
+     2: Add prefix
+     3: Add file suffix
+     4: Enter a regexp
+     5: Test filename manipulation
+     6: Use this ?
+Select parameter to modify (1-6):   
+\end{verbatim}
+
+
+\subsection{RegexWhere Format}
+
+The format is very close to that used by sed or Perl (\texttt{s/replace this/by
+  that/}) operator. A valid regexwhere expression has three fields :
+\begin{itemize}
+\item a search expression (with optionnal submatch)
+\item a replacement expression (with optionnal back references \$1 to \$9)
+\item a set of search options (only case-insensitive ``i'' at this time)
+\end{itemize}
+
+Each field is delimited by a separator specified by the user as the first
+character of the expression. The separator can be one of the following:
+\begin{verbatim}
+<separator-keyword> = / ! ; % : , ~ # = &
+\end{verbatim}
+
+You can use several expressions separated by a commas.
+
+\subsection*{Examples}
+
+\begin{tabular}{|c|c|c|l|}
+\hline
+Orignal filename & New filename & RegexWhere & Comments \\
+\hline
+\hline
+\texttt{c:/system.ini} & \texttt{c:/system.old.ini} & \texttt{/.ini\$/.old.ini/} & \$ matches end of name\\
+\hline
+\texttt{/prod/u01/pdata/} & \texttt{/rect/u01/rdata}  & \texttt{/prod/rect/,/pdata/rdata/} & uses two regexp\\
+\hline
+\texttt{/prod/u01/pdata/} & \texttt{/rect/u01/rdata}  & \texttt{!/prod/!/rect/!,/pdata/rdata/} & use \texttt{!} as separator\\
+\hline
+\texttt{C:/WINNT} & \texttt{d:/WINNT}  & \texttt{/c:/d:/i} & case insensitive pattern match \\
+\hline
+
+\end{tabular}
+
+%\subsubsection{Using group}
+%
+%Like with Perl or Sed, you can make submatch with \texttt{()}, 
+%
+%\subsubsection*{Examples}
+
+
+%\subsubsection{Options}
+%
+%       i   Do case-insensitive pattern matching.
+
+\section{Restoring Directory Attributes}
+\index[general]{Attributes!Restoring Directory }
+\index[general]{Restoring Directory Attributes }
+
+Depending how you do the restore, you may or may not get the directory entries
+back to their original state. Here are a few of the problems you can
+encounter, and for same machine restores, how to avoid them. 
+
+\begin{itemize}
+\item You backed up on one machine and are restoring to another that is 
+   either a different OS or doesn't have the same users/groups defined.  Bacula
+   does the best it can in these situations. Note, Bacula has saved the
+   user/groups in numeric form, which means on a different machine, they
+   may map to different user/group names.
+
+\item You are restoring into a directory that is already created and has
+   file creation restrictions.  Bacula tries to reset everything but
+   without walking up the full chain of directories and modifying them all
+   during the restore, which Bacula does and will not do, getting
+   permissions back correctly in this situation depends to a large extent
+   on your OS.
+
+\item You are doing a recursive restore of a directory tree.  In this case
+   Bacula will restore a file before restoring the file's parent directory
+   entry.  In the process of restoring the file Bacula will create the
+   parent directory with open permissions and ownership of the file being
+   restored.  Then when Bacula tries to restore the parent directory Bacula
+   sees that it already exists (Similar to the previous situation).  If you
+   had set the Restore job's "Replace" property to "never" then Bacula will
+   not change the directory's permissions and ownerships to match what it
+   backed up, you should also notice that the actual number of files
+   restored is less then the expected number.  If you had set the Restore
+   job's "Replace" property to "always" then Bacula will change the
+   Directory's ownership and permissions to match what it backed up, also
+   the actual number of files restored should be equal to the expected
+   number.
+
+\item You selected one or more files in a directory, but did not select the
+   directory entry to be restored.  In that case, if the directory is not
+   on disk Bacula simply creates the directory with some default attributes
+   which may not be the same as the original.  If you do not select a
+   directory and all its contents to be restored, you can still select
+   items within the directory to be restored by individually marking those
+   files, but in that case, you should individually use the "markdir"
+   command to select all higher level directory entries (one at a time) to
+   be restored if you want the directory entries properly restored.
+
+\item The {\bf bextract} program does not restore access control lists
+  (ACLs), nor will it restore non-portable Win32 data (default) to Unix
+  machines.
+\end{itemize}
+
+\label{Windows}
+\section{Restoring on Windows}
+\index[general]{Restoring on Windows }
+\index[general]{Windows!Restoring on }
+
+If you are restoring on WinNT/2K/XP systems, Bacula will restore the files
+with the original ownerships and permissions as would be expected.  This is
+also true if you are restoring those files to an alternate directory (using
+the Where option in restore).  However, if the alternate directory does not
+already exist, the Bacula File daemon (Client) will try to create it.  In
+some cases, it may not create the directories, and if it does since the
+File daemon runs under the SYSTEM account, the directory will be created
+with SYSTEM ownership and permissions.  In this case, you may have problems
+accessing the newly restored files.
+
+To avoid this problem, you should create any alternate directory before
+doing the restore.  Bacula will not change the ownership and permissions of
+the directory if it is already created as long as it is not one of the
+directories being restored (i.e.  written to tape).
+
+The default restore location is {\bf /tmp/bacula-restores/} and if you are
+restoring from drive {\bf E:}, the default will be 
+{\bf /tmp/bacula-restores/e/}, so you should ensure that this directory
+exists before doing the restore, or use the {\bf mod} option to
+select a different {\bf where} directory that does exist.
+
+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{Restoring Files Can Be Slow}
+\index[general]{Slow!Restoring Files Can Be }
+\index[general]{Restoring Files Can Be Slow }
+
+Restoring files is generally {\bf much} slower than backing them up for several
+reasons. The first is that during a backup the tape is normally already
+positioned and Bacula only needs to write. On the other hand, because restoring
+files is done so rarely, Bacula keeps only the start file and block on the
+tape for the whole job rather than on a file by file basis which would use
+quite a lot of space in the catalog. 
+
+Bacula will forward space to the correct file mark on the tape for the Job,
+then forward space to the correct block, and finally sequentially read each
+record until it gets to the correct one(s) for the file or files you want to
+restore. Once the desired files are restored, Bacula will stop reading the
+tape. 
+
+Finally, instead of just reading a file for backup, during the restore, Bacula
+must create the file, and the operating system must allocate disk space for
+the file as Bacula is restoring it. 
+
+For all the above reasons the restore process is generally much slower than
+backing up (sometimes it takes three times as long).
+
+\section{Problems Restoring Files}
+\index[general]{Files!Problems Restoring }
+\index[general]{Problems Restoring Files }
+
+The most frequent problems users have restoring files are error messages such
+as: 
+
+\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
+
+or 
+
+\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
+
+Both these kinds of messages indicate that you were probably running your tape
+drive in fixed block mode rather than variable block mode. Fixed block mode
+will work with any program that reads tapes sequentially such as tar, but
+Bacula repositions the tape on a block basis when restoring files because this
+will speed up the restore by orders of magnitude when only a few files are being
+restored. There are several ways that you can attempt to recover from this
+unfortunate situation. 
+
+Try the following things, each separately, and reset your Device resource to
+what it is now after each individual test: 
+
+\begin{enumerate}
+\item Set "Block Positioning = no" in your Device resource  and try the
+   restore. This is a new directive and untested. 
+
+\item Set "Minimum Block Size = 512" and "Maximum  Block Size = 512" and
+   try the restore.  If you are able to determine the block size your drive
+   was previously using, you should try that size if 512 does not work.
+   This is a really horrible solution, and it is not at all recommended
+   to continue backing up your data without correcting this condition.
+   Please see the Tape Testing chapter for more on this.
+
+\item Try editing the restore.bsr file at the Run xxx yes/mod/no prompt 
+   before starting the restore job and remove all the VolBlock statements.
+   These are what causes Bacula to reposition the tape, and where problems
+   occur if you have a fixed block size set for your drive.  The VolFile
+   commands also cause repositioning, but this will work regardless of the
+   block size.
+
+\item Use bextract to extract the files you want -- it reads the  Volume
+   sequentially if you use the include list feature, or if you use a .bsr
+   file, but remove all the VolBlock statements after the .bsr file is
+   created (at the Run yes/mod/no) prompt but before you start the restore.
+\end{enumerate}
+
+\section{Restore Errors}
+\index[general]{Errors!Restore}
+\index[general]{Restore Errors}
+
+There are a number of reasons why there may be restore errors or
+warning messages. Some of the more common ones are:
+
+\begin{description}
+
+\item [file count mismatch]
+  This can occur for the following reasons:
+  \begin{itemize}
+  \item You requested Bacula not to overwrite existing or newer
+     files.
+  \item A Bacula miscount of files/directories. This is an
+     on-going problem due to the complications of directories,
+     soft/hard link, and such.  Simply check that all the files you
+     wanted were actually restored.
+  \end{itemize}
+
+\item [file size error]
+   When Bacula restores files, it checks that the size of the
+   restored file is the same as the file status data it saved 
+   when starting the backup of the file. If the sizes do not
+   agree, Bacula will print an error message. This size mismatch
+   most often occurs because the file was being written as Bacula
+   backed up the file. In this case, the size that Bacula
+   restored will be greater than the status size.  This often
+   happens with log files.
+
+   If the restored size is smaller, then you should be concerned
+   about a possible tape error and check the Bacula output as
+   well as your system logs.
+\end{description}
+
+
+
+\section{Example Restore Job Resource}
+\index[general]{Example Restore Job Resource }
+\index[general]{Resource!Example 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
+
+If {\bf Where} is not specified, the default location for restoring files will
+be their original locations. 
+\label{Selection}
+
+\section{File Selection Commands}
+\index[general]{Commands!File Selection }
+\index[general]{File Selection Commands }
+
+After you have selected the Jobs to be restored and Bacula has created the
+in-memory directory tree, you will enter file selection mode as indicated by
+the dollar sign ({\bf \$}) prompt. While in this mode, you may use the
+commands listed above. The basic idea is to move up and down the in memory
+directory structure with the {\bf cd} command much as you normally do on the
+system. Once you are in a directory, you may select the files that you want
+restored. As a default no files are marked to be restored. If you wish to
+start with all files, simply enter: {\bf cd /} and {\bf mark *}. Otherwise
+proceed to select the files you wish to restore by marking them with the {\bf
+mark} command. The available commands are: 
+
+\begin{description}
+
+\item [cd]
+   The {\bf cd} command changes the current directory to  the argument
+   specified.
+   It operates much like the Unix {\bf cd} command.  Wildcard specifications are
+   not permitted.  
+
+   Note, on Windows systems, the various drives (c:, d:, ...) are treated  like
+   a
+   directory within the file tree while in the file  selection mode. As a
+   consequence, you must do a {\bf cd c:} or  possibly in some cases a {\bf cd
+   C:} (note upper case)  to get down to the first directory.  
+
+\item [dir]
+   \index[dir]{dir }
+   The {\bf dir} command is similar to the {\bf ls} command,  except that it
+   prints it in long format (all details). This command  can be a bit slower
+   than
+   the {\bf ls} command because it must access  the catalog database for the
+   detailed information for each file.  
+
+\item [estimate]
+   \index[dir]{estimate }
+   The {\bf estimate} command prints a summary of  the total files in the tree,
+   how many are marked to be restored, and  an estimate of the number of bytes
+   to
+   be restored. This can be useful  if you are short on disk space on the
+   machine
+   where the files will be  restored.  
+
+\item [find]
+   \index[dir]{find}
+   The {\bf find} command accepts one or more arguments  and displays all files
+   in the tree that match that argument. The argument  may have wildcards. It is
+   somewhat similar to the Unix command  {\bf find / -name arg}.  
+
+\item [ls]
+   The {\bf ls} command produces a listing of all the files  contained in the
+   current directory much like the Unix {\bf ls} command.  You may specify an
+   argument containing wildcards, in which case only  those files will be
+   listed.
+
+   Any file that is marked to be restored will  have its name preceded by an
+   asterisk ({\bf *}). Directory names  will be terminated with a forward slash
+   ({\bf /}) to distinguish them  from filenames.  
+
+\item [lsmark]
+   \index[fd]{lsmark}
+   The {\bf lsmark} command is the same as the  {\bf ls} except that it will
+   print only those files marked for  extraction. The other distinction is that
+   it will recursively  descend into any directory selected. 
+
+\item [mark]
+   \index[dir]{mark}
+   The {\bf mark} command allows you to mark files to be restored. It takes a
+   single argument which is the filename  or directory name in the current
+   directory to be marked for extraction.  The argument may be a wildcard
+   specification, in which  case all files that match in the current directory
+   are marked to be  restored. If the argument matches a directory rather than a
+   file,  then the directory and all the files contained in that directory
+   (recursively)  are marked to be restored. Any marked file will have its name 
+   preceded with an asterisk ({\bf *}) in the output produced by the  {\bf ls}
+or
+   {\bf dir} commands. Note, supplying a full path on  the mark command does not
+   work as expected to select a file or  directory in the current directory.
+   Also, the {\bf mark} command works  on the current and lower directories but
+   does not touch higher level  directories.  
+
+   After executing the {\bf mark} command, it will print a brief summary:  
+
+\footnotesize
+\begin{verbatim}
+    No files marked.
+    
+\end{verbatim}
+\normalsize
+
+   If no files were marked, or:  
+
+\footnotesize
+\begin{verbatim}
+    nn files marked.
+    
+\end{verbatim}
+\normalsize
+
+   if some files are marked.  
+
+\item [unmark]
+   \index[dir]{unmark }
+   The {\bf unmark} is identical to the {\bf mark}  command, except that it
+   unmarks the specified file or files so that  they will not be restored. Note:
+   the {\bf unmark} command works from  the current directory, so it does not
+   unmark any files at a higher  level. First do a {\bf cd /} before the {\bf
+   unmark *} command if  you want to unmark everything.  
+
+\item [pwd]
+   \index[dir]{pwd }
+   The {\bf pwd} command prints the current working  directory. It accepts no
+   arguments.  
+
+\item [count]
+   \index[dir]{count }
+   The {\bf count} command prints the total files in the  directory tree and the
+   number of files marked to be restored.  
+
+\item [done]
+   \index[dir]{done }
+   This command terminates file selection mode.  
+
+\item [exit]
+   \index[fd]{exit }
+   This command terminates file selection mode (the same as  done).  
+
+\item [quit]
+   \index[fd]{quit }
+   This command terminates the file selection and does  not run the restore
+job. 
+
+
+\item [help]
+   \index[fd]{help }
+   This command prints a summary of the commands available.  
+
+\item [?]
+   This command is the same as the {\bf help} command.  
+\end{description}
+
+\label{database_restore}
+\section{Restoring When Things Go Wrong}
+\index[general]{Restoring When Things Go Wrong }
+\index[general]{Restoring Your Database}
+\index[general]{Database!Restoring}
+
+This and the following sections will try to present a few of the kinds of
+problems that can come up making restoring more difficult. We will try to
+provide a few ideas how to get out of these problem situations.
+In addition to what is presented here, there is more specific information
+on restoring a \ilink{Client}{restore_client} and your
+\ilink{Server}{restore_server} in the \ilink{Disaster Recovery Using
+Bacula}{RescueChapter} chapter of this manual.
+
+\begin{description}
+\item[Problem]
+   My database is broken.
+\item[Solution]
+   For SQLite, use the vacuum command to try to fix the database. For either
+   MySQL or PostgreSQL, see the vendor's documentation. They have specific tools
+   that check and repair databases, see the \ilink{database
+   repair}{DatabaseRepair} sections of this manual for links to vendor    
+   information.
+
+   Assuming the above does not resolve the problem, you will need to restore
+   or rebuild your catalog.  Note, if it is a matter of some
+   inconsistencies in the Bacula tables rather than a broken database, then
+   running \ilink{dbcheck}{dbcheck} might help, but you will need to ensure
+   that your database indexes are properly setup.  Please see
+   the \ilink{Database Performance Issues}{DatabasePerformance} sections
+   of this manual for more details.
+
+\item[Problem]
+   How do I restore my catalog?
+\item[Solution with a Catalog backup]
+   If you have backed up your database nightly (as you should) and you
+   have made a bootstrap file, you can immediately load back your
+   database (or the ASCII SQL output).  Make a copy of your current
+   database, then re-initialize it, by running the following scripts:
+\begin{verbatim}
+   ./drop_bacula_tables
+   ./make_bacula_tables
+\end{verbatim}
+   After re-initializing the database, you should be able to run 
+   Bacula. If you now try to use the restore command, it will not 
+   work because the database will be empty. However, you can manually
+   run a restore job and specify your bootstrap file. You do so
+   by entering the {bf run} command in the console and selecting the
+   restore job.  If you are using the default bacula-dir.conf, this
+   Job will be named {\bf RestoreFiles}. Most likely it will prompt
+   you with something such as:
+
+\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
+
+   A number of the items will be different in your case.  What you want to
+   do is: to use the mod option to change the Bootstrap to point to your
+   saved bootstrap file; and to make sure all the other items such as
+   Client, Storage, Catalog, and Where are correct.  The FileSet is not
+   used when you specify a bootstrap file.  Once you have set all the
+   correct values, run the Job and it will restore the backup of your
+   database, which is most likely an ASCII dump. 
+
+   You will then need to follow the instructions for your
+   database type to recreate the database from the ASCII backup file.
+   See the \ilink {Catalog Maintenance}{CatMaintenanceChapter} chapter of
+   this manual for examples of the command needed to restore a 
+   database from an ASCII dump (they are shown in the Compacting Your
+   XXX Database sections).
+    
+   Also, please note that after you restore your database from an ASCII
+   backup, you do NOT want to do a {\bf make\_bacula\_tables}  command, or
+   you will probably erase your newly restored database tables.
+
+      
+\item[Solution with a Job listing]
+   If you did save your database but did not make a bootstrap file, then
+   recovering the database is more difficult.  You will probably need to
+   use bextract to extract the backup copy.  First you should locate the
+   listing of the job report from the last catalog backup.  It has
+   important information that will allow you to quickly find your database
+   file.  For example, in the job report for the CatalogBackup shown below,
+   the critical items are the Volume name(s), the Volume Session Id and the
+   Volume Session Time.  If you know those, you can easily restore your
+   Catalog.
+
+\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
+
+  From the above information, you can manually create a bootstrap file,
+  and then follow the instructions given above for restoring your database.
+  A reconstructed bootstrap file for the above backup Job would look
+  like the following:
+
+\footnotesize
+\begin{verbatim}
+Volume="DLT-22Apr05"
+VolSessionId=11
+VolSessionTime=1114075126
+FileIndex=1-1
+\end{verbatim}
+\normalsize    
+
+  Where we have inserted the Volume name, Volume Session Id, and Volume
+  Session Time that correspond to the values in the job report.  We've also
+  used a FileIndex of one, which will always be the case providing that
+  there was only one file backed up in the job.
+  
+  The disadvantage of this bootstrap file compared to what is created when
+  you ask for one to be written, is that there is no File and Block
+  specified, so the restore code must search all data in the Volume to find
+  the requested file.  A fully specified bootstrap file would have the File
+  and Blocks specified as follows:
+
+\footnotesize
+\begin{verbatim}
+Volume="DLT-22Apr05"
+VolSessionId=11
+VolSessionTime=1114075126
+VolFile=118-118
+VolBlock=0-4053
+FileIndex=1-1
+\end{verbatim}
+\normalsize
+
+   Once you have restored the ASCII dump of the database,
+   you will then to follow the instructions for your
+   database type to recreate the database from the ASCII backup file.
+   See the \ilink {Catalog Maintenance}{CatMaintenanceChapter} chapter of
+   this manual for examples of the command needed to restore a 
+   database from an ASCII dump (they are shown in the Compacting Your
+   XXX Database sections).
+    
+   Also, please note that after you restore your database from an ASCII
+   backup, you do NOT want to do a {\bf make\_bacula\_tables}  command, or
+   you will probably erase your newly restored database tables.
+
+\item [Solution without a Job Listing]
+   If you do not have a job listing, then it is a bit more difficult.
+   Either you use the \ilink{bscan}{bscan} program to scan the contents
+   of your tape into a database, which can be very time consuming 
+   depending on the size of the tape, or you can use the \ilink{bls}{bls}
+   program to list everything on the tape, and reconstruct a bootstrap 
+   file from the bls listing for the file or files you want following
+   the instructions given above.
+
+   There is a specific example of how to use {\bf bls} below.
+
+\item [Problem]
+   I try to restore the last known good full backup by specifying
+   item 3 on the restore menu then the JobId to restore.  Bacula 
+   then reports:
+
+\footnotesize
+\begin{verbatim}
+   1 Job 0 Files
+\end{verbatim}
+\normalsize
+   and restores nothing.
+
+\item[Solution]
+   Most likely the File records were pruned from the database either due
+   to the File Retention period expiring or by explicitly purging the
+   Job. By using the "llist jobid=nn" command, you can obtain all the
+   important information about the 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
+
+   Then you can find the Volume(s) used by doing:
+
+\footnotesize
+\begin{verbatim}
+sql
+select VolumeName from JobMedia,Media where JobId=1 and JobMedia.MediaId=Media.MediaId;
+\end{verbatim}
+\normalsize
+
+   Finally, you can create a bootstrap file as described in the previous
+   problem above using this information.
+
+   If you are using Bacula version 1.38.0 or greater, when you select
+   item 3 from the menu and enter the JobId, it will ask you if
+   you would like to restore all the files in the job, and it will
+   collect the above information and write the bootstrap file for
+   you.
+
+\item [Problem]
+  You don't have a bootstrap file, and you don't have the Job report for
+  the backup of your database, but you did backup the database, and you
+  know the Volume to which it was backed up.
+  
+\item [Solution]
+  Either bscan the tape (see below for bscanning), or better use {\bf bls}
+  to find where it is on the tape, then use {\bf bextract} to 
+  restore the database.  For example,
+
+
+\footnotesize
+\begin{verbatim}
+./bls -j -V DLT-22Apr05 /dev/nst0
+\end{verbatim}
+\normalsize
+  Might produce the following output:
+\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
+  Of course, there will be many more records printed, but we have indicated
+  the essential lines of output. From the information on the Begin Job and End 
+  Job Session Records, you can reconstruct a bootstrap file such as the one
+  shown above.
+
+\item[Problem]
+  How can I find where a file is stored.
+\item[Solution]
+  Normally, it is not necessary, you just use the {\bf restore} command to
+  restore the most recently saved version (menu option 5), or a version
+  saved before a given date (menu option 8).  If you know the JobId of the
+  job in which it was saved, you can use menu option 3 to enter that JobId.
+
+  If you would like to know the JobId where a file was saved, select
+  restore menu option 2.
+
+  You can also use the {\bf query} command to find information such as: 
+\footnotesize
+\begin{verbatim}
+*query
+Available queries:
+     1: List up to 20 places where a File is saved regardless of the
+directory
+     2: List where the most recent copies of a file are saved
+     3: List last 20 Full Backups for a Client
+     4: List all backups for a Client after a specified time
+     5: List all backups for a Client
+     6: List Volume Attributes for a selected Volume
+     7: List Volumes used by selected JobId
+     8: List Volumes to Restore All Files
+     9: List Pool Attributes for a selected Pool
+    10: List total files/bytes by Job
+    11: List total files/bytes by Volume
+    12: List Files for a selected JobId
+    13: List Jobs stored on a selected MediaId
+    14: List Jobs stored for a given Volume name
+    15: List Volumes Bacula thinks are in changer
+    16: List Volumes likely to need replacement from age or errors
+Choose a query (1-16):
+\end{verbatim}
+\normalsize
+
+\item[Problem]
+  I didn't backup my database. What do I do now?
+\item[Solution]
+  This is probably the worst of all cases, and you will probably have
+  to re-create your database from scratch and then bscan in all your
+  Volumes, which is a very long, painful, and inexact process.
+
+There are basically three steps to take:
+
+\begin{enumerate}
+\item Ensure that your SQL server is running (MySQL or PostgreSQL)
+   and that the Bacula database (normally bacula) exists.  See the
+   \ilink{Installation}{CreateDatabase} chapter of the manual.
+\item Ensure that the Bacula databases are created. This is also
+   described at the above link.
+\item Start and stop the Bacula Director using the propriate
+   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.
+\end{enumerate}
+
+When the above is complete, you can begin bscanning your Volumes. Please
+see the \ilink{bscan}{bscan} section of the Volume Utility Tools of this
+chapter for more details.
+
+\end{description}
diff --git a/docs/manuals/en/main/security.tex b/docs/manuals/en/main/security.tex
new file mode 100644 (file)
index 0000000..7866410
--- /dev/null
@@ -0,0 +1,332 @@
+%%
+%%
+
+\chapter{Bacula Security Issues}
+\label{SecurityChapter}
+\index[general]{Bacula Security Issues}
+\index[general]{Security}
+\index[general]{Issues!Bacula Security}
+
+\begin{itemize}
+\item Security means being able to restore your files, so read the 
+   \ilink{Critical Items Chapter}{Critical} of this manual.
+\item The Clients ({\bf bacula-fd}) must run as root to be able to access  all
+   the system files. 
+\item It is not necessary to run the Director as root. 
+\item It is not necessary to run the Storage daemon as root, but you  must
+   ensure that it can open the tape drives, which are often restricted to root
+   access by default. In addition, if you do not run the Storage daemon as root,
+   it will not be able to automatically set your tape drive parameters on most
+   OSes since these functions, unfortunately require root access.
+\item You should restrict access to the Bacula configuration files,  so that
+   the passwords are not world-readable. The {\bf Bacula}  daemons are password
+   protected using CRAM-MD5 (i.e. the password is not  sent across the network).
+   This will ensure that not everyone  can access the daemons. It is a reasonably
+   good protection, but  can be cracked by experts. 
+\item If you are using the recommended ports 9101, 9102, and 9103, you  will
+   probably want to protect these ports from external access  using a firewall
+   and/or using tcp wrappers ({\bf etc/hosts.allow}).  
+\item By default, all data that is sent across the network is unencrypted.
+   However, Bacula does support TLS (transport layer security) and can
+   encrypt transmitted data.  Please read the
+   \ilink{TLS (SSL) Communications Encryption}{CommEncryption}
+   section of this manual.
+\item You should ensure that the Bacula working directories are  readable and
+   writable only by the Bacula daemons. 
+\item If you are using {\bf MySQL} it is not necessary for it to  run with
+   {\bf root} permission. 
+\item The default Bacula {\bf grant-mysql-permissions} script  grants all
+   permissions to use the MySQL database without a  password. If you want
+   security, please tighten this up! 
+\item Don't forget that Bacula is a network program, so anyone anywhere  on
+   the network with the console program and the Director's password  can access
+   Bacula and the backed up data. 
+\item You can restrict what IP addresses Bacula will bind to by using the 
+   appropriate {\bf DirAddress}, {\bf FDAddress}, or {\bf SDAddress}  records in
+   the respective daemon configuration files. 
+\item Be aware that if you are backing up your database using the default
+   script, if you have a password on your database, it will be passed as
+   a command line option to that script, and any user will be able to see
+   this information. If you want it to be secure, you will need to pass it
+   by an environment variable or a secure file.
+
+   See also \ilink{Backing Up Your Bacula
+   Database - Security Considerations }{BackingUpBaculaSecurityConsiderations}
+   for more information.
+\end{itemize}
+
+
+\section{Backward Compatibility}
+\index[general]{Backward Compatibility}
+One of the major goals of Bacula is to ensure that you can restore
+tapes (I'll use the word tape to include disk Volumes) that you wrote years
+ago.  This means that each new version of Bacula should be able to read old
+format tapes. The first problem you will have is to ensure that the 
+hardware is still working some years down the road, and the second
+problem will be to ensure that the media will still be good, then 
+your OS must be able to interface to the device, and finally Bacula
+must be able to recognize old formats.  All the problems except the
+last are ones that we cannot solve, but by careful planning you can.
+
+Since the very beginning of Bacula (January 2000) until today (December
+2005), there have been two major Bacula tape formats.  The second format
+was introduced in version 1.27 in November of 2002, and it has not
+changed since then.  In principle, Bacula can still read the original
+format, but I haven't tried it lately so who knows ...
+
+Though the tape format is fixed, the kinds of data that we can put on the
+tapes are extensible, and that is how we added new features
+such as ACLs, Win32 data, encrypted data, ...  Obviously, an older
+version of Bacula would not know how to read these newer data streams,
+but each newer version of Bacula should know how to read all the 
+older streams.
+
+If you want to be 100% sure that you can read old tapes, you
+should:
+
+1. Try reading old tapes from time to time -- e.g. at least once
+a year.
+
+2. Keep statically linked copies of every version of Bacula that you use
+in production then if for some reason, we botch up old tape compatibility, you
+can always pull out an old copy of Bacula ...
+
+The second point is probably overkill but if you want to be sure, it may
+save you someday.
+
+
+
+\label{wrappers}
+\section{Configuring and Testing TCP Wrappers}
+\index[general]{Configuring and Testing TCP Wrappers}
+\index[general]{TCP Wrappers}
+\index[general]{Wrappers!TCP}
+\index[general]{libwrappers}
+
+TCP Wrappers are implemented if you turn them on when configuring
+({\bf ./configure \verb:--:with-tcp-wrappers}). 
+With this code enabled, you may control who may access your
+daemons.  This control is done by modifying the file: {\bf
+/etc/hosts.allow}.  The program name that {\bf Bacula} uses when
+applying these access restrictions is the name you specify in the
+daemon configuration file (see below for examples).
+You must not use the {\bf twist} option in your {\bf
+/etc/hosts.allow} or it will terminate the Bacula daemon when a
+connection is refused.
+
+The exact name of the package you need loaded to build with TCP wrappers
+depends on the system.  For example,
+on SuSE, the TCP wrappers libraries needed to link Bacula are
+contained in the tcpd-devel package. On Red Hat, the package is named
+tcp\_wrappers.
+
+Dan Langille has provided the following information on configuring and
+testing TCP wrappers with Bacula. 
+
+If you read hosts\_options(5), you will see an option called twist. This
+option replaces the current process by an instance of the specified shell
+command. Typically, something like this is used: 
+
+\footnotesize
+\begin{verbatim}
+ALL : ALL \
+ : severity auth.info \
+ : twist /bin/echo "You are not welcome to use %d from %h."
+\end{verbatim}
+\normalsize
+
+The libwrap code tries to avoid {\bf twist} if it runs in a resident process,
+but that test will not protect the first hosts\_access() call. This will
+result in the process (e.g. bacula-fd, bacula-sd, bacula-dir) being terminated
+if the first connection to their port results in the twist option being
+invoked. The potential, and I stress potential, exists for an attacker to
+prevent the daemons from running. This situation is eliminated if your
+/etc/hosts.allow file contains an appropriate rule set. The following example
+is sufficient: 
+
+\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
+
+You must adjust the names to be the same as the Name directives found
+in each of the daemon configuration files. They are, in general, not the
+same as the binary daemon names. It is not possible to use the 
+daemon names because multiple daemons may be running on the same machine
+but with different configurations.
+
+In these examples, the Director is undef-dir, the
+Storage Daemon is undef-sd, and the File Daemon is undef-fd. Adjust to suit
+your situation. The above example rules assume that the SD, FD, and DIR all
+reside on the same box. If you have a remote FD client, then the following
+rule set on the remote client will suffice: 
+
+\footnotesize
+\begin{verbatim}
+undef-fd : director.example.org : allow
+undef-fd : ALL : deny
+\end{verbatim}
+\normalsize
+
+where director.example.org is the host which will be contacting the client
+(ie. the box on which the Bacula Director daemon runs). The use of "ALL :
+deny" ensures that the twist option (if present) is not invoked. To properly
+test your configuration, start the daemon(s), then attempt to connect from an
+IP address which should be able to connect. You should see something like
+this: 
+
+\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
+
+This is the correct response. If you see this: 
+
+\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
+
+then twist has been invoked and your configuration is not correct and you need
+to add the deny statement. It is important to note that your testing must
+include restarting the daemons after each connection attempt. You can also
+tcpdchk(8) and tcpdmatch(8) to validate your /etc/hosts.allow rules. Here is a
+simple test using 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
+
+If you are running Bacula as a standalone daemon, the warning above can be
+safely ignored. Here is an example which indicates that your rules are missing
+a deny statement and the twist option has been invoked. 
+
+\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{Running as non-root}
+\index[general]{Running as non-root }
+
+Security advice from Dan Langille: 
+% TODO: don't use specific name
+
+% TODO: don't be too specific on operating system
+
+% TODO: maybe remove personalization?
+
+It is a good idea to run daemons with the lowest possible privileges.  In
+other words, if you can, don't run applications as root which do  not have to
+be root.  The Storage Daemon and the Director Daemon do not need to be root.
+The  File Daemon needs to be root in order to access all files on your system.
+In order to run as non-root, you need to create a user and a group.  Choosing
+{\tt bacula} as both the user name and the group name sounds like a good idea
+to me.  
+
+The FreeBSD port creates this user and group for you.
+Here is what those entries looked like on my FreeBSD laptop: 
+
+\footnotesize
+\begin{verbatim}
+bacula:*:1002:1002::0:0:Bacula Daemon:/var/db/bacula:/sbin/nologin
+\end{verbatim}
+\normalsize
+
+I used vipw to create this entry. I selected a User ID and Group ID  of 1002
+as they were unused on my system.  
+
+I also created a group in /etc/group:  
+
+\footnotesize
+\begin{verbatim}
+bacula:*:1002:
+\end{verbatim}
+\normalsize
+
+The bacula user (as opposed to the Bacula daemon) will have a home  directory
+of {\tt /var/db/bacula} which is the  default location for the Bacula
+database.  
+
+Now that you have both a bacula user and a bacula group, you can  secure the
+bacula home directory by issuing this command: 
+
+\footnotesize
+\begin{verbatim}
+chown -R bacula:bacula /var/db/bacula/
+\end{verbatim}
+\normalsize
+
+This ensures that only the bacula user can access this directory.  It also
+means that if we run the Director and the Storage daemon  as bacula, those
+daemons also have restricted access. This would not be  the case if they were
+running as root.  
+
+It is important to note that the storage daemon actually needs  to be in the
+operator group for normal access to tape drives etc (at  least on a FreeBSD
+system, that's how things are set up by default)  Such devices are normally
+chown root:operator. It is easier and less  error prone  to make Bacula a
+member of that group than it is to play around  with system permissions. 
+
+Starting the Bacula daemons 
+
+To start the bacula daemons on a FreeBSD system, issue the following command: 
+
+\footnotesize
+\begin{verbatim}
+/usr/local/etc/rc.d/bacula-dir start
+/usr/local/etc/rc.d/bacula-sd  start
+/usr/local/etc/rc.d/bacula-fd  start
+\end{verbatim}
+\normalsize
+
+To confirm they are all running: 
+
+\footnotesize
+\begin{verbatim}
+$ ps auwx | grep bacula
+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
+bacula 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
+bacula 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
diff --git a/docs/manuals/en/main/spooling.tex b/docs/manuals/en/main/spooling.tex
new file mode 100644 (file)
index 0000000..b7d883a
--- /dev/null
@@ -0,0 +1,150 @@
+%%
+%%
+
+\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\vb{}no} 
+
+\item To override the Job specification in a Schedule Run  directive in the
+   Director's conf file.
+
+{\bf SpoolData = yes\vb{}no} 
+
+\item To override the Job specification in a bconsole session using the \texttt{run}
+   command. Please note that this does {\bf not } refer to a configuration
+   statement, but to an argument for the run command.
+
+{\bf SpoolData=yes\vb{}no} 
+
+\item To limit the the maximum spool file size for a particular job in the Job
+  resource
+
+{\bf Spool Size = size}
+   Where size is a the maximum spool size for this job  specified in bytes. 
+
+\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}
diff --git a/docs/manuals/en/main/sqlite.tex b/docs/manuals/en/main/sqlite.tex
new file mode 100644 (file)
index 0000000..a5ef879
--- /dev/null
@@ -0,0 +1,168 @@
+%%
+%%
+
+\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. 
diff --git a/docs/manuals/en/main/state.tex b/docs/manuals/en/main/state.tex
new file mode 100644 (file)
index 0000000..4d954b8
--- /dev/null
@@ -0,0 +1,246 @@
+%%
+%%
+
+\chapter{The Current State of Bacula}
+\label{StateChapter}
+\index[general]{Current State of Bacula }
+
+In other words, what is and what is not currently implemented and functional. 
+
+\section{What is Implemented}
+\index[general]{Implemented!What}
+\index[general]{What is Implemented}
+
+\begin{itemize}
+\item Job Control
+   \begin{itemize}
+   \item Network backup/restore with centralized Director.  
+   \item Internal scheduler for automatic 
+      \ilink{Job}{JobDef} execution.  
+   \item Scheduling of multiple Jobs at the same time.  
+   \item You may run one Job at a time or multiple simultaneous Jobs
+         (sometimes called multiplexing).
+   \item Job sequencing using priorities.  
+   \item \ilink{Console}{UADef} interface to the Director allowing complete
+      control.  A shell, Qt4 GUI, GNOME GUI and wxWidgets GUI versions of
+      the Console program are available.  Note, the Qt4 GUI program called
+      the Bacula Administration tool or bat, offers many additional
+      features over the shell program.
+   \end{itemize}
+
+\item Security
+   \begin{itemize}
+   \item Verification of files previously cataloged, permitting a Tripwire like 
+      capability (system break-in detection).  
+   \item CRAM-MD5 password authentication between each component (daemon).
+   \item Configurable 
+      \ilink{TLS (SSL) communications encryption}{CommEncryption} between each 
+            component.
+   \item Configurable
+   \ilink{Data (on Volume) encryption}{DataEncryption}
+      on a Client by Client basis.
+   \item Computation of MD5 or SHA1 signatures of the file data if requested.  
+   \end{itemize}
+
+
+\item Restore Features
+   \begin{itemize}
+   \item Restore of one or more files selected interactively either for the
+      current backup or a backup prior to a specified time and date.  
+   \item Restore of a complete system starting from bare  metal. This is mostly
+      automated for Linux systems and  partially automated for Solaris. See 
+      \ilink{Disaster Recovery Using Bacula}{RescueChapter}. This is also
+      reported to work on Win2K/XP systems.  
+   \item Listing and Restoration of files using stand-alone {\bf bls} and  {\bf
+      bextract} tool programs. Among other things, this permits  extraction of files
+      when Bacula and/or the catalog are not  available. Note, the recommended way
+      to restore files is using  the restore command in the Console. These programs
+      are designed  for use as a last resort. 
+   \item Ability to restore the catalog database rapidly by using bootstrap
+      files (previously saved).
+   \item Ability to recreate the catalog database by scanning backup Volumes 
+      using the {\bf bscan} program.  
+   \end{itemize}
+
+\item SQL Catalog
+   \begin{itemize}
+   \item Catalog database facility for remembering Volumes, Pools, Jobs,  and
+      Files backed up.  
+   \item Support for MySQL, PostgreSQL, and SQLite Catalog databases.  
+   \item User extensible queries to the MySQL, PostgreSQL and SQLite databases.  
+   \end{itemize}
+
+\item Advanced Volume and Pool Management
+   \begin{itemize}
+   \item Labeled Volumes, preventing accidental overwriting  (at least by
+      Bacula).  
+   \item Any number of Jobs and Clients can be backed up to a single  Volume.
+      That is, you can backup and restore Linux, Unix, Sun, and  Windows machines to
+      the same Volume.  
+   \item Multi-volume saves. When a Volume is full, {\bf Bacula}  automatically
+      requests the next Volume and continues the backup.  
+   \item 
+      \ilink{Pool and Volume}{PoolResource} library management 
+      providing Volume flexibility (e.g. monthly, weekly, daily Volume sets,  Volume
+      sets segregated by Client, ...). 
+   \item Machine independent Volume data format. Linux, Solaris, and Windows 
+      clients can all be backed up to the same Volume if desired. 
+   \item The Volume data format is upwards compatible so that old Volumes
+      can always be read.
+   \item A flexible 
+      \ilink{message}{MessagesChapter}  handler including routing
+      of messages from any daemon back to the  Director and automatic email
+      reporting.  
+   \item Data spooling to disk during backup with subsequent write to tape from
+      the spooled disk files. This prevents tape "shoe shine"  during
+      Incremental/Differential backups.  
+   \end{itemize}
+
+\item Advanced Support for most Storage Devices
+    \begin{itemize}
+   \item Autochanger support using a simple shell interface that can interface 
+      to virtually any autoloader program. A script for {\bf mtx} is  provided.  
+   \item Support for autochanger barcodes -- automatic tape labeling from 
+      barcodes.  
+   \item Automatic support for multiple autochanger magazines either using
+      barcodes or by reading the tapes.  
+   \item Support for multiple drive autochangers.
+   \item Raw device backup/restore. Restore must be to the same device. 
+   \item All Volume blocks (approximately 64K bytes) contain a data checksum.  
+   \item Migration support -- move data from one Pool to another or
+         one Volume to another.
+   \item Supports writing to DVD.
+   \end{itemize}
+
+\item Multi-Operating System Support
+   \begin{itemize} 
+   \item Programmed to handle arbitrarily long filenames and messages.  
+   \item GZIP compression on a file by file basis done by the Client program  if
+      requested before network transit.  
+   \item Saves and restores POSIX ACLs on most OSes if enabled.  
+   \item Access control lists for Consoles that permit restricting user access
+      to only their data.  
+   \item Support for save/restore of files larger than 2GB.  
+   \item Support for 64 bit machines, e.g. amd64, Sparc.
+   \item Support ANSI and IBM tape labels.
+   \item Support for Unicode filenames (e.g. Chinese) on Win32 machines on
+         version 1.37.28 and greater.
+   \item Consistent backup of open files on Win32 systems (WinXP, Win2003, 
+         and Vista)
+         but not Win2000, using Volume Shadow Copy (VSS).
+   \item Support for path/filename lengths of up to 64K on Win32 machines
+         (unlimited on Unix/Linux machines).
+   \end{itemize}
+
+\item Miscellaneous
+   \begin{itemize}
+   \item Multi-threaded implementation.  
+   \item A comprehensive and extensible 
+      \ilink{configuration file}{DirectorChapter} for each daemon.  
+   \end{itemize}
+\end{itemize}
+
+\section{Advantages Over Other Backup Programs}
+\index[general]{Advantages of Bacula Over Other Backup Programs }
+\index[general]{Programs!Advantages of Bacula Over Other Backup }
+
+\begin{itemize}
+\item Since there is a client for each machine, you can backup
+   and restore clients of any type ensuring that all attributes
+   of files are properly saved and restored.
+\item It is also possible to backup clients without any client
+   software by using NFS or Samba.  However, if possible, we
+   recommend running a Client File daemon on each machine to be
+   backed up.
+\item Bacula handles multi-volume backups.  
+\item A full comprehensive SQL standard database of all files backed up.  This
+   permits online viewing of files saved on any particular  Volume.  
+\item Automatic pruning of the database (removal of old records) thus 
+   simplifying database administration.  
+\item Any SQL database engine can be used making Bacula very flexible.  
+      Drivers currently exist for MySQL, PostgreSQL, and SQLite.
+\item The modular but integrated design makes Bacula very scalable.  
+\item Since Bacula uses client file servers, any database or
+   other application can be properly shutdown by Bacula using the
+   native tools of the system, backed up, then restarted (all
+   within a Bacula Job).
+\item Bacula has a built-in Job scheduler.  
+\item The Volume format is documented and there are simple C programs to 
+   read/write it.  
+\item Bacula uses well defined (IANA registered) TCP/IP ports -- no rpcs,  no
+   shared memory.  
+\item Bacula installation and configuration is relatively simple compared  to
+   other comparable products.  
+\item According to one user Bacula is as fast as the big major commercial 
+   applications.  
+\item According to another user Bacula is four times as fast as another
+   commercial application, probably because that application  stores its catalog
+   information in a large number of individual  files rather than an SQL database
+   as Bacula does.  
+\item Aside from several GUI administrative interfaces, Bacula has a
+   comprehensive shell administrative interface, which allows the
+   administrator to use tools such as ssh to administrate any part of
+   Bacula from anywhere (even from home).
+\item Bacula has a Rescue CD for Linux systems with the following features:  
+   \begin{itemize}
+   \item You build it on your own system from scratch with one simple  command:
+      make -- well, then make burn. 
+   \item It uses your kernel  
+   \item It captures your current disk parameters and builds scripts that  allow
+      you to automatically repartition a disk and format it to  put it back to what
+      you had before. 
+   \item It has a script that will restart your networking (with the right  IP
+      address)  
+   \item It has a script to automatically mount your hard disks.  
+   \item It has a full Bacula FD statically linked  
+   \item You can easily add additional data/programs, ... to the disk.  
+   \end{itemize}
+
+\end{itemize}
+
+\section{Current Implementation Restrictions}
+\index[general]{Current Implementation Restrictions }
+\index[general]{Restrictions!Current Implementation }
+
+\begin{itemize}
+\item Bacula's Differential and Incremental \textsl{normal} backups are based
+  on time stamps.  Consequently, if you move files into an existing directory
+  or move a whole directory into the backup fileset after a Full backup, those
+  files will probably not be backed up by an Incremental save because they will
+  have old dates.  You must run backups in Accurate mode or explicitly update
+  the date/time stamp on all moved files. % TODO: remove it ?
+\item File System Modules (configurable routines for
+   saving/restoring special files) are not yet implemented.  However,
+   this feature is easily implemented using RunScripts.
+\item Bacula cannot restore two different jobs in the same
+   restore if those jobs were run simultaneously, unless you had
+   data spooling turned on and the spool file held the full
+   contents of both jobs. In other terms, Bacula cannot restore
+   two jobs in the same restore if the jobs' data blocks were
+   intermixed on the backup medium. This poses no restrictions
+   for normal backup jobs even if they are run simultaneously.
+\item Bacula can generally restore any backup made from a client
+   to any other client. However, if the architecture is significantly
+   different (i.e. 32 bit architecture to 64 bit or Win32 to Unix),
+   some restrictions may apply (e.g. Solaris door files do not exist
+   on other Unix/Linux machines; there are reports that Zlib compression
+   written with 64 bit machines does not always read correctly on a 32 bit
+   machine).
+\item In older version of Bacula ($<=$ 3.x), if you have over 4 billion file
+  entries stored in your database, the database FileId is likely to overflow.
+\item In non \textsl{Accurate} mode, files deleted after a Full save will be
+  included in a restoration. This is typical for most similar backup programs.
+\end{itemize}
+
+\section{Design Limitations or Restrictions}
+\index[general]{Restrictions!Design Limitations or }
+\index[general]{Design Limitations or Restrictions }
+
+\begin{itemize}
+\item Names (resource names, Volume names, and such) defined in Bacula 
+   configuration files are limited to a fixed number of
+   characters.  Currently the limit is defined as 127 characters.  Note,
+   this does not apply to filenames, which may be arbitrarily long.
+\item Command line input to some of the stand alone tools -- e.g. btape,
+   bconsole is restricted to several hundred characters maximum.
+\end{itemize}
diff --git a/docs/manuals/en/main/statistics.tex b/docs/manuals/en/main/statistics.tex
new file mode 100644 (file)
index 0000000..a5732a4
--- /dev/null
@@ -0,0 +1,61 @@
+\chapter{Using Bacula catalog to grab information}
+\label{UseBaculaCatalogToExtractInformationChapter}
+\index[general]{Statistics}
+
+Bacula catalog contains lot of information about your IT infrastructure, how
+many files, their size, the number of video or music files etc. Using Bacula
+catalog during the day to get them permit to save resources on your servers.
+
+In this chapter, you will find tips and information to measure bacula
+efficiency and report statistics.
+
+\section{Job statistics}
+If you (or probably your boss) want to have statistics on your backups to
+provide some \textit{Service Level Agreement} indicators, you could use a few
+SQL queries on the Job table to report how many:
+
+\begin{itemize}
+\item jobs have run
+\item jobs have been successful
+\item files have been backed up
+\item ...
+\end{itemize}
+
+However, these statistics are accurate only if your job retention is greater
+than your statistics period. Ie, if jobs are purged from the catalog, you won't
+be able to use them. 
+
+Now, you can use the \textbf{update stats [days=num]} console command to fill
+the JobHistory table with new Job records. If you want to be sure to take in
+account only \textbf{good jobs}, ie if one of your important job has failed but
+you have fixed the problem and restarted it on time, you probably want to
+delete the first \textit{bad} job record and keep only the successful one. For
+that simply let your staff do the job, and update JobHistory table after two or
+three days depending on your organization using the \textbf{[days=num]} option.
+
+These statistics records aren't used for restoring, but mainly for
+capacity planning, billings, etc.
+
+The Bweb interface provides a statistics module that can use this feature. You
+can also use tools like Talend or extract information by yourself.
+
+The \textbf{Statistics Retention = \lt{}time\gt{}} director directive defines
+the length of time that Bacula will keep statistics job records in the Catalog
+database after the Job End time. (In \texttt{JobHistory} table) When this time
+period expires, and if user runs \texttt{prune stats} command, Bacula will
+prune (remove) Job records that are older than the specified period.
+
+You can use the following Job resource in your nightly \textbf{BackupCatalog}
+job to maintain statistics.
+\begin{verbatim}
+Job {
+  Name = BackupCatalog
+  ...
+  RunScript {
+    Console = "update stats days=3"
+    Console = "prune stats yes"
+    RunsWhen = After
+    RunsOnClient = no
+  }
+}
+\end{verbatim}
diff --git a/docs/manuals/en/main/storedconf.tex b/docs/manuals/en/main/storedconf.tex
new file mode 100644 (file)
index 0000000..b5d5419
--- /dev/null
@@ -0,0 +1,1424 @@
+%%
+%%
+
+\chapter{Storage Daemon Configuration}
+\label{StoredConfChapter}
+\index[general]{Storage Daemon Configuration}
+\index[general]{Configuration!Storage Daemon}
+
+The Storage Daemon configuration file has relatively few resource definitions.
+However, due to the great variation in backup media and system capabilities,
+the storage daemon must be highly configurable. As a consequence, there are
+quite a large number of directives in the Device Resource definition that
+allow you to define all the characteristics of your Storage device (normally a
+tape drive). Fortunately, with modern storage devices, the defaults are
+sufficient, and very few directives are actually needed. 
+
+Examples of {\bf Device} resource directives that are known to work for a
+number of common tape drives can be found in the {\bf
+\lt{}bacula-src\gt{}/examples/devices} directory, and most will also be listed
+here. 
+
+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 Storage Resource definitions must be defined: 
+
+\begin{itemize}
+\item 
+   \ilink{Storage}{StorageResource} -- to define the  name of the
+   Storage daemon.  
+\item 
+   \ilink{Director}{DirectorResource1} -- to  define the Director's
+   name and his access password.  
+\item 
+   \ilink{Device}{DeviceResource} -- to define  the
+   characteristics of your storage device (tape  drive).  
+\item 
+   \ilink{Messages}{MessagesChapter} -- to define where error  and
+   information messages are to be sent. 
+\end{itemize}
+
+\section{Storage Resource}
+\label{StorageResource}
+\index[general]{Resource!Storage}
+\index[general]{Storage Resource}
+
+In general, the properties specified under the Storage resource define global
+properties of the Storage daemon. Each Storage daemon configuration file must
+have one and only one Storage resource definition. 
+
+\begin{description}
+
+\item [Name = \lt{}Storage-Daemon-Name\gt{}]
+   \index[sd]{Name}
+   \index[sd]{Directive!Name}
+   Specifies the Name of the Storage daemon. This  directive is required. 
+
+\item [Working Directory = \lt{}Directory\gt{}]
+   \index[sd]{Working Directory}
+   \index[sd]{Directive!Working Directory}
+   This directive  is mandatory and specifies a directory in which the Storage
+   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 names
+   given to each daemon are unique. This  directive is
+   required  
+
+\item [Pid Directory = \lt{}Directory\gt{}]
+   \index[sd]{Pid Directory}
+   \index[sd]{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 directive 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[sd]{Heartbeat Interval}
+   \index[sd]{Directive!Heartbeat Interval}
+   \index[general]{Heartbeat Interval}
+   \index[general]{Broken pipe}
+   This directive defines an interval of time in seconds.  When
+   the Storage daemon is waiting for the operator to mount a
+   tape, each time interval, it will send a heartbeat signal to
+   the File daemon.  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 an valid connection after a short
+   duration despite the fact that keepalive is set.  This usually
+   results in a broken pipe error message.
+
+\item [Client Connect Wait = \lt{}time-interval\gt{}]
+   \index[sd]{Connect Wait}
+   \index[sd]{Directive!Connect Wait}
+   \index[general]{Client Connect Wait}
+   This directive defines an interval of time in seconds that
+   the Storage daemon will wait for a Client (the File daemon)
+   to connect.  The default is 30 minutes.  Be aware that the
+   longer the Storage daemon waits for a Client, the more
+   resources will be tied up.
+
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+   \index[sd]{Maximum Concurrent Jobs}
+   \index[sd]{Directive!Maximum Concurrent Jobs}
+   where \lt{}number\gt{} is the maximum number of Jobs that may run
+   concurrently.  The default is set to 10, 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.  To run simultaneous Jobs,
+   you will need to set a number of other directives in the Director's
+   configuration file.  Which ones you set depend on what you want, but you
+   will almost certainly need to set the {\bf Maximum Concurrent Jobs} in
+   the Storage resource in the Director's configuration file and possibly
+   those in the Job and Client resources.
+
+\item [SDAddresses = \lt{}IP-address-specification\gt{}]
+   \index[sd]{SDAddresses}
+   \index[sd]{Directive!SDAddresses}
+   Specify the ports and addresses on which the Storage daemon will listen
+   for Director connections.  Normally, the default is sufficient and you
+   do not need to specify this directive.  Probably the simplest way to
+   explain how this directive works is to show an example:
+
+\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
+
+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.  
+
+Using this directive, you can replace both the SDPort and SDAddress 
+directives shown below. 
+
+\item [SDPort = \lt{}port-number\gt{}]
+   \index[sd]{SDPort}
+   \index[sd]{Directive!SDPort}
+   Specifies port number on which the Storage daemon  listens for Director
+   connections. The default is 9103.  
+   
+\item [SDAddress = \lt{}IP-Address\gt{}]
+   \index[sd]{SDAddress}
+   \index[sd]{Directive!SDAddress}
+   This directive is optional, and if it is specified, it will cause the
+   Storage daemon server (for Director and File daemon 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 directive is not
+   specified, the Storage daemon will bind to any available address (the
+   default).
+
+\end{description}
+
+The following is a typical Storage daemon Storage definition. 
+
+\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{Director Resource}
+\label{DirectorResource1}
+\index[general]{Director Resource}
+\index[general]{Resource!Director}
+
+The Director resource specifies the Name of the Director which is permitted
+to use the services of the Storage daemon.  There may be multiple Director
+resources.  The Director Name and Password must match the corresponding
+values in the Director's configuration file.
+
+\begin{description}
+
+\item [Name = \lt{}Director-Name\gt{}]
+   \index[sd]{Name}
+   \index[sd]{Directive!Name}
+   Specifies the Name of the Director allowed to connect  to the Storage daemon.
+   This directive is required.  
+
+\item [Password = \lt{}Director-password\gt{}]
+   \index[sd]{Password}
+   \index[sd]{Directive!Password}
+   Specifies the password that must be supplied by the above named  Director.
+   This directive is required.  
+
+\item [Monitor = \lt{}yes\vb{}no\gt{}]
+   \index[sd]{Monitor}
+   \index[sd]{Directive!Monitor}
+   If Monitor is set to {\bf no} (default), this director will have full
+   access to this Storage daemon.  If Monitor is set to {\bf yes}, this
+   director will only be able to fetch the current status of this Storage
+   daemon.
+
+   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}
+
+The following is an example of a valid Director resource definition: 
+
+\footnotesize
+\begin{verbatim}
+Director {
+  Name = MainDirector
+  Password = my_secret_password
+}
+\end{verbatim}
+\normalsize
+
+\label{DeviceResource}
+\section{Device Resource}
+\index[general]{Resource!Device}
+\index[general]{Device Resource}
+
+The Device Resource specifies the details of each device (normally a tape
+drive) that can be used by the Storage daemon.  There may be multiple
+Device resources for a single Storage daemon.  In general, the properties
+specified within the Device resource are specific to the Device.
+
+\begin{description}
+
+\item [Name = {\it Device-Name}]
+   \index[sd]{Name}
+   \index[sd]{Directive!Name}
+   Specifies the Name that the Director will use when asking to backup or
+   restore to or from to this device. This is the logical  Device name, and may
+   be any string up to 127 characters in length.  It is generally a good idea to
+   make it correspond to the English  name of the backup device. The physical
+   name of the device is  specified on the {\bf Archive Device} directive
+   described below.  The name you specify here is also used in your Director's
+   conf  file on the 
+   \ilink{Device directive}{StorageResource2}  in its Storage
+   resource. 
+
+\item [Archive Device = {\it name-string}]
+   \index[sd]{Archive Device}
+   \index[sd]{Directive!Archive Device}
+   The specified {\bf name-string} gives the system file name of the  storage
+   device managed by this storage daemon. This will usually be  the device file
+   name of a removable storage device (tape drive),  for example "{\bf
+   /dev/nst0}" or "{\bf /dev/rmt/0mbn}".  For a DVD-writer, it will be for
+   example {\bf /dev/hdc}.  It may also be a directory name if you are archiving
+   to disk storage.  In this case, you must supply the full absolute path to the
+   directory.  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.  
+   
+   As noted above, normally the Archive Device is the name of a tape drive, but
+   you may also specify an absolute path to an existing directory. If the
+   Device is a directory Bacula will write to file storage in the specified
+   directory, and the filename used will be the Volume name as specified in the
+   Catalog.  If you want to write into more than one directory (i.e.  to spread
+   the load to different disk drives), you will need to define two Device
+   resources, each containing an Archive Device with a different directory.
+   \label{SetupFifo}
+   In addition to a tape device name or a directory name, Bacula will  accept the
+   name of a FIFO. A FIFO is a special kind of file that  connects two programs
+   via kernel memory. If a FIFO device is specified  for a backup operation, you
+   must have a program that reads what Bacula  writes into the FIFO. When the
+   Storage daemon starts the job, it  will wait for {\bf MaximumOpenWait} seconds
+   for the read program to start reading, and then time it out and  terminate
+   the job. As a consequence, it is best to start the read  program at the
+   beginning of the job perhaps with the {\bf RunBeforeJob}  directive. For this
+   kind of device, you never want to specify  {\bf AlwaysOpen}, because you want
+   the Storage daemon to open it only  when a job starts, so you must explicitly
+   set it to {\bf No}.  Since a FIFO is a one way device, Bacula will not attempt
+   to read  a label of a FIFO device, but will simply write on it. To create a 
+   FIFO Volume in the catalog, use the {\bf add} command rather than the {\bf
+   label} command to avoid attempting to write a label.
+
+\footnotesize
+\begin{verbatim}
+Device {
+  Name = FifoStorage
+  Media Type = Fifo
+  Device Type = Fifo
+  Archive Device = /tmp/fifo
+  LabelMedia = yes
+  Random Access = no
+  AutomaticMount = no
+  RemovableMedia = no
+  MaximumOpenWait = 60
+  AlwaysOpen = no
+}
+\end{verbatim}
+\normalsize
+
+   During a restore operation, if the Archive Device is a FIFO, Bacula  will
+   attempt to read from the FIFO, so you must have an external program  that
+   writes into the FIFO. Bacula will wait {\bf MaximumOpenWait} seconds  for the
+   program to begin writing and will then time it out and  terminate the job. As
+   noted above, you may use the {\bf RunBeforeJob}  to start the writer program
+   at the beginning of the job.  
+   
+   The Archive Device directive is required. 
+
+\item [Device Type = {\it type-specification}]
+   \index[sd]{Device Type}
+   \index[sd]{Directive!Device Type}
+   The Device Type specification allows you to explicitly tell Bacula
+   what kind of device you are defining. It the {\it type-specification}
+   may be one of the following:
+   \begin{description}
+   \item [File]
+     Tells Bacula that the device is a file. It may either be a
+     file defined on fixed medium or a removable filesystem such as
+     USB.  All files must be random access devices.
+   \item [Tape]
+     The device is a tape device and thus is sequential access. Tape devices
+     are controlled using ioctl() calls.
+   \item [Fifo]
+     The device is a first-in-first out sequential access read-only 
+     or write-only device.
+   \item [DVD]
+     The device is a DVD. DVDs are sequential access for writing, but
+     random access for reading.
+  \end{description}
+  
+  The Device Type directive is not required, and if not specified, Bacula
+  will attempt to guess what kind of device has been specified using the
+  Archive Device specification supplied. There are several advantages to
+  explicitly specifying the Device Type. First, on some systems, block and
+  character devices have the same type, which means that on those systems,
+  Bacula is unlikely to be able to correctly guess that a device is a DVD.
+  Secondly, if you explicitly specify the Device Type, the mount point
+  need not be defined until the device is opened. This is the case with
+  most removable devices such as USB that are mounted by the HAL daemon.
+  If the Device Type is not explicitly specified, then the mount point
+  must exist when the Storage daemon starts.
+
+  This directive was implemented in Bacula version 1.38.6.
+
+
+\item [Media Type = {\it name-string}]
+   \index[sd]{Media Type}
+   \index[sd]{Directive!Media Type}
+   The specified {\bf name-string} names the type of media supported by this
+   device, for example, "DLT7000".  Media type names are arbitrary in that you
+   set them to anything you want, but they must be known to the volume
+   database to keep track of which storage daemons can read which volumes.  In
+   general, each different storage type should have a unique Media Type
+   associated with it.  The same {\bf name-string} must appear in the
+   appropriate Storage resource definition in the Director's configuration
+   file.
+   
+   Even though the names you assign are arbitrary (i.e.  you choose the name
+   you want), you should take care in specifying them because the Media Type
+   is used to determine which storage device Bacula will select during
+   restore.  Thus you should probably use the same Media Type specification
+   for all drives where the Media can be freely interchanged.  This is not
+   generally an issue if you have a single Storage daemon, but it is with
+   multiple Storage daemons, especially if they have incompatible media.
+   
+   For example, if you specify a Media Type of "DDS-4" then during the
+   restore, Bacula will be able to choose any Storage Daemon that handles
+   "DDS-4".  If you have an autochanger, you might want to name the Media Type
+   in a way that is unique to the autochanger, unless you wish to possibly use
+   the Volumes in other drives.  You should also ensure to have unique Media
+   Type names if the Media is not compatible between drives.  This
+   specification is required for all devices.
+
+   In addition, if you are using disk storage, each Device resource will
+   generally have a different mount point or directory. In order for
+   Bacula to select the correct Device resource, each one must have a
+   unique Media Type.
+
+\label{Autochanger}
+\item [Autochanger = {\it yes\vb{}no}]
+   \index[sd]{Autochanger}
+   \index[sd]{Directive!Autochanger}
+   If {\bf Yes}, this device belongs to an automatic tape changer, and you
+   must specify an {\bf Autochanger} resource that points to the {\bf
+   Device} resources.  You must also specify a 
+   {\bf Changer Device}.  If the Autochanger directive is set to {\bf
+   No} (default), the volume must be manually changed.  You should also
+   have an identical directive to the  
+   \ilink{Storage resource}{Autochanger1}  in the Director's
+   configuration file so that  when labeling tapes you are prompted for the slot.
+
+\item [Changer Device = {\it name-string}]
+   \index[sd]{Changer Device}
+   \index[sd]{Directive!Changer Device}
+   The specified {\bf name-string} must be the {\bf generic SCSI} device
+   name of the autochanger that corresponds to the normal read/write
+   {\bf Archive Device}  specified in the Device resource. This
+   generic SCSI device name should be specified if you have an autochanger 
+   or if you have a standard tape drive and want to use the
+   {\bf Alert Command} (see below). For example, on Linux systems, for 
+   an Archive Device name of {\bf /dev/nst0}, you would specify {\bf
+   /dev/sg0} for the Changer Device name. Depending on your exact
+   configuration, and the number of autochangers or the type of
+   autochanger, what you specify here can vary.  This directive is
+   optional.  See the \ilink{ Using Autochangers}{AutochangersChapter} chapter
+   of this manual for more details of using this and the following
+   autochanger directives.
+
+\item [Changer Command = {\it name-string}]
+   \index[sd]{Changer Command}
+   \index[sd]{Directive!Changer Command}
+   The {\bf name-string} specifies an external program to be called  that will
+   automatically change volumes as required by {\bf Bacula}.  Normally,
+   this directive will be specified only in the {\bf AutoChanger} resource,
+   which is then used for all devices.  However, you may also specify
+   the different {\bf Changer Command} in each Device resource.
+   Most frequently,
+   you will specify the Bacula supplied {\bf mtx-changer}  script as follows:  
+
+\footnotesize
+\begin{verbatim}
+Changer Command = "/path/mtx-changer %c %o %S %a %d"
+\end{verbatim}
+\normalsize
+
+   and you will install the {\bf mtx} on your system (found  in the {\bf depkgs}
+   release). An example of this command is in the default bacula-sd.conf file. 
+   For more details on the substitution characters that may be specified  to
+   configure your autochanger please see  the 
+   \ilink{Autochangers}{AutochangersChapter} chapter of this  manual.
+   For FreeBSD users, you might want to see one of the  several {\bf chio}
+   scripts in {\bf examples/autochangers}.  
+
+\item [Alert Command = {\it name-string}]
+   \index[sd]{Alert Command}
+   The {\bf name-string} specifies an external program to be called at the
+   completion of each Job after the device is released.  The purpose of this
+   command is to check for Tape Alerts, which are present when something is
+   wrong with your tape drive (at least for most modern tape drives).  The same
+   substitution characters that may be specified in the Changer Command may
+   also be used in this string.  For more information, please see the
+   \ilink{Autochangers}{AutochangersChapter} chapter of this manual.
+   
+   
+   Note, it is not necessary to have an autochanger to use this command. The
+   example below uses the {\bf tapeinfo} program that comes with the {\bf mtx}
+   package, but it can be used on any tape drive. However, you will need to
+   specify a {\bf Changer Device} directive in your Device resource (see above)
+   so that the generic SCSI device name can be edited into the command (with
+   the \%c).
+   
+   An example of the use of this command to print Tape Alerts  in the Job report
+   is:  
+
+\footnotesize
+\begin{verbatim}
+Alert Command = "sh -c 'tapeinfo -f %c | grep TapeAlert'"
+      
+\end{verbatim}
+\normalsize
+
+and an example output when there is a problem could be:  
+
+\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}
+   The {\bf Drive Index} that you specify is passed to the {\bf
+   mtx-changer} script and is thus passed to the {\bf mtx} program.  By
+   default, the Drive Index is zero, so if you have only one drive in your
+   autochanger, everything will work normally.  However, if you have
+   multiple drives, you must specify multiple Bacula Device resources (one
+   for each drive).  The first Device should have the Drive Index set to 0,
+   and the second Device Resource should contain a Drive Index set to 1,
+   and so on.  This will then permit you to use two or more drives in your
+   autochanger.  As of Bacula version 1.38.0, using the {\bf Autochanger}
+   resource, Bacula will automatically ensure that only one drive at a time
+   uses the autochanger script, so you no longer need locking scripts as in
+   the past -- the default mtx-changer script works for any number of
+   drives.
+
+\item [Autoselect = {\it yes\vb{}no}]
+   \index[sd]{Autoselect}
+   \index[sd]{Directive!Autoselect}
+   If this directive is set to {\bf yes} (default), and the Device
+   belongs to an autochanger, then when the Autochanger is referenced
+   by the Director, this device can automatically be selected. If this
+   directive is set to {\bf no}, then the Device can only be referenced
+   by directly using the Device name in the Director. This is useful
+   for reserving a drive for something special such as a high priority
+   backup or restore operations.
+
+\item [Maximum Changer Wait = {\it time}]
+   \index[sd]{Maximum Changer Wait}
+   \index[sd]{Directive!Maximum Changer Wait}
+   This directive specifies the maximum time in seconds for Bacula to wait
+   for an autochanger to change the volume.  If this time is exceeded,
+   Bacula will invalidate the Volume slot number stored in the catalog and
+   try again.  If no additional changer volumes exist, Bacula will ask the
+   operator to intervene.  The default is 5 minutes.      
+% TODO: if this is the format, then maybe "5 minutes" should be in
+% TODO: quotes? define style. see others.
+
+\item [Maximum Rewind Wait = {\it time}]
+   \index[sd]{Maximum Rewind Wait}
+   \index[sd]{Directive!Maximum Rewind Wait}
+   This directive specifies the maximum time in seconds for Bacula to wait
+   for a rewind before timing out.  If this time is exceeded,
+   Bacula will cancel the job.  The default is 5 minutes.
+
+\item [Maximum Open Wait = {\it time}]
+   \index[sd]{Maximum Open Wait}
+   \index[sd]{Directive!Maximum Open Wait}
+   This directive specifies the maximum time in seconds for Bacula to wait
+   for a open before timing out.  If this time is exceeded,
+   Bacula will cancel the job.  The default is 5 minutes.
+
+\item [Always Open = {\it yes\vb{}no}]
+   \index[sd]{Always Open}
+   \index[sd]{Directive!Always Open}
+   If {\bf Yes} (default), Bacula will always keep the device open unless
+   specifically {\bf unmounted} by the Console program.  This permits
+   Bacula to ensure that the tape drive is always available, and properly
+   positioned. If you set
+   {\bf AlwaysOpen} to {\bf no} {\bf Bacula} will only open the drive when
+   necessary, and at the end of the Job if no other Jobs are using the
+   drive, it will be freed.  The next time Bacula wants to append to a tape
+   on a drive that was freed, Bacula will rewind the tape and position it to
+   the end.  To avoid unnecessary tape positioning and to minimize
+   unnecessary operator intervention, it is highly recommended that {\bf
+   Always Open = yes}.  This also ensures that the drive is available when
+   Bacula needs it.
+   
+   If you have {\bf Always Open = yes} (recommended) and you want to use the
+   drive for something else, simply use the {\bf unmount} command in the
+   Console program to release the drive. However, don't forget to remount the
+   drive with {\bf mount} when the drive is available or the next Bacula job
+   will block.
+   
+   For File storage, this directive is ignored. For a FIFO storage  device, you
+   must set this to {\bf No}.  
+   
+   Please note that if you set this directive to {\bf No} Bacula  will release
+   the tape drive between each job, and thus the next job  will rewind the tape
+   and position it to the end of the data. This  can be a very time consuming
+   operation. In addition, with this directive set to no, certain multiple
+   drive autochanger operations will fail.  We strongly recommend to keep
+   {\bf Always Open} set to {\bf Yes}
+
+\item [Volume Poll Interval = {\it time}]
+   \index[sd]{Volume Poll Interval}
+   \index[sd]{Directive!Volume Poll Interval}
+   If the time  specified on this directive is non-zero, after  asking the
+   operator to mount a new volume Bacula will  periodically poll (or read) the
+   drive at the specified  interval to see if a new volume has been mounted. If
+   the  time interval is zero (the default), no polling will occur.  This
+   directive can be useful if you want to avoid operator  intervention via the
+   console. Instead, the operator can  simply remove the old volume and insert
+   the requested one,  and Bacula on the next poll will recognize the new tape
+   and  continue. Please be aware that if you set this interval  too small, you
+   may excessively wear your tape drive if the  old tape remains in the drive,
+   since Bacula will read it on  each poll. This can be avoided by ejecting the
+   tape using  the {\bf Offline On Unmount} and the {\bf Close on Poll} 
+   directives. 
+   However, if you are using a Linux 2.6 kernel or other OSes
+   such as FreeBSD or Solaris, the Offline On Unmount will leave the drive
+   with no tape, and Bacula will not be able to properly open the drive and
+   may fail the job.  For more information on this problem, please see the
+   \ilink{description of Offline On Unmount}{NoTapeInDrive} in the Tape
+   Testing chapter.
+
+\item [Close on Poll= {\it yes\vb{}no}]
+   \index[sd]{Close on Poll}
+   \index[sd]{Directive!Close on Poll}
+   If {\bf Yes}, Bacula close the device (equivalent to  an unmount except no
+   mount is required) and reopen it at each  poll. Normally this is not too
+   useful unless you have the  {\bf Offline on Unmount} directive set, in which
+   case the  drive will be taken offline preventing wear on the tape  during any
+   future polling. Once the operator inserts a new  tape, Bacula will recognize
+   the drive on the next poll and  automatically continue with the backup. 
+   Please see above more more details.
+
+\item [Maximum Open Wait = {\it time}]
+   \index[sd]{Maximum Open Wait}
+   \index[sd]{Directive!Maximum Open Wait}
+   This directive specifies the maximum amount of time in seconds that
+   Bacula will wait for a device that is busy.  The default is 5 minutes.
+   If the device cannot be obtained, the current Job will be terminated in
+   error.  Bacula will re-attempt to open the drive the next time a Job
+   starts that needs the the drive.
+
+\label{removablemedia}
+\item [Removable media = {\it yes\vb{}no}]
+   \index[sd]{Removable media}
+   \index[sd]{Directive!Removable media}
+   If {\bf Yes}, this device supports removable media (for example, tapes
+   or CDs).  If {\bf No}, media cannot be removed (for example, an
+   intermediate backup area on a hard disk). If {\bf Removable media} is
+   enabled on a File device (as opposed to a tape) the Storage daemon will
+   assume that device may be something like a USB device that can be
+   removed or a simply a removable harddisk. When attempting to open
+   such a device, if the Volume is not found (for File devices, the Volume
+   name is the same as the Filename), then the Storage daemon will search
+   the entire device looking for likely Volume names, and for each one 
+   found, it will ask the Director if the Volume can be used.  If so,
+   the Storage daemon will use the first such Volume found.  Thus it
+   acts somewhat like a tape drive -- if the correct Volume is not found,
+   it looks at what actually is found, and if it is an appendable Volume,
+   it will use it.
+
+   If the removable medium is not automatically mounted (e.g. udev), then
+   you might consider using additional Storage daemon device directives
+   such as {\bf Requires Mount}, {\bf Mount Point}, {\bf Mount Command},
+   and {\bf Unmount Command}, all of which can be used in conjunction with
+   {\bf Removable Media}.    
+
+
+\item [Random access = {\it yes\vb{}no}]
+   \index[sd]{Random access}
+   \index[sd]{Directive!Random access}
+   If {\bf Yes}, the archive device is assumed to be a random access medium
+   which supports the {\bf lseek} (or {\bf lseek64} if Largefile is enabled
+   during configuration) facility. This should be set to {\bf Yes} for all
+   file systems such as DVD, USB, and fixed files.  It should be set to
+   {\bf No} for non-random access devices such as tapes and named pipes.
+
+
+\item [Requires Mount = {\it yes\vb{}no}]
+   \index[sd]{Requires Mount  }
+   When this directive is enabled, the Storage daemon will submit
+   a {\bf Mount Command} before attempting to open the device.
+   You must set this directive to {\bf yes} for DVD-writers and removable
+   file systems such as USB devices that are not automatically mounted
+   by the operating system when plugged in or opened by Bacula.
+   It should be set to {\bf no} for
+   all other devices such as tapes and fixed filesystems. It should also
+   be set to {\bf no} for any removable device that is automatically
+   mounted by the operating system when opened (e.g. USB devices mounted
+   by udev or hotplug). 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. 
+   This directive is used only
+   for devices that have {\bf Requires Mount} enabled such as DVD or 
+   USB file devices.
+
+\item [Mount Command = {\it name-string}]
+   \index[sd]{Mount Command}
+   This directive specifies the command that must be executed to mount 
+   devices such as DVDs and many USB devices. For DVDs, the
+   device is written directly, but 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, for a DVD, 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
+
+See the \ilink {Edit Codes}{mountcodes} section below for more details of
+the editing codes that can be used in this directive.
+
+  If you need to specify multiple commands, create a shell script.
+
+\item [Unmount Command = {\it name-string}]
+   \index[sd]{Unmount Command}
+   This directive specifies the command that must be executed to unmount 
+   devices such as DVDs and many USB devices. 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
+
+See the \ilink {Edit Codes}{mountcodes} section below for more details of
+the editing codes that can be used in this directive.
+
+  If you need to specify multiple commands, create a shell script.
+
+\item [Minimum block size = {\it size-in-bytes}]
+   \index[sd]{Minimum block size}
+   \index[sd]{Directive!Minimum block size}
+   On most modern tape drives, you will not need or want to specify this
+   directive, and if you do so, it will be to make Bacula use fixed block
+   sizes.  This statement applies only to non-random access devices (e.g.
+   tape drives).  Blocks written by the storage daemon to a non-random
+   archive device will never be smaller than the given {\bf size-in-bytes}.
+   The Storage daemon will attempt to efficiently fill blocks with data
+   received from active sessions but will, if necessary, add padding to a
+   block to achieve the required minimum size.
+   
+   To force the block size to be fixed, as is the case for some non-random
+   access devices (tape drives), set the {\bf Minimum block size} and the
+   {\bf Maximum block size} to the same value (zero included).  The default
+   is that both the minimum and maximum block size are zero and the default
+   block size is 64,512 bytes. 
+   
+   For  example, suppose you want a fixed block size of 100K bytes, then you 
+   would specify:  
+
+\footnotesize
+\begin{verbatim}
+    Minimum block size = 100K
+    Maximum block size = 100K
+    
+\end{verbatim}
+\normalsize
+
+   Please note that if you specify a fixed block size as shown above,  the tape
+   drive must either be in variable block size mode, or  if it is in fixed block
+   size mode, the block size (generally  defined by {\bf mt}) {\bf must} be
+   identical to the size specified  in Bacula -- otherwise when you attempt to
+   re-read your Volumes,  you will get an error.  
+   
+   If you want the  block size to be variable but with a 64K minimum and 200K
+   maximum (and  default as well), you would specify:  
+
+\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}
+   On most modern tape drives, you will not need to specify this directive.
+   If you do so, it will most likely be to use fixed block sizes (see
+   Minimum block size above).  The Storage daemon will always attempt to
+   write blocks of the specified {\bf size-in-bytes} to the archive device.
+   As a consequence, this statement specifies both the default block size
+   and the maximum block size.  The size written never exceed the given
+   {\bf size-in-bytes}.  If adding data to a block would cause it to exceed
+   the given maximum size, the block will be written to the archive device,
+   and the new data will begin a new block.
+   
+   If no value is specified or zero is specified, the Storage daemon will
+   use a default block size of 64,512 bytes (126 * 512).
+
+   The maximum {\bf size-in-bytes} possible is 2,000,000.
+
+\item [Hardware End of Medium = {\it yes\vb{}no}]
+   \index[sd]{Hardware End of Medium}
+   \index[sd]{Directive!Hardware End of Medium}
+   If {\bf No}, the archive device is not required to support end of medium
+   ioctl request, and the storage daemon will use the forward space file
+   function to find the end of the recorded data. If {\bf Yes}, the archive
+   device must support the {\tt ioctl} {\tt MTEOM} call, which will position
+   the tape to the end of the recorded data. In addition, your SCSI driver must
+   keep track of the file number on the tape and report it back correctly by
+   the {\bf MTIOCGET} ioctl. Note, some SCSI drivers will correctly forward
+   space to the end of the recorded data, but they do not keep track of the
+   file number.  On Linux machines, the SCSI driver has a {\bf fast-eod}
+   option, which if set will cause the driver to lose track of the file
+   number. You should ensure that this option is always turned off using the
+   {\bf mt} program.
+   
+   Default setting for Hardware End of Medium is {\bf Yes}. This  function is
+   used before appending to a tape to ensure that no  previously written data is
+   lost. We recommend if you have a non-standard or unusual tape drive that you
+   use the {\bf btape} program  to test your drive to see whether or not it
+   supports this function.  All modern (after 1998) tape drives support this
+   feature.  
+   
+\item [Fast Forward Space File = {\it yes\vb{}no}]
+   \index[sd]{Fast Forward Space File}
+   \index[sd]{Directive!Fast Forward Space File}
+   If {\bf No}, the archive device is not required to support  keeping track of
+   the file number ({\bf MTIOCGET} ioctl) during  forward space file. If {\bf
+   Yes}, the archive device must support  the {\tt ioctl} {\tt MTFSF} call, which
+   virtually all drivers  support, but in addition, your SCSI driver must keep
+   track of the  file number on the tape and report it back correctly by the 
+   {\bf MTIOCGET} ioctl. Note, some SCSI drivers will correctly  forward space,
+   but they do not keep track of the file number or more  seriously, they do not
+   report end of medium.  
+   
+   Default setting for Fast Forward Space File is {\bf Yes}.
+   
+\item [Use MTIOCGET = {\it yes\vb{}no}]
+   \index[sd]{Use MTIOCGET}
+   \index[sd]{Directive!Use MTIOCGET}
+   If {\bf No}, the operating system is not required to support keeping track of
+   the file number and reporting it in the ({\bf MTIOCGET} ioctl). The default
+   is {\bf Yes}. If you must set this to No, Bacula will do the proper file
+   position determination, but it is very unfortunate because it means that 
+   tape movement is very inefficient.
+   Fortunately, this operation system deficiency seems to be the case only
+   on a few *BSD systems.  Operating systems known to work correctly are
+   Solaris, Linux and FreeBSD.
+
+\item [BSF at EOM = {\it yes\vb{}no}]
+   \index[sd]{BSF at EOM}
+   \index[sd]{Directive!BSF at EOM}
+   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\vb{}no}]
+   \index[sd]{TWO EOF}
+   \index[sd]{Directive!TWO EOF}
+   If {\bf Yes}, Bacula will write two end of file marks when terminating a
+   tape -- i.e. after the last job or at the end of the medium. If {\bf No},
+   the default, Bacula will only write one end of file to terminate the tape.
+
+\item [Backward Space Record = {\it yes\vb{}no}]
+   \index[sd]{Backward Space Record}
+   \index[sd]{Directive!Backward Space Record}
+   If {\it Yes}, the archive device supports the {\tt MTBSR ioctl} to backspace
+   records. If {\it No}, this call is not used and the device must be rewound
+   and advanced forward to the desired position. Default is {\bf Yes} for non
+   random-access devices. This function if enabled is used at the end of a
+   Volume after writing the end of file and any ANSI/IBM labels to determine
+   whether or not the last block was written correctly. If you turn this
+   function off, the test will not be done. This causes no harm as the re-read
+   process is precautionary rather than required.
+
+\item [Backward Space File = {\it yes\vb{}no}]
+   \index[sd]{Backward Space File}
+   \index[sd]{Directive!Backward Space File}
+   If {\it Yes}, the archive device supports the {\bf MTBSF} and  {\bf MTBSF
+  ioctl}s to backspace over an end of file mark and to the  start of a file. If
+  {\it No}, these calls are not used and the  device must be rewound and
+  advanced forward to the desired position.  Default is {\bf Yes} for non
+  random-access devices. 
+
+\item [Forward Space Record = {\it yes\vb{}no}]
+   \index[sd]{Forward Space Record}
+   \index[sd]{Directive!Forward Space Record}
+   If {\it Yes}, the archive device must support the {\bf MTFSR  ioctl} to
+   forward space over records. If {\bf No}, data must  be read in order to
+   advance the position on the device. Default is  {\bf Yes} for non
+   random-access devices. 
+
+\item [Forward Space File = {\it yes\vb{}no}]
+   \index[sd]{Forward Space File}
+   \index[sd]{Directive!Forward Space File}
+   If {\bf Yes}, the archive device must support the {\tt MTFSF  ioctl} to
+   forward space by file marks. If {\it No}, data  must be read to advance the
+   position on the device. Default is  {\bf Yes} for non random-access devices. 
+
+\item [Offline On Unmount = {\it yes\vb{}no}]
+   \index[sd]{Offline On Unmount}
+   \index[sd]{Directive!Offline On Unmount}
+   The default for this directive is {\bf No}. If {\bf Yes} the  archive device
+   must support the {\tt MTOFFL ioctl} to rewind and  take the volume offline. In
+   this case, Bacula will issue the  offline (eject) request before closing the
+   device during the {\bf unmount}  command. If {\bf No} Bacula will not attempt
+   to offline the  device before unmounting it. After an offline is issued,  the
+   cassette will be ejected thus {\bf requiring operator intervention}  to
+   continue, and on some systems require an explicit load command  to be issued
+   ({\bf mt -f /dev/xxx load}) before the system will recognize  the tape. If you
+   are using an autochanger, some devices  require an offline to be issued prior
+   to changing the volume. However,  most devices do not and may get very
+   confused.  
+
+   If you are using a Linux 2.6 kernel or other OSes
+   such as FreeBSD or Solaris, the Offline On Unmount will leave the drive
+   with no tape, and Bacula will not be able to properly open the drive and
+   may fail the job.  For more information on this problem, please see the
+   \ilink{description of Offline On Unmount}{NoTapeInDrive} in the Tape
+   Testing chapter.
+
+\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
+   \index[sd]{Device Maximum Concurrent Jobs}
+   \index[sd]{Directive!Device Maximum Concurrent Jobs}
+   \index[sd]{Directive!New in 3.0.3}
+   where \lt{}number\gt{} is the maximum number of Jobs that can run
+   concurrently on a specified Device.  Using this directive, it is possible
+   to have different Jobs using multiple drives, because when 
+   the Maximum Concurrent Jobs limit is
+   reached, the Storage Daemon will start new Jobs on any other available
+   compatible drive.  This facilitates writing to multiple drives with
+   multiple Jobs that all use the same Pool.
+
+\item [Maximum Volume Size = {\it size}]
+   \index[sd]{Maximum Volume Size}
+   \index[sd]{Directive!Maximum Volume Size}
+   No more than {\bf size} bytes will be written onto a given volume on the
+   archive device.  This directive is used mainly in testing Bacula to
+   simulate a small Volume.  It can also be useful if you wish to limit the
+   size of a File Volume to say less than 2GB of data.  In some rare cases
+   of really antiquated tape drives that do not properly indicate when the
+   end of a tape is reached during writing (though I have read about such
+   drives, I have never personally encountered one).  Please note, this
+   directive is deprecated (being phased out) in favor of the {\bf Maximum
+   Volume Bytes} defined in the Director's configuration file.
+
+\item [Maximum File Size = {\it size}]
+   \index[sd]{Maximum File Size}
+   \index[sd]{Directive!Maximum File Size}
+   No more than {\bf size} bytes will be written into a given logical file
+   on the volume.  Once this size is reached, an end of file mark is
+   written on the volume and subsequent data are written into the next
+   file.  Breaking long sequences of data blocks with file marks permits
+   quicker positioning to the start of a given stream of data and can
+   improve recovery from read errors on the volume.  The default is one
+   Gigabyte.  This directive creates EOF marks only on tape media.
+   However, regardless of the medium type (tape, disk, DVD, ...) each time
+   a the Maximum File Size is exceeded, a record is put into the catalog
+   database that permits seeking to that position on the medium for
+   restore operations. If you set this to a small value (e.g. 1MB),
+   you will generate lots of database records (JobMedia) and may
+   significantly increase CPU/disk overhead.
+
+   If you are configuring an LTO-3 or LTO-4 tape, you probably will
+   want to set the {\bf Maximum File Size} to 2GB to avoid making
+   the drive stop to write an EOF mark.
+
+   Note, this directive does not limit the size of Volumes that Bacula
+   will create regardless of whether they are tape or disk volumes. It
+   changes only the number of EOF marks on a tape and the number of
+   block positioning records (see below) that are generated. If you
+   want to limit the size of all Volumes for a particular device, use
+   the {\bf Maximum Volume Size} directive (above), or use the
+   {\bf Maximum Volume Bytes} directive in the Director's Pool resource,
+   which does the same thing but on a Pool (Volume) basis.
+
+\item [Block Positioning = {\it yes\vb{}no}]
+   \index[sd]{Block Positioning}
+   \index[sd]{Directive!Block Positioning}
+   This directive tells Bacula not to use block positioning when doing restores.
+   Turning this directive off can cause Bacula to be {\bf extremely} slow
+   when restoring files.  You might use this directive if you wrote your
+   tapes with Bacula in variable block mode (the default), but your drive
+   was in fixed block mode. The default is {\bf yes}.
+
+\item [Maximum Network Buffer Size = {\it bytes}]
+   \index[sd]{Maximum Network Buffer Size}
+   \index[sd]{Directive!Maximum Network Buffer Size}
+   where {\it bytes} 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
+   32,768 bytes.
+
+   The default size was chosen to be relatively large but not too big in
+   the case that you are transmitting data over Internet.  It is clear that
+   on a high speed local network, you can increase this number and improve
+   performance. For example, some users have found that if you use a value
+   of 65,536 bytes they get five to ten times the throughput.  Larger values for
+   most users don't seem to improve performance. If you are interested
+   in improving your backup speeds, this is definitely a place to
+   experiment. You will probably also want to make the corresponding change
+   in each of your File daemons conf files.
+
+
+\item [Maximum Spool Size = {\it bytes}]
+   \index[sd]{Maximum Spool Size}
+   \index[sd]{Directive!Maximum Spool Size}
+   where the bytes specify the maximum spool size for all jobs that are
+   running.  The default is no limit.
+
+\item [Maximum Job Spool Size = {\it bytes}]
+   \index[sd]{Maximum Job Spool Size}
+   \index[sd]{Directive!Maximum Job Spool Size}
+   where the bytes specify the maximum spool size for any one job  that is
+   running. The default is no limit. 
+   This directive is implemented only in version 1.37 and later.
+
+\item [Spool Directory = {\it directory}]
+   \index[sd]{Spool Directory}
+   \index[sd]{Directive!Spool Directory}
+   specifies the name of the directory to be used to store  the spool files for
+   this device. This directory is also used to store  temporary part files when
+   writing to a device that requires mount (DVD).  The default is to use the
+   working directory. 
+
+\item [Maximum Part Size = {\it bytes}]
+   \index[sd]{Maximum Part Size}
+   \index[sd]{Directive!Maximum Part Size}
+   This is the maximum size of a volume part file. The default is no limit.
+   This directive is implemented only in version 1.37 and later.
+
+   If the device requires  mount, it is transferred to the device when this size
+   is reached.  In this case, you must take care to have enough disk space left
+   in  the spool directory.  
+
+   Otherwise, it is left on the hard disk.  
+
+   It is ignored for tape and FIFO devices.  
+
+
+\end{description}
+
+\label{mountcodes}
+\section{Edit Codes for Mount and Unmount Directives} 
+\index[general]{Directives!Edit Codes}
+\index[general]{Edit Codes for Mount and Unmount 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{Devices that require a mount (DVD)}
+\index[general]{Devices that require a mount (DVD)}
+\index[general]{DVD!Devices that require a mount}
+
+All the directives in this section are implemented only in
+Bacula version 1.37 and later and hence are available in version 1.38.6.
+
+As of version 1.39.5, the directives
+"Requires Mount", "Mount Point", "Mount Command", and "Unmount Command"
+apply to removable filesystems such as USB in addition to DVD.
+
+\begin{description}
+
+\item [Requires Mount = {\it yes\vb{}no}]
+   \index[sd]{Requires Mount}
+   \index[sd]{Directive!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 to be read,  and if it must be written in a special way.
+   If it set, {\bf Mount Point},  {\bf Mount Command}, {\bf Unmount Command} and
+   {\bf Write Part Command}  directives must also be defined. 
+
+\item [Mount Point = {\it directory}]
+   \index[sd]{Mount Point}
+   \index[sd]{Directive!Mount Point}
+   Directory where the device can be mounted. 
+
+\item [Mount Command = {\it name-string}]
+   \index[sd]{Mount Command}
+   \index[sd]{Directive!Mount Command}
+   Command that must be executed to mount 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}
+  Mount Command = "/bin/mount -t iso9660 -o ro %a %m"
+\end{verbatim}
+\normalsize
+
+For some media, you may need multiple commands.  If so, it is recommended
+that you use a shell script instead of putting them all into the Mount
+Command.  For example, instead of this:
+
+\footnotesize
+\begin{verbatim}
+  Mount Command = "/usr/local/bin/mymount"
+\end{verbatim}
+\normalsize
+
+Where that script contains:
+
+\footnotesize
+\begin{verbatim}
+#!/bin/sh
+ndasadmin enable -s 1 -o w
+sleep 2
+mount /dev/ndas-00323794-0p1 /backup
+\end{verbatim}
+\normalsize
+
+Similar consideration should be given to all other Command parameters.
+
+\item [Unmount Command = {\it name-string}]
+   \index[sd]{Unmount Command}
+   \index[sd]{Directive!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
+
+  If you need to specify multiple commands, create a shell script.
+
+\item [Write Part Command = {\it name-string}]
+   \index[sd]{Write Part Command}
+   \index[sd]{Directive!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.
+
+  If you need to specify multiple commands, create a shell script.
+
+
+\item [Free Space Command = {\it name-string}]
+   \index[sd]{Free Space Command}
+   \index[sd]{Directive!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, \%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}
+  Free Space Command = "/path/dvd-handler %a free"
+\end{verbatim}
+\normalsize
+
+  Where {\bf /path} is the path to your scripts install directory, and
+  dvd-handler is the Bacula supplied script file.
+  If you want to specify your own command, please look at the code of
+  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. 
+
+  If you need to specify multiple commands, create a shell script.
+
+\end{description}
+
+%% This pulls in the Autochanger resource from another file.
+\label{AutochangerRes}
+\label{AutochangerResource1}
+\input{autochangerres}
+
+
+
+
+\section{Capabilities}
+\index[general]{Capabilities}
+
+\begin{description}
+
+\item [Label media = {\it yes\vb{}no}]
+   \index[sd]{Label media}
+   \index[sd]{Directive!Label media}
+   If {\bf Yes}, permits this device to automatically label blank media
+   without an explicit operator command.  It does so by using an internal
+   algorithm as defined on the \ilink{Label Format}{Label} record in each
+   Pool resource.  If this is {\bf No} as by default, Bacula will label
+   tapes only by specific operator command ({\bf label} in the Console) or
+   when the tape has been recycled.  The automatic labeling feature is most
+   useful when writing to disk rather than tape volumes.
+
+\item [Automatic mount = {\it yes\vb{}no}]
+   \index[sd]{Automatic mount}
+   \index[sd]{Directive!Automatic mount}
+   If {\bf Yes} (the default), permits the daemon to examine the device to
+   determine if it contains a Bacula labeled volume.  This is done
+   initially when the daemon is started, and then at the beginning of each
+   job.  This directive is particularly important if you have set
+   {\bf Always Open = no} because it permits Bacula to attempt to read the
+   device before asking the system operator to mount a tape.  However,
+   please note that the tape must be mounted before the job begins.
+
+\end{description}
+
+\section{Messages Resource}
+\label{MessagesResource1}
+\index[general]{Resource!Messages}
+\index[general]{Messages Resource}
+
+For a description of the Messages Resource, please see the 
+\ilink{Messages Resource}{MessagesChapter} Chapter of this
+manual. 
+
+\section{Sample Storage Daemon Configuration File}
+\label{SampleConfiguration}
+\index[general]{File!Sample Storage Daemon Configuration}
+\index[general]{Sample Storage Daemon Configuration File}
+
+A example Storage Daemon configuration file might be the following: 
+
+\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
diff --git a/docs/manuals/en/main/strategies.tex b/docs/manuals/en/main/strategies.tex
new file mode 100644 (file)
index 0000000..b0bcfeb
--- /dev/null
@@ -0,0 +1,439 @@
+%%
+%%
+
+\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 <\&ltEND_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. 
diff --git a/docs/manuals/en/main/supportedchangers.tex b/docs/manuals/en/main/supportedchangers.tex
new file mode 100644 (file)
index 0000000..ebf876b
--- /dev/null
@@ -0,0 +1,76 @@
+%%
+%%
+
+\chapter{Supported Autochangers}
+\label{Models}
+\index[general]{Supported Autochanger Models}
+\index[general]{Autochangers!Supported}
+
+I hesitate to call these "supported" autochangers because the only
+autochangers that I have in my possession and am able to test are the HP
+SureStore DAT40X6 and the Overland PowerLoader LTO-2.  All the other
+autochangers have been reported to work by Bacula users.  Note, in the
+Capacity/Slot column below, I quote the Compressed capacity per tape (or
+Slot).
+
+Since on most systems (other than FreeBSD), Bacula uses {\bf mtx}
+through the {\bf mtx-changer} script, in principle, if {\bf mtx}
+will operate your changer correctly, then it is just a question
+of adapting the {\bf mtx-changer} script (or selecting one
+already adapted) for proper interfacing.  You can find a list of
+autochangers supported by {\bf mtx} at the following link:
+\elink{http://mtx.opensource-sw.net/compatibility.php}
+{\url{http://mtx.opensource-sw.net/compatibility.php}}.
+The home page for the {\bf mtx} project can be found at:
+\elink{http://mtx.opensource-sw.net/}{\url{http://mtx.opensource-sw.net/}}.
+
+
+\addcontentsline{lot}{table}{Autochangers Known to Work with 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 Man. } &
+\multicolumn{1}{c| }{\bf Media } & \multicolumn{1}{c| }{\bf Model } &
+\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 {Linux } & {BDT } & {AIT } & {BDT ThinStor } & {?} & {200GB  } \\
+ \hline {- } & {CA-VM } & {?? } & {Tape } & {??} & {??  } \\
+ \hline {Linux } & {Dell} & {DLT VI,LTO-2,LTO3} & {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 } & {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 {FreeBSD 5.4} & {IBM } & {DLT} & {IBM 3502-R14 -- rebranded ATL L-500} & {14} & {35/70GB  } \\
+ \hline {Linux} & {IBM } & {???} & {IBM TotalStorage 3582L23} & {??} & {??  } \\
+ \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 {Linux} & {Quantum } & {DLT-S4} & {Superloader 3} & {16} & {800/1600GB } \\
+ \hline {Linux} & {Quantum } & {LTO-2} & {Superloader 3} & {16} & {200/400GB } \\
+ \hline {Linux} & {Quantum } & {LTO-3 } & {PX502 } & {??} & {?? } \\
+ \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}
diff --git a/docs/manuals/en/main/supporteddrives.tex b/docs/manuals/en/main/supporteddrives.tex
new file mode 100644 (file)
index 0000000..005ba40
--- /dev/null
@@ -0,0 +1,158 @@
+%%
+%%
+
+\chapter{Supported Tape Drives}
+\label{SupportedDrives}
+\index[general]{Drives!Supported Tape }
+\index[general]{Supported Tape Drives }
+
+Bacula uses standard operating system calls (read, write, ioctl) to 
+interface to tape drives.  As a consequence, it relies on having a
+correctly written OS tape driver. Bacula is known to work perfectly well
+with SCSI tape drivers on FreeBSD, Linux, Solaris, and Windows machines,
+and it may work on other *nix machines, but we have not tested it.
+Recently there are many new drives that use IDE, ATAPI, or
+SATA interfaces rather than SCSI. On Linux the OnStream drive, which uses
+the OSST driver is one such
+example, and it is known to work with Bacula. In addition a number of such
+tape drives (i.e. OS drivers) seem to work on Windows systems.  However,
+non-SCSI tape drives (other than the OnStream) that use ide-scis, ide-tape, 
+or other non-scsi drivers do not function correctly with Bacula (or any
+other demanding tape application) as of today (April 2007).  If you
+have purchased a non-SCSI tape drive for use with Bacula on Linux, there
+is a good chance that it will not work. We are working with the kernel
+developers to rectify this situation, but it will not be resolved in the 
+near future.
+
+Even if your drive is on the list below, please check the 
+\ilink{Tape Testing Chapter}{btape1} of this manual for
+procedures that you can use to verify if your tape drive will work with
+Bacula. If your drive is in fixed block mode, it may appear to work with
+Bacula until you attempt to do a restore and Bacula wants to position the
+tape. You can be sure only by following the procedures suggested above and
+testing. 
+
+It is very difficult to supply a list of supported tape drives, or drives that
+are known to work with Bacula because of limited feedback (so if you use
+Bacula on a different drive, please let us know). Based on user feedback, the
+following drives are known to work with Bacula. A dash in a column means
+unknown: 
+
+\addcontentsline{lot}{table}{Supported Tape Drives}
+\begin{longtable}{|p{2.0in}|l|l|p{2.5in}|l|}
+ \hline 
+\multicolumn{1}{|c| }{\bf OS } & \multicolumn{1}{c| }{\bf Man. } &
+\multicolumn{1}{c| }{\bf Media } & \multicolumn{1}{c| }{\bf Model } &
+\multicolumn{1}{c| }{\bf Capacity  } \\
+ \hline {- } & {ADIC } & {DLT } & {Adic Scalar 100 DLT } & {100GB  } \\
+ \hline {- } & {ADIC } & {DLT } & {Adic Fastor 22 DLT } & {-  } \\
+ \hline {FreeBSD 5.4-RELEASE-p1 amd64 } & {Certance} & {LTO } & {AdicCertance CL400 LTO Ultrium 2 } & {200GB  } \\
+ \hline {- } & {- } & {DDS } & {Compaq DDS 2,3,4 } & {-  } \\
+ \hline {SuSE 8.1 Pro} & {Compaq} & {AIT } & {Compaq AIT 35 LVD } & {35/70GB } \\
+ \hline {- } & {Exabyte } & {-  } & {Exabyte drives less than 10 years old } & {-  } \\
+ \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 {- } & {IBM} & {??} & {3480, 3480XL, 3490, 3490E, 3580 and 3590 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 {FreeBSD 4.11-Release} & {Quantum } & {SDLT } & {SDLT320 } & {160/320GB  } \\
+ \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 
+
+\end{longtable}
+
+There is a list of \ilink{supported autochangers}{Models} in the Supported
+Autochangers chapter of this document, where you will find other tape drives
+that work with Bacula. 
+
+\section{Unsupported Tape Drives}
+\label{UnSupportedDrives}
+\index[general]{Unsupported Tape Drives }
+\index[general]{Drives!Unsupported Tape }
+
+Previously OnStream IDE-SCSI tape drives did not work with Bacula. As of
+Bacula version 1.33 and the osst kernel driver version 0.9.14 or later, they
+now work. Please see the testing chapter as you must set a fixed block size. 
+
+QIC tapes are known to have a number of particularities (fixed block size, and
+one EOF rather than two to terminate the tape). As a consequence, you will
+need to take a lot of care in configuring them to make them work correctly
+with Bacula. 
+
+\section{FreeBSD Users Be Aware!!!}
+\index[general]{FreeBSD Users Be Aware }
+\index[general]{Aware!FreeBSD Users Be }
+
+Unless you have patched the pthreads library on FreeBSD 4.11 systems, you will
+lose data when Bacula spans tapes. This is because the unpatched pthreads
+library fails to return a warning status to Bacula that the end of the tape is
+near. This problem is fixed in FreeBSD systems released after 4.11. Please see the 
+\ilink{Tape Testing Chapter}{FreeBSDTapes} of this manual for
+{\bf important} information on how to configure your tape drive for
+compatibility with Bacula. 
+
+\section{Supported Autochangers}
+\index[general]{Autochangers!Supported }
+\index[general]{Supported Autochangers }
+
+For information on supported autochangers, please see the 
+\ilink{Autochangers Known to Work with Bacula}{Models}
+section of the Supported Autochangers chapter of this manual. 
+
+\section{Tape Specifications}
+\index[general]{Specifications!Tape}
+\index[general]{Tape Specifications}
+If you want to know what tape drive to buy that will work with Bacula,
+we really cannot tell you.  However, we can say that if you are going
+to buy a drive, you should try to avoid DDS drives. The technology is
+rather old and DDS tape drives need frequent cleaning.  DLT drives are 
+generally much better (newer technology) and do not need frequent 
+cleaning.
+
+Below, you will find a table of DLT and LTO tape specifications that will
+give you some idea of the capacity and speed of modern tapes. The 
+capacities that are listed are the native tape capacity without compression.
+All modern drives have hardware compression, and manufacturers often list
+compressed capacity using a compression ration of 2:1. The actual compression 
+ratio will depend mostly on the data you have to backup, but I find that
+1.5:1 is a much more reasonable number (i.e. multiply the value shown in 
+the table by 1.5 to get a rough average of what you will probably see).
+The transfer rates are rounded to the nearest GB/hr.  All values are provided
+by various manufacturers.
+
+The Media Type is what is designated by the manufacturers and you are not
+required to use (but you may) the same name in your Bacula conf resources.
+
+
+\begin{tabular}{|c|c|c|c}
+Media Type      & Drive Type & Media Capacity & Transfer Rate \\ \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 Ultrium 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}
diff --git a/docs/manuals/en/main/supportedoses.tex b/docs/manuals/en/main/supportedoses.tex
new file mode 100644 (file)
index 0000000..bf4d937
--- /dev/null
@@ -0,0 +1,90 @@
+%%
+%%
+
+\chapter{Supported Operating Systems}
+\label{SupportedOSes}
+\index[general]{Systems!Supported Operating }
+\index[general]{Supported Operating Systems }
+
+\begin{itemize}
+\item[X] Fully supported
+\item[$\star$] The are reported to work in many cases.  However they are NOT
+  supported by the bacula's project.
+\end{itemize}
+
+
+\begin{tabular}[h]{|l|l|c|c|c|}
+  \hline
+  Operating Systems & Version & Client \small{Daemon} & Director \small{Daemon} & Storage \small{Daemon} \\
+  \hline
+  \hline
+  GNU/Linux
+  & All & X & X & X \\
+  \hline
+  FreeBSD & $\geq$ 5.0 & X & X & X
+  \\
+  \hline
+  Solaris & $\geq$ 8 & X & X & X \\
+  \hline
+  OpenSolaris & ~ & X & X & X \\
+  \hline
+  \hline
+  MS Windows 32bit& Win98/Me & X  & ~ & ~ \\
+  \hline
+  ~ & WinNT/2K & X  & $\star$ & $\star$ \\
+  \hline
+  ~ & XP & X  & $\star$ & $\star$ \\
+  ~ & 2008/Vista & X  & $\star$ & $\star$ \\
+  MS Windows 64bit& 2008/Vista & X  & ~ & ~ \\
+  \hline
+  \hline
+  MacOS X/Darwin & ~ & X & ~ & ~ \\
+  \hline
+  OpenBSD & ~ & X & $\star$ & ~ \\
+  \hline
+  NetBSD & ~ & X & $\star$ & ~ \\
+  \hline
+  Irix & ~ & $\star$ & ~ & ~ \\
+  \hline
+  True64 & ~ & $\star$ & ~ & ~ \\
+  \hline
+  AIX & $\geq$ 4.3 & $\star$ & ~ & ~ \\
+  \hline
+  BSDI & ~ & $\star$ & ~ & ~ \\
+  \hline
+  HPUX & ~ & $\star$ & ~ & ~ \\
+  \hline
+\end{tabular}
+
+\section*{Important notes}
+
+\begin{itemize}
+\item By GNU/Linux, we mean 32/64bit Gentoo, Red Hat, Fedora, Mandriva,
+    Debian, OpenSuSE, Ubuntu, Kubuntu, \dots
+
+\item For FreeBSD older than version 5.0,
+  please see some {\bf important} considerations in the
+  \ilink{ Tape Modes on FreeBSD}{FreeBSDTapes}  section of the
+  Tape Testing chapter of this manual.
+
+\item MS Windows Director and Storage daemon are available
+      in the binary Client installer
+
+\item For MacOSX see \elink{http://fink.sourceforge.net/ for obtaining the packages}{http://fink.sourceforge.net/}
+\end{itemize}
+
+See the Porting chapter of the Bacula Developer's Guide for information on
+porting to other systems.
+
+If you have a older Red Hat Linux system running the 2.4.x kernel and you have
+the directory {\bf /lib/tls} installed on your system (normally by default),
+bacula will {\bf NOT} run. This is the new pthreads library and it is
+defective. You must remove this directory prior to running Bacula, or you can
+simply change the name to {\bf /lib/tls-broken}) then you must reboot your
+machine (one of the few times Linux must be rebooted). If you are not able to
+remove/rename /lib/tls, an alternative is to set the environment variable
+"LD\_ASSUME\_KERNEL=2.4.19" prior to executing Bacula. For this option, you do
+not need to reboot, and all programs other than Bacula will continue to use
+/lib/tls.
+The above mentioned {\bf /lib/tls} problem does not occur with Linux 2.6 kernels.
+
diff --git a/docs/manuals/en/main/thanks.tex b/docs/manuals/en/main/thanks.tex
new file mode 100644 (file)
index 0000000..aa32492
--- /dev/null
@@ -0,0 +1,102 @@
+%%
+%%
+
+\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. 
diff --git a/docs/manuals/en/main/tls.tex b/docs/manuals/en/main/tls.tex
new file mode 100644 (file)
index 0000000..6c90e11
--- /dev/null
@@ -0,0 +1,315 @@
+
+\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
diff --git a/docs/manuals/en/main/translate_images.pl b/docs/manuals/en/main/translate_images.pl
new file mode 100755 (executable)
index 0000000..c722511
--- /dev/null
@@ -0,0 +1,185 @@
+#!/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);
diff --git a/docs/manuals/en/main/tutorial.tex b/docs/manuals/en/main/tutorial.tex
new file mode 100644 (file)
index 0000000..1dd8bd0
--- /dev/null
@@ -0,0 +1,1357 @@
+%%
+%%
+
+\chapter{A Brief Tutorial}
+\label{TutorialChapter}
+\index[general]{Brief Tutorial }
+\index[general]{Tutorial!Brief }
+
+This chapter will guide you through running Bacula. To do so, we assume you
+have installed Bacula, possibly in a single file as shown in the previous
+chapter, in which case, you can run Bacula as non-root for these tests.
+However, we assume that you have not changed the .conf files. If you have
+modified the .conf files, please go back and uninstall Bacula, then reinstall
+it, but do not make any changes. The examples in this chapter use the default
+configuration files, and will write the volumes to disk in your {\bf /tmp}
+directory, in addition, the data backed up will be the source directory where
+you built Bacula. As a consequence, you can run all the Bacula daemons for
+these tests as non-root. Please note, in production, your File daemon(s) must
+run as root. See the Security chapter for more information on this subject. 
+
+% TODO: use crossreferences above
+% TODO: add a section here
+
+The general flow of running Bacula is: 
+
+\begin{enumerate}
+\item cd \lt{}install-directory\gt{}  
+\item Start the Database (if using MySQL or PostgreSQL)  
+\item Start the Daemons with {\bf ./bacula start}  
+\item Start the Console program to interact with the Director  
+\item Run a job  
+\item When the Volume fills, unmount the Volume, if it is a  tape, label a new
+   one, and continue running. In this  chapter, we will write only to disk files
+   so you won't  need to worry about tapes for the moment. 
+\item Test recovering some files from the Volume just written to  ensure the
+   backup is good and that you know how to recover.  Better test before disaster
+   strikes  
+\item Add a second client. 
+   \end{enumerate}
+
+Each of these steps is described in more detail below. 
+
+\section{Before Running Bacula}
+\index[general]{Bacula!Before Running }
+\index[general]{Before Running Bacula }
+
+% TODO: some of this content is already covered once or twice critical
+% TODO: or quickstart. Consolidate!
+
+Before running Bacula for the first time in production, we recommend that you
+run the {\bf test} command in the {\bf btape} program as described in the 
+\ilink{Utility Program Chapter}{btape} of this manual. This will
+help ensure that Bacula functions correctly with your tape drive. If you have
+a modern HP, Sony, or Quantum DDS or DLT tape drive running on Linux or
+Solaris, you can probably skip this test as Bacula is well tested with these
+drives and systems. For all other cases, you are {\bf strongly} encouraged to
+run the test before continuing. {\bf btape} also has a {\bf fill} command that
+attempts to duplicate what Bacula does when filling a tape and writing on the
+next tape. You should consider trying this command as well, but be forewarned,
+it can take hours (about four hours on my drive) to fill a large capacity tape. 
+
+\section{Starting the Database}
+\label{StartDB}
+\index[general]{Starting the Database }
+\index[general]{Database!Starting the }
+
+If you are using MySQL or PostgreSQL as the Bacula database, you should start
+it before you attempt to run a job to avoid getting error messages from Bacula
+when it starts. The scripts {\bf startmysql} and {\bf stopmysql} are what I
+(Kern) use to start and stop my local MySQL. Note, if you are using SQLite,
+you will not want to use {\bf startmysql} or {\bf stopmysql}. If you are
+running this in production, you will probably want to find some way to
+automatically start MySQL or PostgreSQL after each system reboot. 
+
+If you are using SQLite (i.e. you specified the {\bf \verb:--:with-sqlite=xxx} option
+on the {\bf ./configure} command, you need do nothing. SQLite is automatically
+started by {\bf Bacula}. 
+
+\section{Starting the Daemons}
+\label{StartDaemon}
+\index[general]{Starting the Daemons }
+\index[general]{Daemons!Starting the }
+
+Assuming you have built from source or have installed the rpms,
+to start the three daemons, from your installation directory, simply enter: 
+
+./bacula start 
+
+The {\bf bacula} script starts the Storage daemon, the File daemon, and the
+Director daemon, which all normally run as daemons in the background. If you
+are using the autostart feature of Bacula, your daemons will either be
+automatically started on reboot, or you can control them individually with the
+files {\bf bacula-dir}, {\bf bacula-fd}, and {\bf bacula-sd}, which are
+usually located in {\bf /etc/init.d}, though the actual location is system
+dependent. 
+Some distributions may do this differently.
+
+Note, on Windows, currently only the File daemon is ported, and it must be
+started differently. Please see the 
+\ilink{Windows Version of Bacula}{Win32Chapter} Chapter of this
+manual. 
+
+The rpm packages configure the daemons to run as user=root and group=bacula.
+The rpm installation also creates the group bacula if it does not exist on the
+system. Any users that you add to the group bacula will have access to files
+created by the daemons. To disable or alter this behavior edit the daemon
+startup scripts: 
+
+\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}
+
+and then restart as noted above. 
+
+The 
+\ilink{installation chapter}{InstallChapter} of this manual
+explains how you can install scripts that will automatically restart the
+daemons when the system starts. 
+
+\section{Using the Director to Query and Start Jobs}
+\index[general]{Jobs!Querying or Starting Jobs}
+\index[general]{Querying or starting Jobs}
+% TODO: section name is too long; maybe use "Using the Console Program" ??
+
+To communicate with the director and to query the state of Bacula or run jobs,
+from the top level directory, simply enter: 
+
+./bconsole 
+
+Alternatively to running the command line console, if you have
+Qt4 installed and used the {\bf \verb:--:enable-bat} on the configure command,
+you may use the Bacula Administration Tool ({\bf bat}):
+
+./bat
+
+Which has a graphical interface, and many more features than bconsole.
+
+Two other possibilities are to run the GNOME console 
+{\bf bgnome-console} or the wxWidgets program {\bf bwx-console}.
+
+For simplicity, here we will describe only the {\bf ./bconsole} program. Most
+of what is described here applies equally well to {\bf ./bat},
+{\bf ./bgnome-console}, and to {\bf bwx-console}.
+
+The {\bf ./bconsole} runs the Bacula Console program, which connects to the
+Director daemon. Since Bacula is a network program, you can run the Console
+program anywhere on your network. Most frequently, however, one runs it on the
+same machine as the Director. Normally, the Console program will print
+something similar to the following: 
+
+\footnotesize
+\begin{verbatim}
+[kern@polymatou bin]$ ./bconsole
+Connecting to Director lpmatou:9101
+1000 OK: HeadMan Version: 2.1.8 (14 May 2007)
+*
+\end{verbatim}
+\normalsize
+
+the asterisk is the console command prompt. 
+
+Type {\bf help} to see a list of available commands: 
+
+\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 [<jobid=nnn> | <job=name>] -- cancel a job
+  create     create DB Pool from resource
+  delete     delete [pool=<pool-name> | media volume=<volume-name>]
+  disable    disable <job=name> -- disable a job
+  enable     enable <job=name> -- enable a job
+  estimate   performs FileSet estimate, listing gives full listing
+  exit       exit = quit
+  gui        gui [on|off] -- non-interactive gui mode
+  help       print this command
+  list       list [pools | jobs | jobtotals | media <pool=pool-name> |
+files <jobid=nn>]; from catalog
+  label      label a tape
+  llist      full or long list like list command
+  memory     print current memory usage
+  messages   messages
+  mount      mount <storage-name>
+  prune      prune expired records from catalog
+  purge      purge records from catalog
+  python     python control commands
+  quit       quit
+  query      query catalog
+  restore    restore files
+  relabel    relabel a tape
+  release    release <storage-name>
+  reload     reload conf file
+  run        run <job-name>
+  status     status [[slots] storage | dir | client]=<name>
+  setdebug   sets debug level
+  setip      sets new client address -- if authorized
+  show       show (resource records) [jobs | pools | ... | all]
+  sqlquery   use SQL to query catalog
+  time       print current time
+  trace      turn on/off trace to file
+  unmount    unmount <storage-name>
+  umount     umount <storage-name> for old-time Unix guys
+  update     update Volume, Pool or slots
+  use        use catalog xxx
+  var        does variable expansion
+  version    print Director version
+  wait       wait until no jobs are running [<jobname=name> | <jobid=nnn> | <ujobid=complete_name>]
+*
+\end{verbatim}
+\normalsize
+
+Details of the console program's commands are explained in the 
+\ilink{Console Chapter}{_ConsoleChapter} of this manual. 
+
+\section{Running a Job}
+\label{Running}
+\index[general]{Job!Running a }
+\index[general]{Running a Job }
+
+At this point, we assume you have done the following: 
+
+\begin{itemize}
+\item Configured Bacula with {\bf ./configure \verb:--:your-options} 
+\item Built Bacula using {\bf make} 
+\item Installed Bacula using {\bf make install} 
+\item Have created your database with, for example,  {\bf
+   ./create\_sqlite\_database} 
+\item Have created the Bacula database tables with,  {\bf
+   ./make\_bacula\_tables} 
+\item Have possibly edited your {\bf bacula-dir.conf} file  to personalize it
+   a bit. BE CAREFUL! if you change the  Director's name or password, you will
+   need to make similar  modifications in the other .conf files. For the moment
+   it is  probably better to make no changes.  
+\item You have started Bacula with {\bf ./bacula start}  
+\item You have invoked the Console program with {\bf ./bconsole} 
+\end{itemize}
+
+Furthermore, we assume for the moment you are using the default configuration
+files. 
+
+At this point, enter the following command: 
+
+\footnotesize
+\begin{verbatim}
+show filesets
+\end{verbatim}
+\normalsize
+
+and you should get something similar to: 
+
+\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
+
+This is a pre-defined {\bf FileSet} that will backup the Bacula source
+directory. The actual directory names printed should correspond to your system
+configuration. For testing purposes, we have chosen a directory of moderate
+size (about 40 Megabytes) and complexity without being too big. The FileSet
+{\bf Catalog} is used for backing up Bacula's catalog and is not of interest
+to us for the moment. The {\bf I} entries are the files or directories that
+will be included in the backup and the {\bf E} are those that will be
+excluded, and the {\bf O} entries are the options specified for
+the FileSet. You can change what is backed up by editing {\bf bacula-dir.conf}  
+and changing the {\bf File =} line in the {\bf FileSet} resource.
+
+Now is the time to run your first backup job. We are going to backup your
+Bacula source directory to a File Volume in your {\bf /tmp} directory just to
+show you how easy it is. Now enter: 
+
+\footnotesize
+\begin{verbatim}
+status dir
+\end{verbatim}
+\normalsize
+
+and you should get the following output: 
+
+\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
+
+where the times and the Director's name will be different according to your
+setup. This shows that an Incremental job is scheduled to run for the Job {\bf
+Client1} at 1:05am and that at 1:10, a {\bf BackupCatalog} is scheduled to
+run. Note, you should probably change the name {\bf Client1} to be the name of
+your machine, if not, when you add additional clients, it will be very
+confusing. For my real machine, I use {\bf Rufus} rather than {\bf Client1} as
+in this example. 
+
+Now enter: 
+
+\footnotesize
+\begin{verbatim}
+status client
+\end{verbatim}
+\normalsize
+
+and you should get something like: 
+
+\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
+
+In this case, the client is named {\bf rufus-fd} your name will be different,
+but the line beginning with {\bf rufus-fd Version ...} is printed by your File
+daemon, so we are now sure it is up and running. 
+
+Finally do the same for your Storage daemon with: 
+
+\footnotesize
+\begin{verbatim}
+status storage
+\end{verbatim}
+\normalsize
+
+and you should get: 
+
+\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
+
+You will notice that the default Storage daemon device is named {\bf File} and
+that it will use device {\bf /tmp}, which is not currently open. 
+
+Now, let's actually run a job with: 
+
+\footnotesize
+\begin{verbatim}
+run
+\end{verbatim}
+\normalsize
+
+you should get the following output: 
+
+\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
+
+Here, Bacula has listed the three different Jobs that you can run, and you
+should choose number {\bf 1} and type enter, at which point you will get: 
+
+\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
+
+At this point, take some time to look carefully at what is printed and
+understand it. It is asking you if it is OK to run a job named {\bf Client1}
+with FileSet {\bf Full Set} (we listed above) as an Incremental job on your
+Client (your client name will be different), and to use Storage {\bf File} and
+Pool {\bf Default}, and finally, it wants to run it now (the current time
+should be displayed by your console). 
+
+Here we have the choice to run ({\bf yes}), to modify one or more of the above
+parameters ({\bf mod}), or to not run the job ({\bf no}). Please enter {\bf
+yes}, at which point you should immediately get the command prompt (an
+asterisk). If you wait a few seconds, then enter the command {\bf messages}
+you will get back something like: 
+
+\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
+
+The first message, indicates that no previous Full backup was done, so Bacula
+is upgrading our Incremental job to a Full backup (this is normal). The second
+message indicates that the job started with JobId 1., and the third message
+tells us that Bacula cannot find any Volumes in the Pool for writing the
+output. This is normal because we have not yet created (labeled) any Volumes.
+Bacula indicates to you all the details of the volume it needs. 
+
+At this point, the job is BLOCKED waiting for a Volume. You can check this if
+you want by doing a {\bf status dir}. In order to continue, we must create a
+Volume that Bacula can write on. We do so with: 
+
+\footnotesize
+\begin{verbatim}
+label
+\end{verbatim}
+\normalsize
+
+and Bacula will print: 
+
+\footnotesize
+\begin{verbatim}
+The defined Storage resources are:
+     1: File
+Item 1 selected automatically.
+Enter new Volume name:
+\end{verbatim}
+\normalsize
+
+at which point, you should enter some name beginning with a letter and
+containing only letters and numbers (period, hyphen, and underscore) are also
+permitted. For example, enter {\bf TestVolume001}, and you should get back: 
+
+\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
+
+Finally, enter {\bf messages} and you should get something like: 
+
+\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
+
+If you don't see the output immediately, you can keep entering {\bf messages}
+until the job terminates, or you can enter, {\bf autodisplay on} and your
+messages will automatically be displayed as soon as they are ready. 
+
+If you do an {\bf ls -l} of your {\bf /tmp} directory, you will see that you
+have the following item: 
+
+\footnotesize
+\begin{verbatim}
+-rw-r-----    1 kern     kern     39072153 Apr 28 14:30 TestVolume001
+\end{verbatim}
+\normalsize
+
+This is the file Volume that you just wrote and it contains all the data of
+the job just run. If you run additional jobs, they will be appended to this
+Volume unless you specify otherwise. 
+
+You might ask yourself if you have to label all the Volumes that Bacula is
+going to use. The answer for disk Volumes, like the one we used, is no. It is
+possible to have Bacula automatically label volumes. For tape Volumes, you
+will most likely have to label each of the Volumes you want to use. 
+
+If you would like to stop here, you can simply enter {\bf quit} in the Console
+program, and you can stop Bacula with {\bf ./bacula stop}. To clean up, simply
+delete the file {\bf /tmp/TestVolume001}, and you should also re-initialize
+your database using: 
+
+\footnotesize
+\begin{verbatim}
+./drop_bacula_tables
+./make_bacula_tables
+\end{verbatim}
+\normalsize
+
+Please note that this will erase all information about the previous jobs that
+have run, and that you might want to do it now while testing but that normally
+you will not want to re-initialize your database. 
+
+If you would like to try restoring the files that you just backed up, read the
+following section. 
+\label{restoring}
+
+\section{Restoring Your Files}
+\index[general]{Files!Restoring Your }
+\index[general]{Restoring Your Files }
+
+If you have run the default configuration and the save of the Bacula source
+code as demonstrated above, you can restore the backed up files in the Console
+program by entering: 
+
+\footnotesize
+\begin{verbatim}
+restore all
+\end{verbatim}
+\normalsize
+
+where you will get: 
+
+\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
+
+As you can see, there are a number of options, but for the current
+demonstration, please enter {\bf 5} to do a restore of the last backup you
+did, and you will get the following output: 
+
+\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
+
+where I have truncated the listing on the right side to make it more readable.
+As you can see by starting at the top of the listing, Bacula knows what client
+you have, and since there was only one, it selected it automatically, likewise
+for the FileSet. Then Bacula produced a listing containing all the jobs that
+form the current backup, in this case, there is only one, and the Storage
+daemon was also automatically chosen. Bacula then took all the files that were
+in Job number 1 and entered them into a {\bf directory tree} (a sort of in
+memory representation of your filesystem). At this point, you can use the {\bf
+cd} and {\bf ls} ro {\bf dir} commands to walk up and down the directory tree
+and view what files will be restored. For example, if I enter {\bf cd
+/home/kern/bacula/bacula-1.30} and then enter {\bf dir} I will get a listing
+of all the files in the Bacula source directory. On your system, the path will
+be somewhat different. For more information on this, please refer to the 
+\ilink{Restore Command Chapter}{RestoreChapter} of this manual for
+more details. 
+
+To exit this mode, simply enter: 
+
+\footnotesize
+\begin{verbatim}
+done
+\end{verbatim}
+\normalsize
+
+and you will get the following output: 
+
+\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
+Backup Client:  rufus-fd
+Restore Client: rufus-fd
+Storage:        File
+JobId:          *None*
+When:           2005-04-28 14:53:54
+OK to run? (yes/mod/no):
+\end{verbatim}
+\normalsize
+
+If you answer {\bf yes} your files will be restored to {\bf
+/tmp/bacula-restores}. If you want to restore the files to their original
+locations, you must use the {\bf mod} option and explicitly set {\bf Where:}
+to nothing (or to /). We recommend you go ahead and answer {\bf yes} and after
+a brief moment, enter {\bf messages}, at which point you should get a listing
+of all the files that were restored as well as a summary of the job that looks
+similar to this: 
+
+\footnotesize
+\begin{verbatim}
+28-Apr-2005 14:56 rufus-dir: Bacula 2.1.8 (08May07): 08-May-2007 14:56:06
+Build OS:               i686-pc-linux-gnu suse 10.2
+JobId:                  2
+Job:                    RestoreFiles.2007-05-08_14.56.06
+Restore Client:         rufus-fd
+Start time:             08-May-2007 14:56
+End time:               08-May-2007 14:56
+Files Restored:         1,444
+Bytes Restored:         38,816,381
+Rate:                   9704.1 KB/s
+FD Errors:              0
+FD termination status:  OK
+SD termination status:  OK
+Termination:            Restore OK
+08-May-2007 14:56 rufus-dir: Begin pruning Jobs.
+08-May-2007 14:56 rufus-dir: No Jobs found to prune.
+08-May-2007 14:56 rufus-dir: Begin pruning Files.
+08-May-2007 14:56 rufus-dir: No Files found to prune.
+08-May-2007 14:56 rufus-dir: End auto prune.
+\end{verbatim}
+\normalsize
+
+After exiting the Console program, you can examine the files in {\bf
+/tmp/bacula-restores}, which will contain a small directory tree with all the
+files. Be sure to clean up at the end with: 
+
+\footnotesize
+\begin{verbatim}
+rm -rf /tmp/bacula-restore
+\end{verbatim}
+\normalsize
+
+\section{Quitting the Console Program}
+\index[general]{Program!Quitting the Console }
+\index[general]{Quitting the Console Program }
+
+Simply enter the command {\bf quit}. 
+\label{SecondClient}
+
+\section{Adding a Second Client}
+\index[general]{Client!Adding a Second }
+\index[general]{Adding a Second Client }
+
+If you have gotten the example shown above to work on your system, you may be
+ready to add a second Client (File daemon). That is you have a second machine
+that you would like backed up. The only part you need installed on the other
+machine is the binary {\bf bacula-fd} (or {\bf bacula-fd.exe} for Windows) and
+its configuration file {\bf bacula-fd.conf}. You can start with the same {\bf
+bacula-fd.conf} file that you are currently using and make one minor
+modification to it to create the conf file for your second client. Change the
+File daemon name from whatever was configured, {\bf rufus-fd} in the example
+above, but your system will have a different name. The best is to change it to
+the name of your second machine. For example: 
+
+\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
+
+would become: 
+
+\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
+
+where I show just a portion of the file and have changed {\bf rufus-fd} to
+{\bf matou-fd}. The names you use are your choice. For the moment, I recommend
+you change nothing else. Later, you will want to change the password. 
+
+Now you should install that change on your second machine. Then you need to
+make some additions to your Director's configuration file to define the new
+File daemon or Client. Starting from our original example which should be
+installed on your system, you should add the following lines (essentially
+copies of the existing data but with the names changed) to your Director's
+configuration file {\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
+
+Then make sure that the Address parameter in the Storage resource is set to
+the fully qualified domain name and not to something like "localhost". The
+address specified is sent to the File daemon (client) and it must be a fully
+qualified domain name. If you pass something like "localhost" it will not
+resolve correctly and will result in a time out when the File daemon fails to
+connect to the Storage daemon. 
+
+That is all that is necessary. I copied the existing resource to create a
+second Job (Matou) to backup the second client (matou-fd). It has the name
+{\bf Matou}, the Client is named {\bf matou-fd}, and the bootstrap file name
+is changed, but everything else is the same. This means that Matou will be
+backed up on the same schedule using the same set of tapes. You may want to
+change that later, but for now, let's keep it simple. 
+
+The second change was to add a new Client resource that defines {\bf matou-fd}
+and has the correct address {\bf matou}, but in real life, you may need a
+fully qualified domain name or an IP address. I also kept the password the
+same (shown as xxxxx for the example). 
+
+At this point, if you stop Bacula and restart it, and start the Client on the
+other machine, everything will be ready, and the prompts that you saw above
+will now include the second machine. 
+
+To make this a real production installation, you will possibly want to use
+different Pool, or a different schedule. It is up to you to customize. In any
+case, you should change the password in both the Director's file and the
+Client's file for additional security. 
+
+For some important tips on changing names and passwords, and a diagram of what
+names and passwords must match, please see 
+\ilink{Authorization Errors}{AuthorizationErrors} in the FAQ chapter
+of this manual. 
+
+\section{When The Tape Fills}
+\label{FullTape}
+\index[general]{Fills!When The Tape }
+\index[general]{When The Tape Fills }
+
+If you have scheduled your job, typically nightly, there will come a time when
+the tape fills up and {\bf Bacula} cannot continue. In this case, Bacula will
+send you a message similar to the following: 
+
+\footnotesize
+\begin{verbatim}
+rufus-sd: block.c:337 === Write error errno=28: ERR=No space left
+          on device
+\end{verbatim}
+\normalsize
+
+This indicates that Bacula got a write error because the tape is full. Bacula
+will then search the Pool specified for your Job looking for an appendable
+volume. In the best of all cases, you will have properly set your Retention
+Periods and you will have all your tapes marked to be Recycled, and {\bf
+Bacula} will automatically recycle the tapes in your pool requesting and
+overwriting old Volumes. For more information on recycling, please see the 
+\ilink{Recycling chapter}{RecyclingChapter} of this manual. If you
+find that your Volumes were not properly recycled (usually because of a
+configuration error), please see the 
+\ilink{Manually Recycling Volumes}{manualrecycling} section of
+the Recycling chapter. 
+
+If like me, you have a very large set of Volumes and you label them with the
+date the Volume was first writing, or you have not set up your Retention
+periods, Bacula will not find a tape in the pool, and it will send you a
+message similar to the following: 
+
+\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
+
+Until you create a new Volume, this message will be repeated an hour later,
+then two hours later, and so on doubling the interval each time up to a
+maximum interval of one day. 
+
+The obvious question at this point is: What do I do now? 
+
+The answer is simple: first, using the Console program, close the tape drive
+using the {\bf unmount} command. If you only have a single drive, it will be
+automatically selected, otherwise, make sure you release the one specified on
+the message (in this case {\bf STD-10000}). 
+
+Next, you remove the tape from the drive and insert a new blank tape. Note, on
+some older tape drives, you may need to write an end of file mark ({\bf mt \
+-f \ /dev/nst0 \ weof}) to prevent the drive from running away when Bacula
+attempts to read the label. 
+
+Finally, you use the {\bf label} command in the Console to write a label to
+the new Volume. The {\bf label} command will contact the Storage daemon to
+write the software label, if it is successful, it will add the new Volume to
+the Pool, then issue a {\bf mount} command to the Storage daemon. See the
+previous sections of this chapter for more details on labeling tapes. 
+
+The result is that Bacula will continue the previous Job writing the backup to
+the new Volume. 
+
+If you have a Pool of volumes and Bacula is cycling through them, instead of
+the above message "Cannot find any appendable volumes.", Bacula may ask you
+to mount a specific volume. In that case, you should attempt to do just that.
+If you do not have the volume any more (for any of a number of reasons), you
+can simply mount another volume from the same Pool, providing it is
+appendable, and Bacula will use it. You can use the {\bf list volumes} command
+in the console program to determine which volumes are appendable and which are
+not. 
+
+If like me, you have your Volume retention periods set correctly, but you have
+no more free Volumes, you can relabel and reuse a Volume as follows: 
+
+\begin{itemize}
+\item Do a {\bf list volumes} in the Console and select the oldest  Volume for
+   relabeling.  
+\item If you have setup your Retention periods correctly, the  Volume should
+   have VolStatus {\bf Purged}.  
+\item If the VolStatus is not set to Purged, you will need to purge  the
+   database of Jobs that are written on that Volume. Do so  by using the command
+   {\bf purge jobs volume} in the Console.  If you have multiple Pools, you will
+be prompted for the  Pool then enter the VolumeName (or MediaId) when
+requested.  
+\item Then simply use the {\bf relabel} command to relabel the  Volume. 
+   \end{itemize}
+
+To manually relabel the Volume use the following additional steps: 
+
+\begin{itemize}
+\item To delete the Volume from the catalog use the {\bf delete volume} 
+   command in the Console and select the VolumeName (or MediaId) to be  deleted. 
+
+\item Use the {\bf unmount} command in the Console to unmount the  old tape.  
+\item Physically relabel the old Volume that you deleted so that it  can be
+   reused.  
+\item Insert the old Volume in the tape drive.  
+\item From a command line do: {\bf mt \ -f \ /dev/st0 \ rewind} and  {\bf mt \
+   -f \ /dev/st0 \ weof}, where you need to use the proper  tape drive name for
+   your system in place of {\bf /dev/st0}.  
+\item Use the {\bf label} command in the Console to write a new  Bacula label
+   on your tape.  
+\item Use the {\bf mount} command in the Console if it is not automatically 
+   done, so that Bacula starts using your newly labeled tape. 
+   \end{itemize}
+
+\section{Other Useful Console Commands}
+\index[general]{Commands!Other Useful Console }
+\index[general]{Other Useful Console Commands }
+
+\begin{description}
+
+\item [status dir]
+   \index[console]{status dir }
+   Print a status of all running jobs and jobs  scheduled in the next 24 hours.  
+
+\item [status]
+   \index[console]{status }
+   The console program will prompt you to select  a daemon type, then will
+request the daemon's status.  
+
+\item [status jobid=nn]
+   \index[console]{status jobid }
+   Print a status of JobId nn if it is running.  The Storage daemon is contacted
+and requested to print a current  status of the job as well.  
+
+\item [list pools]
+   \index[console]{list pools }
+   List the pools defined in the Catalog (normally  only Default is used).  
+
+\item [list media]
+   \index[console]{list media }
+   Lists all the media defined in the Catalog.  
+
+\item [list jobs]
+   \index[console]{list jobs }
+   Lists all jobs in the Catalog that have run.  
+
+\item [list jobid=nn]
+   \index[console]{list jobid }
+   Lists JobId nn from the Catalog.  
+
+\item [list jobtotals]
+   \index[console]{list jobtotals }
+   Lists totals for all jobs in the Catalog.  
+
+\item [list files jobid=nn]
+   \index[console]{list files jobid }
+   List the files that were saved for JobId nn.  
+
+\item [list jobmedia]
+   \index[console]{list jobmedia }
+   List the media information for each Job run.  
+
+\item [messages]
+   \index[console]{messages }
+   Prints any messages that have been directed to the console.  
+
+\item [unmount storage=storage-name]
+   \index[console]{unmount storage }
+   Unmounts the drive associated with the storage  device with the name {\bf
+storage-name} if the drive is not currently being  used. This command is used
+if you wish Bacula to free the drive so  that you can use it to label a tape. 
+
+
+\item [mount storage=storage-name]
+   \index[sd]{mount storage }
+   Causes the drive associated with the  storage device to be mounted again. When
+Bacula reaches the end of a volume and requests you to mount a  new volume,
+you must issue this command after you have placed the  new volume in the
+drive. In effect, it is the signal needed by  Bacula to know to start reading
+or writing the new volume.  
+
+\item [quit]
+   \index[sd]{quit }
+   Exit or quit the console program. 
+\end{description}
+
+Most of the commands given above, with the exception of {\bf list}, will
+prompt you for the necessary arguments if you simply enter the command name. 
+
+\section{Debug Daemon Output}
+\index[general]{Debug Daemon Output }
+\index[general]{Output!Debug Daemon }
+
+If you want debug output from the daemons as they are running, start the
+daemons from the install directory as follows: 
+
+\footnotesize
+\begin{verbatim}
+./bacula start -d100
+\end{verbatim}
+\normalsize
+
+This can be particularly helpful if your daemons do not start correctly,
+because direct daemon output to the console is normally directed to the
+NULL device, but with the debug level greater than zero, the output
+will be sent to the starting terminal.
+
+To stop the three daemons, enter the following from the install directory: 
+
+\footnotesize
+\begin{verbatim}
+./bacula stop
+\end{verbatim}
+\normalsize
+
+The execution of {\bf bacula stop} may complain about pids not found. This is
+OK, especially if one of the daemons has died, which is very rare. 
+
+To do a full system save, each File daemon must be running as root so that it
+will have permission to access all the files. None of the other daemons
+require root privileges. However, the Storage daemon must be able to open the
+tape drives. On many systems, only root can access the tape drives. Either run
+the Storage daemon as root, or change the permissions on the tape devices to
+permit non-root access. MySQL and PostgreSQL can be installed and run with any
+userid; root privilege is not necessary. 
+
+\section{Patience When Starting Daemons or Mounting Blank Tapes}
+
+When you start the Bacula daemons, the Storage daemon attempts to open all
+defined storage devices and verify the currently mounted Volume (if
+configured). Until all the storage devices are verified, the Storage daemon
+will not accept connections from the Console program. If a tape was previously
+used, it will be rewound, and on some devices this can take several minutes.
+As a consequence, you may need to have a bit of patience when first contacting
+the Storage daemon after starting the daemons. If you can see your tape drive,
+once the lights stop flashing, the drive will be ready to be used. 
+
+The same considerations apply if you have just mounted a blank tape in a drive
+such as an HP DLT. It can take a minute or two before the drive properly
+recognizes that the tape is blank. If you attempt to {\bf mount} the tape with
+the Console program during this recognition period, it is quite possible that
+you will hang your SCSI driver (at least on my Red Hat Linux system). As a
+consequence, you are again urged to have patience when inserting blank tapes.
+Let the device settle down before attempting to access it. 
+
+\section{Difficulties Connecting from the FD to the SD}
+\index[general]{Difficulties Connecting from the FD to the SD}
+\index[general]{SD!Difficulties Connecting from the FD to the SD}
+
+If you are having difficulties getting one or more of your File daemons to
+connect to the Storage daemon, it is most likely because you have not used a
+fully qualified domain name on the {\bf Address} directive in the
+Director's Storage resource. That is the resolver on the File daemon's machine
+(not on the Director's) must be able to resolve the name you supply into an IP
+address. An example of an address that is guaranteed not to work: {\bf
+localhost}. An example that may work: {\bf megalon}. An example that is more
+likely to work: {\bf magalon.mydomain.com}. On Win32 if you don't have a good
+resolver (often true on older Win98 systems), you might try using an IP
+address in place of a name. 
+
+If your address is correct, then make sure that no other program is using the
+port 9103 on the Storage daemon's machine. The Bacula port numbers are
+authorized by IANA, and should not be used by other programs, but apparently
+some HP printers do use these port numbers. A {\bf netstat -a} on the Storage
+daemon's machine can determine who is using the 9103 port (used for FD to SD
+communications in Bacula). 
+
+\section{Daemon Command Line Options}
+\index[general]{Daemon Command Line Options }
+\index[general]{Options!Daemon Command Line }
+
+Each of the three daemons (Director, File, Storage) accepts a small set of
+options on the command line. In general, each of the daemons as well as the
+Console program accepts the following options: 
+
+\begin{description}
+
+\item [-c \lt{}file\gt{}]
+   \index[sd]{-c \lt{}file\gt{} }
+   Define the file to use as a  configuration file. The default is the daemon
+   name followed  by {\bf .conf} i.e. {\bf bacula-dir.conf} for the Director, 
+   {\bf bacula-fd.conf} for the File daemon, and {\bf bacula-sd}  for the Storage
+   daemon.  
+
+\item [-d nn]
+   \index[sd]{-d nn }
+   Set the debug level to {\bf nn}. Higher levels  of debug cause more
+   information to be displayed on STDOUT concerning  what the daemon is doing.  
+
+\item [-f]
+   Run the daemon in the foreground. This option is  needed to run the daemon
+   under the debugger.  
+
+\item [-g <group>]
+   Run the daemon under this group.  This must be a group name, not a GID.
+
+\item [-s]
+   Do not trap signals. This option is needed to run  the daemon under the
+   debugger.  
+
+\item [-t]
+   Read the configuration file and print any error messages,  then immediately
+   exit. Useful for syntax testing of  new configuration files.  
+
+\item [-u <user>]
+   Run the daemon as this user.  This must be a user name, not a UID.
+
+\item [-v]
+   Be more verbose or more complete in printing error  and informational
+   messages. Recommended.  
+
+\item [-?]
+   Print the version and list of options. 
+
+\end{description}
+
+
+\section{Creating a Pool}
+\label{Pool}
+\index[general]{Pool!Creating a }
+\index[general]{Creating a Pool }
+
+Creating the Pool is automatically done when {\bf Bacula} starts, so if you
+understand Pools, you can skip to the next section. 
+
+When you run a job, one of the things that Bacula must know is what Volumes to
+use to backup the FileSet. Instead of specifying a Volume (tape) directly, you
+specify which Pool of Volumes you want Bacula to consult when it wants a tape
+for writing backups. Bacula will select the first available Volume from the
+Pool that is appropriate for the Storage device you have specified for the Job
+being run. When a volume has filled up with data, {\bf Bacula} will change its
+VolStatus from {\bf Append} to {\bf Full}, and then {\bf Bacula} will use the
+next volume and so on. If no appendable Volume exists in the Pool, the
+Director will attempt to recycle an old Volume, if there are still no
+appendable Volumes available, {\bf Bacula} will send a message requesting the
+operator to create an appropriate Volume. 
+
+{\bf Bacula} keeps track of the Pool name, the volumes contained in the Pool,
+and a number of attributes of each of those Volumes. 
+
+When Bacula starts, it ensures that all Pool resource definitions have been
+recorded in the catalog. You can verify this by entering: 
+
+\footnotesize
+\begin{verbatim}
+list pools
+\end{verbatim}
+\normalsize
+
+to the console program, which should print something like the following: 
+
+\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
+
+If you attempt to create the same Pool name a second time, {\bf Bacula} will
+print: 
+
+\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{Labeling Your Volumes}
+\index[general]{Volumes!Labeling Your }
+\index[general]{Labeling Your Volumes }
+
+Bacula requires that each Volume contains a software label. There are several
+strategies for labeling volumes. The one I use is to label them as they are
+needed by {\bf Bacula} using the console program. That is when Bacula needs a
+new Volume, and it does not find one in the catalog, it will send me an email
+message requesting that I add Volumes to the Pool. I then use the {\bf label}
+command in the Console program to label a new Volume and to define it in the
+Pool database, after which Bacula will begin writing on the new Volume.
+Alternatively, I can use the Console {\bf relabel} command to relabel a Volume
+that is no longer used providing it has VolStatus {\bf Purged}. 
+
+Another strategy is to label a set of volumes at the start, then use them as
+{\bf Bacula} requests them. This is most often done if you are cycling through
+a set of tapes, for example using an autochanger. For more details on
+recycling, please see the 
+\ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of
+this manual. 
+
+If you run a Bacula job, and you have no labeled tapes in the Pool, Bacula
+will inform you, and you can create them "on-the-fly" so to speak. In my
+case, I label my tapes with the date, for example: {\bf DLT-18April02}. See
+below for the details of using the {\bf label} command. 
+
+\section{Labeling Volumes with the Console Program}
+\index[general]{Labeling Volumes with the Console Program }
+\index[general]{Program!Labeling Volumes with the Console }
+
+Labeling volumes is normally done by using the console program. 
+
+\begin{enumerate}
+\item ./bconsole  
+\item label 
+   \end{enumerate}
+
+If Bacula complains that you cannot label the tape because it is already
+labeled, simply {\bf unmount} the tape using the {\bf unmount} command in the
+console, then physically mount a blank tape and re-issue the {\bf label}
+command. 
+
+Since the physical storage media is different for each device, the {\bf label}
+command will provide you with a list of the defined Storage resources such as
+the following: 
+
+\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
+
+At this point, you should have a blank tape in the drive corresponding to the
+Storage resource that you select. 
+
+It will then ask you for the Volume name. 
+
+\footnotesize
+\begin{verbatim}
+Enter new Volume name:
+\end{verbatim}
+\normalsize
+
+If Bacula complains: 
+
+\footnotesize
+\begin{verbatim}
+Media record for Volume xxxx already exists.
+\end{verbatim}
+\normalsize
+
+It means that the volume name {\bf xxxx} that you entered already exists in
+the Media database. You can list all the defined Media (Volumes) with the {\bf
+list media} command. Note, the LastWritten column has been truncated for
+proper printing. 
+
+\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
+
+Once Bacula has verified that the volume does not already exist, it will
+prompt you for the name of the Pool in which the Volume (tape) is to be
+created.  If there is only one Pool (Default), it will be automatically
+selected.
+
+If the tape is successfully labeled, a Volume record will also be created in
+the Pool. That is the Volume name and all its other attributes will appear
+when you list the Pool. In addition, that Volume will be available for backup
+if the MediaType matches what is requested by the Storage daemon. 
+
+When you labeled the tape, you answered very few questions about it --
+principally the Volume name, and perhaps the Slot. However, a Volume record in
+the catalog database (internally known as a Media record) contains quite a few
+attributes. Most of these attributes will be filled in from the default values
+that were defined in the Pool (i.e. the Pool holds most of the default
+attributes used when creating a Volume). 
+
+It is also possible to add media to the pool without physically labeling the
+Volumes. This can be done with the {\bf add} command. For more information,
+please see the 
+\ilink{Console Chapter}{_ConsoleChapter} of this manual. 
diff --git a/docs/manuals/en/main/verify.tex b/docs/manuals/en/main/verify.tex
new file mode 100644 (file)
index 0000000..1726158
--- /dev/null
@@ -0,0 +1,376 @@
+%%
+%%
+
+% 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
diff --git a/docs/manuals/en/main/win32.tex b/docs/manuals/en/main/win32.tex
new file mode 100644 (file)
index 0000000..ccad87d
--- /dev/null
@@ -0,0 +1,865 @@
+%%
+%%
+
+\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{\idir 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{\idir win32-welcome.eps}  
+
+\item Next you will be asked to select the installation type. 
+
+\addcontentsline{lof}{figure}{Win32 Installation Type}
+\includegraphics{\idir 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{\idir 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{\idir win32-config.eps}  
+\item While the various files are being loaded, you will see the following
+   dialog:
+
+   \addcontentsline{lof}{figure}{Win32 Install Progress}
+   \includegraphics{\idir win32-installing.eps}  
+
+
+\item Finally, the finish dialog will appear:  
+
+   \addcontentsline{lof}{figure}{Win32 Client Setup Completed}
+   \includegraphics{\idir win32-finish.eps}  
+
+\ 
+\end{itemize}
+
+That should complete the installation process. When the Bacula File Server is
+ready to serve files, an icon \includegraphics{\idir idle.eps} representing a
+cassette (or tape) will appear in the system tray
+\includegraphics{\idir tray-icon.eps}; right click on it and a menu will appear.\\
+\includegraphics{\idir 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{\idir running.eps},
+and if there is an error, the holes in the cassette icon will change to red
+\includegraphics{\idir 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). 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{\idir 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{\idir view-only.eps} 
+
+You should see something like this: 
+
+\includegraphics{\idir 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{\idir 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{\idir 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://technet.microsoft.com/en-us/sysinternals/bb897541.aspx}}.