From: Kern Sibbald Date: Tue, 3 Nov 2009 16:42:44 +0000 (+0100) Subject: Create Bacula Main Reference manual X-Git-Tag: Release-5.0.0~52 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=0669187751084c57ee7353bcf80e678521195b84;p=bacula%2Fdocs Create Bacula Main Reference manual --- diff --git a/docs/.gitignore b/docs/.gitignore index 79ffb058..b4da1985 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -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/ diff --git a/docs/Makefile.in b/docs/Makefile.in index 65f24bdf..a81a6a14 100644 --- a/docs/Makefile.in +++ b/docs/Makefile.in @@ -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 \ diff --git a/docs/autoconf/configure.in b/docs/autoconf/configure.in index 50f71f96..331edd29 100644 --- a/docs/autoconf/configure.in +++ b/docs/autoconf/configure.in @@ -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 diff --git a/docs/configure b/docs/configure index 6d7443f7..09322b38 100755 --- a/docs/configure +++ b/docs/configure @@ -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 index 00000000..57bc8caf --- /dev/null +++ b/docs/manuals/en/main/Makefile.in @@ -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.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 index 00000000..ccdf2368 --- /dev/null +++ b/docs/manuals/en/main/STYLE @@ -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 index 00000000..7d6e14fe --- /dev/null +++ b/docs/manuals/en/main/ansi-labels.tex @@ -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 index 00000000..98563c77 --- /dev/null +++ b/docs/manuals/en/main/autochangerres.tex @@ -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 index 00000000..d3fa47e0 --- /dev/null +++ b/docs/manuals/en/main/autochangers.tex @@ -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 :. 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 index 00000000..8c18e201 --- /dev/null +++ b/docs/manuals/en/main/bimagemgr.bix @@ -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 index 00000000..882aaf03 --- /dev/null +++ b/docs/manuals/en/main/bootstrap.tex @@ -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 index 00000000..42df829d --- /dev/null +++ b/docs/manuals/en/main/bugs.tex @@ -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 index 00000000..da243b0c --- /dev/null +++ b/docs/manuals/en/main/catmaintenance.tex @@ -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 </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 /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 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/en/main/check_tex.pl @@ -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 () { + $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 index 00000000..07521566 --- /dev/null +++ b/docs/manuals/en/main/configure.tex @@ -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 index 00000000..563c81ad --- /dev/null +++ b/docs/manuals/en/main/consoleconf.tex @@ -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 index 00000000..d6aa6a5c --- /dev/null +++ b/docs/manuals/en/main/coverpage.tex @@ -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 index 00000000..ee0d225c --- /dev/null +++ b/docs/manuals/en/main/critical.tex @@ -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 index 00000000..9b259cef --- /dev/null +++ b/docs/manuals/en/main/dataencryption.tex @@ -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 index 00000000..c448d311 --- /dev/null +++ b/docs/manuals/en/main/dirdconf.tex @@ -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} + = on + = at + = 1st | 2nd | 3rd | 4th | 5th | first | + second | third | fourth | fifth + = sun | mon | tue | wed | thu | fri | sat | + sunday | monday | tuesday | wednesday | + thursday | friday | saturday + = w00 | w01 | ... w52 | w53 + = jan | feb | mar | apr | may | jun | jul | + aug | sep | oct | nov | dec | january | + february | ... | december + = daily + = weekly + = monthly + = hourly + = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 + = | +<12hour> = 0 | 1 | 2 | ... 12 + = 0 | 1 | 2 | ... 23 + = 0 | 1 | 2 | ... 59 + = 1 | 2 | ... 31 +