From: Kern Sibbald Date: Wed, 12 Dec 2007 20:43:21 +0000 (+0000) Subject: Remove old manual X-Git-Tag: Release-3.0.0~2158 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=a717851ab6e7285e5f149edeb2e8c5a6ba958211;p=bacula%2Fdocs Remove old manual --- diff --git a/docs/manual/Makefile.in b/docs/manual/Makefile.in deleted file mode 100644 index 6648329a..00000000 --- a/docs/manual/Makefile.in +++ /dev/null @@ -1,149 +0,0 @@ -# -# -# Makefile for LaTeX -# -# To build everything do -# make tex -# make web -# make html -# make dvipdf -# -# or simply -# -# make -# -# for rapid development do: -# make tex -# make show -# -# -# If you are having problems getting "make" to work, debugging it is -# easier if can see the output from latex, which is normally redirected -# to /dev/null. To see it, do the following: -# -# cd docs/manual -# make tex -# latex bacula.tex -# -# typically the latex command will stop indicating the error (e.g. a -# missing \ in front of a _ or a missing { or ] ... -# -# The following characters must be preceded by a backslash -# to be entered as printable characters: -# -# # $ % & ~ _ ^ \ { } -# - -IMAGES=../images - -first_rule: bacula - -bacula: 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 baculai-dir.tex baculai-fd.tex baculai-sd.tex \ - baculai-console.tex baculai-general.tex - latex -interaction=batchmode bacula.tex - makeindex bacula.idx -o bacula.ind 2>/dev/null - makeindex bacula.ddx -o bacula.dnd >/dev/null 2>/dev/null - makeindex bacula.fdx -o bacula.fnd >/dev/null 2>/dev/null - makeindex bacula.sdx -o bacula.snd >/dev/null 2>/dev/null - makeindex bacula.cdx -o bacula.cnd >/dev/null 2>/dev/null - latex -interaction=batchmode bacula.tex - latex -interaction=batchmode bimagemgr.tex - -pdf: - @echo "Making pdfm" - @cp -fp ${IMAGES}/hires/*.eps . - dvipdfm -p a4 bacula.dvi - dvipdfm -p a4 bimagemgr.dvi - -dvipdf: - @echo "Making dvi to pdf" - @cp -fp ${IMAGES}/hires/*.eps . - dvipdf bacula.dvi bacula.pdf - dvipdf bimagemgr.dvi bimagemgr.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 bacula.html; \ - fi) - latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ - -init_file latex2html-init.pl bacula >tex.out 2>&1 - ./translate_images.pl --to_meaningful_names bacula.html - @echo "Done making html" - -web: - @echo "Making web" - @mkdir -p bacula - @cp -fp ${IMAGES}/*.eps . - @rm -f next.eps next.png prev.eps prev.png up.eps up.png - @cp -fp ${IMAGES}/*.eps *.txt bacula/ - @cp -fp ${IMAGES}/*.eps *.txt ${IMAGES}/*.png bacula/ - @rm -f bacula/xp-*.png - @rm -f bacula/next.eps bacula/next.png bacula/prev.eps bacula/prev.png bacula/up.eps bacula/up.png - @rm -rf bacula/*.html - latex2html -split 3 -local_icons -t "Bacula User's Guide" -long_titles 4 \ - -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent bacula >tex.out 2>&1 - ./translate_images.pl --to_meaningful_names bacula/Bacula_Users_Guide.html - -cp -f bacula/Bacula_Freque_Asked_Questi.html bacula/faq.html - @echo "Done making web" -show: - xdvi bacula - -texcheck: - ./check_tex.pl bacula.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 bacula/*.gif bacula/*.jpg bacula/*.eps - @rm -f bacula/*.aux bacula/*.cp bacula/*.fn bacula/*.ky bacula/*.log bacula/*.pg - @rm -f bacula/*.backup bacula/*.ilg bacula/*.lof bacula/*.lot - @rm -f bacula/*.cdx bacula/*.cnd bacula/*.ddx bacula/*.ddn bacula/*.fdx bacula/*.fnd bacula/*.ind bacula/*.sdx bacula/*.snd - @rm -f bacula/*.dnd bacula/*.old bacula/*.out - @rm -f bacula/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 baculai-dir.tex baculai-fd.tex baculai-sd.tex \ - baculai-console.tex baculai-general.tex images.tex - - -distclean: - @rm -f 1 2 3 *.tex~ - @rm -f *.gif *.jpg *.eps - @rm -f *.aux *.cp *.fn *.ky *.log *.pg - @rm -f *.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 images.pl labels.pl internals.pl - @rm -f baculai-dir.tex baculai-fd.tex baculai-sd.tex \ - baculai-console.tex baculai-general.tex images.tex diff --git a/docs/manual/STYLE b/docs/manual/STYLE deleted file mode 100644 index 6cd70564..00000000 --- a/docs/manual/STYLE +++ /dev/null @@ -1,76 +0,0 @@ -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/manual/ansi-labels.tex b/docs/manual/ansi-labels.tex deleted file mode 100644 index 7d6e14fe..00000000 --- a/docs/manual/ansi-labels.tex +++ /dev/null @@ -1,58 +0,0 @@ - -\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/manual/autochangerres.tex b/docs/manual/autochangerres.tex deleted file mode 100644 index 98563c77..00000000 --- a/docs/manual/autochangerres.tex +++ /dev/null @@ -1,107 +0,0 @@ -%% -\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/manual/autochangers.tex b/docs/manual/autochangers.tex deleted file mode 100644 index 154306c4..00000000 --- a/docs/manual/autochangers.tex +++ /dev/null @@ -1,981 +0,0 @@ -%% -%% - -\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. - -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. - -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. - -\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/manual/bimagemgr-chapter.tex b/docs/manual/bimagemgr-chapter.tex deleted file mode 100644 index 01157f84..00000000 --- a/docs/manual/bimagemgr-chapter.tex +++ /dev/null @@ -1,155 +0,0 @@ -%% -%% -%% The following characters must be preceded by a backslash -%% to be entered as printable characters: -%% -%% # $ % & ~ _ ^ \ { } -%% - -\section{bimagemgr} -\label{bimagemgr} -\index[general]{Bimagemgr } - -{\bf bimagemgr} is a utility for those who backup to disk volumes in order to -commit them to CDR disk, rather than tapes. It is a web based interface -written in Perl and is used to monitor when a volume file needs to be burned to -disk. It requires: - -\begin{itemize} -\item A web server running on the bacula server -\item A CD recorder installed and configured on the bacula server -\item The cdrtools package installed on the bacula server. -\item perl, perl-DBI module, and either DBD-MySQL DBD-SQLite or DBD-PostgreSQL modules - \end{itemize} - -DVD burning is not supported by {\bf bimagemgr} at this -time, but both are planned for future releases. - -\subsection{bimagemgr installation} -\index[general]{bimagemgr!Installation } -\index[general]{bimagemgr Installation } - -Installation from tarball: -% TODO: use itemized list for this? -1. Examine the Makefile and adjust it to your configuration if needed. -2. Edit config.pm to fit your configuration. -3. Do 'make install' as root. -4. Edit httpd.conf and change the Timeout value. The web server must not time -out and close the connection before the burn process is finished. The exact -value needed may vary depending upon your cd recorder speed and whether you are -burning on the bacula server on on another machine across your network. In my -case I set it to 1000 seconds. Restart httpd. -5. Make sure that cdrecord is setuid root. -% TODO: I am pretty sure cdrecord can be used without setuid root -% TODO: as long as devices are setup correctly - -Installation from rpm package: -% TODO: use itemized list for this? -1. Install the rpm package for your platform. -2. Edit /cgi-bin/config.pm to fit your configuration. -3. Edit httpd.conf and change the Timeout value. The web server must not time -out and close the connection before the burn process is finished. The exact -value needed may vary depending upon your cd recorder speed and whether you are -burning on the bacula server on on another machine across your network. In my -case I set it to 1000 seconds. Restart httpd. -4. Make sure that cdrecord is setuid root. - -For bacula systems less than 1.36: -% TODO: use itemized list for this? -1. Edit the configuration section of config.pm to fit your configuration. -2. Run /etc/bacula/create\_cdimage\_table.pl from a console on your bacula -server (as root) to add the CDImage table to your bacula database. - -Accessing the Volume files: -The Volume files by default have permissions 640 and can only be read by root. -The recommended approach to this is as follows (and only works if bimagemgr and -apache are running on the same host as bacula. - -For bacula-1.34 or 1.36 installed from tarball - -% TODO: use itemized list for this? -1. Create a new user group bacula and add the user apache to the group for -Red Hat or Mandrake systems. For SuSE systems add the user wwwrun to the -bacula group. -2. Change ownership of all of your Volume files to root.bacula -3. Edit the /etc/bacula/bacula startup script and set SD\_USER=root and -SD\_GROUP=bacula. Restart bacula. - -Note: step 3 should also be done in /etc/init.d/bacula-sd but released versions -of this file prior to 1.36 do not support it. In that case it would be necessary after -a reboot of the server to execute '/etc/bacula/bacula restart'. - -For bacula-1.38 installed from tarball - -% TODO: use itemized list for this? -1. Your configure statement should include: -% TODO: fix formatting here - --with-dir-user=bacula - --with-dir-group=bacula - --with-sd-user=bacula - --with-sd-group=disk - --with-fd-user=root - --with-fd-group=bacula -2. Add the user apache to the bacula group for Red Hat or Mandrake systems. -For SuSE systems add the user wwwrun to the bacula group. -3. Check/change ownership of all of your Volume files to root.bacula - -For bacula-1.36 or bacula-1.38 installed from rpm - -% TODO: use itemized list for this? -1. Add the user apache to the group bacula for Red Hat or Mandrake systems. -For SuSE systems add the user wwwrun to the bacula group. -2. Check/change ownership of all of your Volume files to root.bacula - -bimagemgr installed from rpm > 1.38.9 will add the web server user to the -bacula group in a post install script. Be sure to edit the configuration -information in config.pm after installation of rpm package. - -bimagemgr will now be able to read the Volume files but they are still not -world readable. - -If you are running bimagemgr on another host (not recommended) then you will -need to change the permissions on all of your backup volume files to 644 in -order to access them via nfs share or other means. This approach should only -be taken if you are sure of the security of your environment as it exposes -the backup Volume files to world read. - -\subsection{bimagemgr usage} -\index[general]{bimagemgr!Usage } -\index[general]{bimagemgr Usage } - -Calling the program in your web browser, e.g. {\tt -http://localhost/cgi-bin/bimagemgr.pl} will produce a display as shown below -% TODO: use tex to say figure number -in Figure 1. The program will query the bacula database and display all volume -files with the date last written and the date last burned to disk. If a volume -needs to be burned (last written is newer than last burn date) a "Burn" -button will be displayed in the rightmost column. - -\addcontentsline{lof}{figure}{Bacula CD Image Manager} -\includegraphics{./bimagemgr1.eps} \\Figure 1 -% TODO: use tex to say figure number - -Place a blank CDR disk in your recorder and click the "Burn" button. This will -cause a pop up window as shown in Figure 2 to display the burn progress. -% TODO: use tex to say figure number - -\addcontentsline{lof}{figure}{Bacula CD Image Burn Progress Window} -\includegraphics{./bimagemgr2.eps} \\Figure 2 -% TODO: use tex to say figure number - -When the burn finishes the pop up window will display the results of cdrecord -% TODO: use tex to say figure number -as shown in Figure 3. Close the pop up window and refresh the main window. The -last burn date will be updated and the "Burn" button for that volume will -disappear. Should you have a failed burn you can reset the last burn date of -that volume by clicking its "Reset" link. - -\addcontentsline{lof}{figure}{Bacula CD Image Burn Results} -\includegraphics{./bimagemgr3.eps} \\Figure 3 -% TODO: use tex to say figure number - -In the bottom row of the main display window are two more buttons labeled -"Burn Catalog" and "Blank CDRW". "Burn Catalog" will place a copy of -your bacula catalog on a disk. If you use CDRW disks rather than CDR then -"Blank CDRW" allows you to erase the disk before re-burning it. Regularly -committing your backup volume files and your catalog to disk with {\bf -bimagemgr} ensures that you can rebuild easily in the event of some disaster -on the bacula server itself. diff --git a/docs/manual/bimagemgr.tex b/docs/manual/bimagemgr.tex deleted file mode 100644 index 48ca14ed..00000000 --- a/docs/manual/bimagemgr.tex +++ /dev/null @@ -1,60 +0,0 @@ -%% -%% -%% The following characters must be preceded by a backslash -%% to be entered as printable characters: -%% -%% # $ % & ~ _ ^ \ { } -%% - -\documentclass[11pt,a4paper]{book} -\usepackage{html} -\usepackage{float} -\usepackage{graphicx} -\usepackage{bacula} -\usepackage{longtable} -\usepackage{makeidx} -\usepackage{index} -\usepackage{setspace} -\usepackage{hyperref} - -\makeindex -\newindex{general}{bix}{bid}{General Index} - -\sloppy - -\begin{document} -\sloppy - -\newfont{\bighead}{cmr17 at 36pt} -\parskip 10pt -\parindent 0pt - - -\title{\includegraphics{./bacula-logo.eps} \\ \bigskip - \begin{center} - \large{It comes in the night and sucks - the essence from your computers. } - \end{center} -} -\author{Kern Sibbald} -\date{\vspace{1.0in}\today \\ - This manual documents Bacula version \input{version} \\ - ~\vspace{0.2in}\\ - Copyright \copyright 1999-2007, Free Software Foundation Europe e.V. - \\ - ~\vspace{0.2in}\\ - Permission is granted to copy, distribute and/or modify this document under the terms of the \\ - GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; \\ - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. \\ - A copy of the license is included in the section entitled "GNU Free Documentation License". -} - -\maketitle - -\clearpage - -\markboth{Bacula Manual}{} -\include{bimagemgr-chapter} -\include{fdl} - -\end{document} diff --git a/docs/manual/bootstrap.tex b/docs/manual/bootstrap.tex deleted file mode 100644 index b69cdfbf..00000000 --- a/docs/manual/bootstrap.tex +++ /dev/null @@ -1,418 +0,0 @@ -%% -%% - -\chapter{The Bootstrap File} -\label{BootstrapChapter} -\index[general]{File!Bootstrap } -\index[general]{Bootstrap File } - -The information in this chapter is provided so that you may either create your -own bootstrap files, or so that you can edit a bootstrap file produced by {\bf -Bacula}. However, normally the bootstrap file will be automatically created -for you during the -\ilink{restore\_command}{_ConsoleChapter} command in the Console program, or -by using a -\ilink{ Write Bootstrap}{writebootstrap} record in your Backup -Jobs, and thus you will never need to know the details of this file. - -The {\bf bootstrap} file contains ASCII information that permits precise -specification of what files should be restored, what volume they are on, -and where they are on the volume. It is a relatively compact -form of specifying the information, is human readable, and can be edited with -any text editor. - -\section{Bootstrap File Format} -\index[general]{Format!Bootstrap} -\index[general]{Bootstrap File Format } - -The general format of a {\bf bootstrap} file is: - -{\bf \lt{}keyword\gt{}= \lt{}value\gt{}} - -Where each {\bf keyword} and the {\bf value} specify which files to restore. -More precisely the {\bf keyword} and their {\bf values} serve to limit which -files will be restored and thus act as a filter. The absence of a keyword -means that all records will be accepted. - -Blank lines and lines beginning with a pound sign (\#) in the bootstrap file -are ignored. - -There are keywords which permit filtering by Volume, Client, Job, FileIndex, -Session Id, Session Time, ... - -The more keywords that are specified, the more selective the specification of -which files to restore will be. In fact, each keyword is {\bf AND}ed with -other keywords that may be present. - -For example, - -\footnotesize -\begin{verbatim} -Volume = Test-001 -VolSessionId = 1 -VolSessionTime = 108927638 -\end{verbatim} -\normalsize - -directs the Storage daemon (or the {\bf bextract} program) to restore only -those files on Volume Test-001 {\bf AND} having VolumeSessionId equal to one -{\bf AND} having VolumeSession time equal to 108927638. - -The full set of permitted keywords presented in the order in which they are -matched against the Volume records are: - -\begin{description} - -\item [Volume] - \index[general]{Volume } - The value field specifies what Volume the following commands apply to. - Each Volume specification becomes the current Volume, to which all the - following commands apply until a new current Volume (if any) is - specified. If the Volume name contains spaces, it should be enclosed in - quotes. At lease one Volume specification is required. - -\item [Count] - \index[general]{Count} - The value is the total number of files that will be restored for this Volume. - This allows the Storage daemon to know when to stop reading the Volume. - This value is optional. - -\item [VolFile] - \index[general]{VolFile} - The value is a file number, a list of file numbers, or a range of file - numbers to match on the current Volume. The file number represents the - physical file on the Volume where the data is stored. For a tape - volume, this record is used to position to the correct starting file, - and once the tape is past the last specified file, reading will stop. - -\item [VolBlock] - \index[general]{VolBlock} - The value is a block number, a list of block numbers, or a range of - block numbers to match on the current Volume. The block number - represents the physical block within the file on the Volume where the - data is stored. - - -\item [VolSessionTime] - \index[general]{VolSessionTime } - The value specifies a Volume Session Time to be matched from the current - volume. - -\item [VolSessionId] - \index[general]{VolSessionId } - The value specifies a VolSessionId, a list of volume session ids, or a - range of volume session ids to be matched from the current Volume. Each - VolSessionId and VolSessionTime pair corresponds to a unique Job that is - backed up on the Volume. - -\item [JobId] - \index[general]{JobId } - The value specifies a JobId, list of JobIds, or range of JobIds to be - selected from the current Volume. Note, the JobId may not be unique if you - have multiple Directors, or if you have reinitialized your database. The - JobId filter works only if you do not run multiple simultaneous jobs. - This value is optional and not used by Bacula to restore files. - -\item [Job] - \index[general]{Job } - The value specifies a Job name or list of Job names to be matched on the - current Volume. The Job corresponds to a unique VolSessionId and - VolSessionTime pair. However, the Job is perhaps a bit more readable by - humans. Standard regular expressions (wildcards) may be used to match Job - names. The Job filter works only if you do not run multiple simultaneous - jobs. - This value is optional and not used by Bacula to restore files. - -\item [Client] - \index[general]{Client } - The value specifies a Client name or list of Clients to will be matched on - the current Volume. Standard regular expressions (wildcards) may be used to - match Client names. The Client filter works only if you do not run multiple - simultaneous jobs. - This value is optional and not used by Bacula to restore files. - -\item [FileIndex] - \index[general]{FileIndex } - The value specifies a FileIndex, list of FileIndexes, or range of FileIndexes - to be selected from the current Volume. Each file (data) stored on a Volume - within a Session has a unique FileIndex. For each Session, the first file - written is assigned FileIndex equal to one and incremented for each file - backed up. - - This for a given Volume, the triple VolSessionId, VolSessionTime, and - FileIndex uniquely identifies a file stored on the Volume. Multiple copies of - the same file may be stored on the same Volume, but for each file, the triple - VolSessionId, VolSessionTime, and FileIndex will be unique. This triple is - stored in the Catalog database for each file. - - To restore a particular file, this value (or a range of FileIndexes) is - required. - -\item [Slot] - \index[general]{Slot } - The value specifies the autochanger slot. There may be only a single {\bf - Slot} specification for each Volume. - -\item [Stream] - \index[general]{Stream } - The value specifies a Stream, a list of Streams, or a range of Streams to be - selected from the current Volume. Unless you really know what you are doing - (the internals of {\bf Bacula}), you should avoid this specification. - This value is optional and not used by Bacula to restore files. - -\item [*JobType] - \index[general]{*JobType } - Not yet implemented. - -\item [*JobLevel] - \index[general]{*JobLevel } - Not yet implemented. -\end{description} - -The {\bf Volume} record is a bit special in that it must be the first record. -The other keyword records may appear in any order and any number following a -Volume record. - -Multiple Volume records may be specified in the same bootstrap file, but each -one starts a new set of filter criteria for the Volume. - -In processing the bootstrap file within the current Volume, each filter -specified by a keyword is {\bf AND}ed with the next. Thus, - -\footnotesize -\begin{verbatim} -Volume = Test-01 -Client = "My machine" -FileIndex = 1 -\end{verbatim} -\normalsize - -will match records on Volume {\bf Test-01} {\bf AND} Client records for {\bf -My machine} {\bf AND} FileIndex equal to {\bf one}. - -Multiple occurrences of the same record are {\bf OR}ed together. Thus, - -\footnotesize -\begin{verbatim} -Volume = Test-01 -Client = "My machine" -Client = "Backup machine" -FileIndex = 1 -\end{verbatim} -\normalsize - -will match records on Volume {\bf Test-01} {\bf AND} (Client records for {\bf -My machine} {\bf OR} {\bf Backup machine}) {\bf AND} FileIndex equal to {\bf -one}. - -For integer values, you may supply a range or a list, and for all other values -except Volumes, you may specify a list. A list is equivalent to multiple -records of the same keyword. For example, - -\footnotesize -\begin{verbatim} -Volume = Test-01 -Client = "My machine", "Backup machine" -FileIndex = 1-20, 35 -\end{verbatim} -\normalsize - -will match records on Volume {\bf Test-01} {\bf AND} {\bf (}Client records for -{\bf My machine} {\bf OR} {\bf Backup machine}{\bf )} {\bf AND} {\bf -(}FileIndex 1 {\bf OR} 2 {\bf OR} 3 ... {\bf OR} 20 {\bf OR} 35{\bf )}. - -As previously mentioned above, there may be multiple Volume records in the -same bootstrap file. Each new Volume definition begins a new set of filter -conditions that apply to that Volume and will be {\bf OR}ed with any other -Volume definitions. - -As an example, suppose we query for the current set of tapes to restore all -files on Client {\bf Rufus} using the {\bf query} command in the console -program: - -\footnotesize -\begin{verbatim} -Using default Catalog name=MySQL DB=bacula -*query -Available queries: - 1: List Job totals: - 2: List where a file is saved: - 3: List where the most recent copies of a file are saved: - 4: List total files/bytes by Job: - 5: List total files/bytes by Volume: - 6: List last 10 Full Backups for a Client: - 7: List Volumes used by selected JobId: - 8: List Volumes to Restore All Files: -Choose a query (1-8): 8 -Enter Client Name: Rufus -+-------+------------------+------------+-----------+----------+------------+ -| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | -+-------+------------------+------------+-----------+----------+------------+ -| 154 | 2002-05-30 12:08 | test-02 | 0 | 1 | 1022753312 | -| 202 | 2002-06-15 10:16 | test-02 | 0 | 2 | 1024128917 | -| 203 | 2002-06-15 11:12 | test-02 | 3 | 1 | 1024132350 | -| 204 | 2002-06-18 08:11 | test-02 | 4 | 1 | 1024380678 | -+-------+------------------+------------+-----------+----------+------------+ -\end{verbatim} -\normalsize - -The output shows us that there are four Jobs that must be restored. The first -one is a Full backup, and the following three are all Incremental backups. - -The following bootstrap file will restore those files: - -\footnotesize -\begin{verbatim} -Volume=test-02 -VolSessionId=1 -VolSessionTime=1022753312 -Volume=test-02 -VolSessionId=2 -VolSessionTime=1024128917 -Volume=test-02 -VolSessionId=1 -VolSessionTime=1024132350 -Volume=test-02 -VolSessionId=1 -VolSessionTime=1024380678 -\end{verbatim} -\normalsize - -As a final example, assume that the initial Full save spanned two Volumes. The -output from {\bf query} might look like: - -\footnotesize -\begin{verbatim} -+-------+------------------+------------+-----------+----------+------------+ -| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | -+-------+------------------+------------+-----------+----------+------------+ -| 242 | 2002-06-25 16:50 | File0003 | 0 | 1 | 1025016612 | -| 242 | 2002-06-25 16:50 | File0004 | 0 | 1 | 1025016612 | -| 243 | 2002-06-25 16:52 | File0005 | 0 | 2 | 1025016612 | -| 246 | 2002-06-25 19:19 | File0006 | 0 | 2 | 1025025494 | -+-------+------------------+------------+-----------+----------+------------+ -\end{verbatim} -\normalsize - -and the following bootstrap file would restore those files: - -\footnotesize -\begin{verbatim} -Volume=File0003 -VolSessionId=1 -VolSessionTime=1025016612 -Volume=File0004 -VolSessionId=1 -VolSessionTime=1025016612 -Volume=File0005 -VolSessionId=2 -VolSessionTime=1025016612 -Volume=File0006 -VolSessionId=2 -VolSessionTime=1025025494 -\end{verbatim} -\normalsize - -\section{Automatic Generation of Bootstrap Files} -\index[general]{Files!Automatic Generation of Bootstrap } -\index[general]{Automatic Generation of Bootstrap Files } - -One thing that is probably worth knowing: the bootstrap files that are -generated automatically at the end of the job are not as optimized as those -generated by the restore command. This is because during Incremental and -Differential jobs, the records pertaining to the files written for the -Job are appended to the end of the bootstrap file. -As consequence, all the files saved to an Incremental or Differential job will be -restored first by the Full save, then by any Incremental or Differential -saves. - -When the bootstrap file is generated for the restore command, only one copy -(the most recent) of each file is restored. - -So if you have spare cycles on your machine, you could optimize the bootstrap -files by doing the following: - -\footnotesize -\begin{verbatim} - ./bconsole - restore client=xxx select all - done - no - quit - Backup bootstrap file. -\end{verbatim} -\normalsize - -The above will not work if you have multiple FileSets because that will be an -extra prompt. However, the {\bf restore client=xxx select all} builds the -in-memory tree, selecting everything and creates the bootstrap file. - -The {\bf no} answers the {\bf Do you want to run this (yes/mod/no)} question. - -\label{bscanBootstrap} -\section{Bootstrap for bscan} -\index[general]{bscan} -\index[general]{bscan!bootstrap} -\index[general]{bscan bootstrap} -If you have a very large number of Volumes to scan with {\bf bscan}, -you may exceed the command line limit (511 characters). I that case, -you can create a simple bootstrap file that consists of only the -volume names. An example might be: - -\footnotesize -\begin{verbatim} -Volume="Vol001" -Volume="Vol002" -Volume="Vol003" -Volume="Vol004" -Volume="Vol005" -\end{verbatim} -\normalsize - - -\section{A Final Bootstrap Example} -\index[general]{Bootstrap Example} -\index[general]{Example!Bootstrap} - -If you want to extract or copy a single Job, you can do it by selecting by -JobId (code not tested) or better yet, if you know the VolSessionTime and the -VolSessionId (printed on Job report and in Catalog), specifying this is by far -the best. Using the VolSessionTime and VolSessionId is the way Bacula does -restores. A bsr file might look like the following: - -\footnotesize -\begin{verbatim} -Volume="Vol001" -VolSessionId=10 -VolSessionTime=1080847820 -\end{verbatim} -\normalsize - -If you know how many files are backed up (on the job report), you can -enormously speed up the selection by adding (let's assume there are 157 -files): - -\footnotesize -\begin{verbatim} -FileIndex=1-157 -Count=157 -\end{verbatim} -\normalsize - -Finally, if you know the File number where the Job starts, you can also cause -bcopy to forward space to the right file without reading every record: - -\footnotesize -\begin{verbatim} -VolFile=20 -\end{verbatim} -\normalsize - -There is nothing magic or complicated about a BSR file. Parsing it and -properly applying it within Bacula *is* magic, but you don't need to worry -about that. - -If you want to see a *real* bsr file, simply fire up the {\bf restore} command -in the console program, select something, then answer no when it prompts to -run the job. Then look at the file {\bf restore.bsr} in your working -directory. diff --git a/docs/manual/bugs.tex b/docs/manual/bugs.tex deleted file mode 100644 index 42df829d..00000000 --- a/docs/manual/bugs.tex +++ /dev/null @@ -1,21 +0,0 @@ -%% -%% - -\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/manual/catmaintenance.tex b/docs/manual/catmaintenance.tex deleted file mode 100644 index eeb36b8b..00000000 --- a/docs/manual/catmaintenance.tex +++ /dev/null @@ -1,762 +0,0 @@ -%% -%% - -\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[dir]{File Retention } - The File Retention record defines the length of time that Bacula will keep -File records in the Catalog database. When this time period expires, and if -{\bf AutoPrune} is set to {\bf yes}, Bacula will prune (remove) File records -that are older than the specified File Retention period. The pruning will -occur at the end of a backup Job for the given Client. Note that the Client -database record contains a copy of the File and Job retention periods, but -Bacula uses the current values found in the Director's Client resource to do -the pruning. - -Since File records in the database account for probably 80 percent of the -size of the database, you should carefully determine exactly what File -Retention period you need. Once the File records have been removed from -the database, you will no longer be able to restore individual files -in a Job. However, with Bacula version 1.37 and later, as long as the -Job record still exists, you will be able to restore all files in the -job. - -Retention periods are specified in seconds, but as a convenience, there are -a number of modifiers that permit easy specification in terms of minutes, -hours, days, weeks, months, quarters, or years on the record. See the -\ilink{ Configuration chapter}{Time} of this manual for additional details -of modifier specification. - -The default File retention period is 60 days. - -\item [Job Retention = \lt{}time-period-specification\gt{}] - \index[dir]{Job Retention } - The Job Retention record defines the length of time that {\bf Bacula} -will keep Job records in the Catalog database. When this time period -expires, and if {\bf AutoPrune} is set to {\bf yes} Bacula will prune -(remove) Job records that are older than the specified Job Retention -period. Note, if a Job record is selected for pruning, all associated File -and JobMedia records will also be pruned regardless of the File Retention -period set. As a consequence, you normally will set the File retention -period to be less than the Job retention period. - -As mentioned above, once the File records are removed from the database, -you will no longer be able to restore individual files from the Job. -However, as long as the Job record remains in the database, you will be -able to restore all the files backuped for the Job (on version 1.37 and -later). As a consequence, it is generally a good idea to retain the Job -records much longer than the File records. - -The retention period is specified in seconds, but as a convenience, there -are a number of modifiers that permit easy specification in terms of -minutes, hours, days, weeks, months, quarters, or years. See the \ilink{ -Configuration chapter}{Time} of this manual for additional details of -modifier specification. - -The default Job Retention period is 180 days. - -\item [AutoPrune = \lt{}yes/no\gt{}] - \index[dir]{AutoPrune } - If AutoPrune is set to {\bf yes} (default), Bacula will automatically apply -the File retention period and the Job retention period for the Client at the -end of the Job. - -If you turn this off by setting it to {\bf no}, your Catalog will grow each -time you run a Job. -\end{description} - -\label{CompactingMySQL} -\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} -mysql bacula -CREATE INDEX file_jobid_idx on File (JobId); -CREATE INDEX file_jfp_idx on File (Job, FilenameId, PathId); -\end{verbatim} -\normalsize - - - -\label{CompactingPostgres} -\section{Compacting Your PostgreSQL Database} -\index[general]{Database!Compacting Your PostgreSQL } -\index[general]{Compacting Your PostgreSQL Database } - -Over time, as noted above, your database will tend to grow. I've noticed that -even though Bacula regularly prunes files, PostgreSQL has a {\bf VACUUM} -command that will compact your database for you. Alternatively you may want to -use the {\bf vacuumdb} command, which can be run from a cron job. - -All database programs have some means of writing the database out in ASCII -format and then reloading it. Doing so will re-create the database from -scratch producing a compacted result, so below, we show you how you can do -this for PostgreSQL. - -For a {\bf PostgreSQL} database, you could write the Bacula database as an -ASCII file (bacula.sql) then reload it by doing the following: - -\footnotesize -\begin{verbatim} -pg_dump -c bacula > bacula.sql -cat bacula.sql | psql bacula -rm -f bacula.sql -\end{verbatim} -\normalsize - -Depending on the size of your database, this will take more or less time and a -fair amount of disk space. For example, you can {\bf cd} to the location of -the Bacula database (typically /usr/local/pgsql/data or possible -/var/lib/pgsql/data) and check the size. - -There are certain PostgreSQL users who do not recommend the above -procedure. They have the following to say: -PostgreSQL does not -need to be dumped/restored to keep the database efficient. A normal -process of vacuuming will prevent the database from every getting too -large. If you want to fine-tweak the database storage, commands such -as VACUUM FULL, REINDEX, and CLUSTER exist specifically to keep you -from having to do a dump/restore. - -Finally, you might want to look at the PostgreSQL documentation on -this subject at -\elink{http://www.postgresql.org/docs/8.1/interactive/maintenance.html} -{http://www.postgresql.org/docs/8.1/interactive/maintenance.html}. - -\section{Compacting Your SQLite Database} -\index[general]{Compacting Your SQLite Database } -\index[general]{Database!Compacting Your SQLite } - -First please read the previous section that explains why it is necessary to -compress a database. SQLite version 2.8.4 and greater have the {\bf Vacuum} -command for compacting the database. - -\footnotesize -\begin{verbatim} -cd {\bf working-directory} -echo 'vacuum;' | sqlite bacula.db -\end{verbatim} -\normalsize - -As an alternative, you can use the following commands, adapted to your system: - - -\footnotesize -\begin{verbatim} -cd {\bf working-directory} -echo '.dump' | sqlite bacula.db > bacula.sql -rm -f bacula.db -sqlite bacula.db < bacula.sql -rm -f bacula.sql -\end{verbatim} -\normalsize - -Where {\bf working-directory} is the directory that you specified in the -Director's configuration file. Note, in the case of SQLite, it is necessary to -completely delete (rm) the old database before creating a new compressed -version. - -\section{Migrating from SQLite to MySQL} -\index[general]{MySQL!Migrating from SQLite to } -\index[general]{Migrating from SQLite to MySQL } - -You may begin using Bacula with SQLite then later find that you want to switch -to MySQL for any of a number of reasons: SQLite tends to use more disk than -MySQL; when the database is corrupted it is often more catastrophic than -with MySQL or PostgreSQL. -Several users have succeeded in converting from SQLite to MySQL by -exporting the MySQL data and then processing it with Perl scripts -prior to putting it into MySQL. This is, however, not a simple -process. - -\label{BackingUpBacula} -\section{Backing Up Your Bacula Database} -\index[general]{Backing Up Your Bacula Database } -\index[general]{Database!Backing Up Your Bacula } - -If ever the machine on which your Bacula database crashes, and you need to -restore from backup tapes, one of your first priorities will probably be to -recover the database. Although Bacula will happily backup your catalog -database if it is specified in the FileSet, this is not a very good way to do -it, because the database will be saved while Bacula is modifying it. Thus the -database may be in an instable state. Worse yet, you will backup the database -before all the Bacula updates have been applied. - -To resolve these problems, you need to backup the database after all the backup -jobs have been run. In addition, you will want to make a copy while Bacula is -not modifying it. To do so, you can use two scripts provided in the release -{\bf make\_catalog\_backup} and {\bf delete\_catalog\_backup}. These files -will be automatically generated along with all the other Bacula scripts. The -first script will make an ASCII copy of your Bacula database into {\bf -bacula.sql} in the working directory you specified in your configuration, and -the second will delete the {\bf bacula.sql} file. - -The basic sequence of events to make this work correctly is as follows: - -\begin{itemize} -\item Run all your nightly backups -\item After running your nightly backups, run a Catalog backup Job -\item The Catalog backup job must be scheduled after your last nightly backup - -\item You use {\bf RunBeforeJob} to create the ASCII backup file and {\bf - RunAfterJob} to clean up -\end{itemize} - -Assuming that you start all your nightly backup jobs at 1:05 am (and that they -run one after another), you can do the catalog backup with the following -additional Director configuration statements: - -\footnotesize -\begin{verbatim} -# Backup the catalog database (after the nightly save) -Job { - Name = "BackupCatalog" - Type = Backup - Client=rufus-fd - FileSet="Catalog" - Schedule = "WeeklyCycleAfterBackup" - Storage = DLTDrive - Messages = Standard - Pool = Default - # WARNING!!! Passing the password via the command line is insecure. - # see comments in make_catalog_backup for details. - RunBeforeJob = "/home/kern/bacula/bin/make_catalog_backup" - RunAfterJob = "/home/kern/bacula/bin/delete_catalog_backup" - Write Bootstrap = "/home/kern/bacula/working/BackupCatalog.bsr" -} -# This schedule does the catalog. It starts after the WeeklyCycle -Schedule { - Name = "WeeklyCycleAfterBackup - Run = Level=Full sun-sat at 1:10 -} -# This is the backup of the catalog -FileSet { - Name = "Catalog" - Include { - Options { - signature=MD5 - } - File = \lt{}working_directory\gt{}/bacula.sql - } -} -\end{verbatim} -\normalsize - -Be sure to write a bootstrap file as in the above example. However, it is preferable -to write or copy the bootstrap file to another computer. It will allow -you to quickly recover the database backup should that be necessary. If -you do not have a bootstrap file, it is still possible to recover your -database backup, but it will be more work and take longer. - - -\label{BackingUpBaculaSecurityConsiderations} -\section{Security considerations} -\index[general]{Backing Up Your Bacula Database - Security Considerations } -\index[general]{Database!Backing Up Your Bacula Database - Security Considerations } - -We provide make\_catalog\_backup as an example of what can be used to backup -your Bacula database. We expect you to take security precautions relevant -to your situation. make\_catalog\_backup is designed to take a password on -the command line. This is fine on machines with only trusted users. It is -not acceptable on machines without trusted users. Most database systems -provide a alternative method, which does not place the password on the -command line. - -The make\_catalog\_backup script contains some warnings about how to use it. Please -read those tips. - -To help you get started, we know PostgreSQL has a password file, -\elink{ -.pgpass}{http://www.postgresql.org/docs/8.2/static/libpq-pgpass.html}, and -we know MySQL has -\elink{ .my.cnf}{http://dev.mysql.com/doc/refman/4.1/en/password-security.html}. - -Only you can decide what is appropriate for your situation. We have provided -you with a starting point. We hope it helps. - - -\label{BackingUPOtherDBs} -\section{Backing Up Third Party Databases} -\index[general]{Backing Up Third Party Databases } -\index[general]{Databases!Backing Up Third Party } - -If you are running a database in production mode on your machine, Bacula will -happily backup the files, but if the database is in use while Bacula is -reading it, you may back it up in an unstable state. - -The best solution is to shutdown your database before backing it up, or use -some tool specific to your database to make a valid live copy perhaps by -dumping the database in ASCII format. I am not a database expert, so I cannot -provide you advice on how to do this, but if you are unsure about how to -backup your database, you might try visiting the Backup Central site, which -has been renamed Storage Mountain (www.backupcentral.com). In particular, -their -\elink{ Free Backup and Recovery -Software}{http://www.backupcentral.com/toc-free-backup-software.html} page has -links to scripts that show you how to shutdown and backup most major -databases. -\label{Size} - -\section{Database Size} -\index[general]{Size!Database } -\index[general]{Database Size } - -As mentioned above, if you do not do automatic pruning, your Catalog will grow -each time you run a Job. Normally, you should decide how long you want File -records to be maintained in the Catalog and set the {\bf File Retention} -period to that time. Then you can either wait and see how big your Catalog -gets or make a calculation assuming approximately 154 bytes for each File -saved and knowing the number of Files that are saved during each backup and -the number of Clients you backup. - -For example, suppose you do a backup of two systems, each with 100,000 files. -Suppose further that you do a Full backup weekly and an Incremental every day, -and that the Incremental backup typically saves 4,000 files. The size of your -database after a month can roughly be calculated as: - -\footnotesize -\begin{verbatim} - Size = 154 * No. Systems * (100,000 * 4 + 10,000 * 26) -\end{verbatim} -\normalsize - -where we have assumed four weeks in a month and 26 incremental backups per month. -This would give the following: - -\footnotesize -\begin{verbatim} - Size = 154 * 2 * (100,000 * 4 + 10,000 * 26) -or - Size = 308 * (400,000 + 260,000) -or - Size = 203,280,000 bytes -\end{verbatim} -\normalsize - -So for the above two systems, we should expect to have a database size of -approximately 200 Megabytes. Of course, this will vary according to how many -files are actually backed up. - -Below are some statistics for a MySQL database containing Job records for five -Clients beginning September 2001 through May 2002 (8.5 months) and File -records for the last 80 days. (Older File records have been pruned). For these -systems, only the user files and system files that change are backed up. The -core part of the system is assumed to be easily reloaded from the Red Hat rpms. - - -In the list below, the files (corresponding to Bacula Tables) with the -extension .MYD contain the data records whereas files with the extension .MYI -contain indexes. - -You will note that the File records (containing the file attributes) make up -the large bulk of the number of records as well as the space used (459 Mega -Bytes including the indexes). As a consequence, the most important Retention -period will be the {\bf File Retention} period. A quick calculation shows that -for each File that is saved, the database grows by approximately 150 bytes. - -\footnotesize -\begin{verbatim} - Size in - Bytes Records File - ============ ========= =========== - 168 5 Client.MYD - 3,072 Client.MYI - 344,394,684 3,080,191 File.MYD - 115,280,896 File.MYI - 2,590,316 106,902 Filename.MYD - 3,026,944 Filename.MYI - 184 4 FileSet.MYD - 2,048 FileSet.MYI - 49,062 1,326 JobMedia.MYD - 30,720 JobMedia.MYI - 141,752 1,378 Job.MYD - 13,312 Job.MYI - 1,004 11 Media.MYD - 3,072 Media.MYI - 1,299,512 22,233 Path.MYD - 581,632 Path.MYI - 36 1 Pool.MYD - 3,072 Pool.MYI - 5 1 Version.MYD - 1,024 Version.MYI -\end{verbatim} -\normalsize - -This database has a total size of approximately 450 Megabytes. - -If we were using SQLite, the determination of the total database size would be -much easier since it is a single file, but we would have less insight to the -size of the individual tables as we have in this case. - -Note, SQLite databases may be as much as 50\% larger than MySQL databases due -to the fact that all data is stored as ASCII strings. That is even binary -integers are stored as ASCII strings, and this seems to increase the space -needed. diff --git a/docs/manual/check_tex.pl b/docs/manual/check_tex.pl deleted file mode 100755 index e12d51be..00000000 --- a/docs/manual/check_tex.pl +++ /dev/null @@ -1,152 +0,0 @@ -#!/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/manual/configure.tex b/docs/manual/configure.tex deleted file mode 100644 index e37773b9..00000000 --- a/docs/manual/configure.tex +++ /dev/null @@ -1,408 +0,0 @@ -%% -%% - -\chapter{Customizing the Configuration Files} -\label{ConfigureChapter} -\index[general]{Files!Customizing the Configuration } -\index[general]{Customizing the Configuration Files } - -When each of the Bacula programs starts, it reads a configuration file -specified on the command line or the default {\bf bacula-dir.conf}, {\bf -bacula-fd.conf}, {\bf bacula-sd.conf}, or {\bf console.conf} for the Director -daemon, the File daemon, the Storage daemon, and the Console program -respectively. - -Each service (Director, Client, Storage, Console) has its own configuration -file containing a set of Resource definitions. These resources are very -similar from one service to another, but may contain different directives -(records) depending on the service. For example, in the Director's resource -file, the {\bf Director} resource defines the name of the Director, a number -of global Director parameters and his password. In the File daemon -configuration file, the {\bf Director} resource specifies which Directors are -permitted to use the File daemon. - -Before running Bacula for the first time, you must customize the configuration -files for each daemon. Default configuration files will have been created by -the installation process, but you will need to modify them to correspond to -your system. An overall view of the resources can be seen in the following: - -\addcontentsline{lof}{figure}{Bacula Objects} -\includegraphics{./bacula-objects.eps} -\\ -(thanks to Aristides Maniatis for the above graphic) -\label{ResFormat} - -\section{Character Sets} -\index[general]{Character Sets} -Bacula is designed to handle most character sets of the world, -US ASCII, German, French, Chinese, ... However, it does this by -encoding everything in UTF-8, and it expects all configuration files -(including those read on Win32 machines) to be in UTF-8 format. -UTF-8 is typically the default on Linux machines, but not on all -Unix machines, nor on Windows, so you must take some care to ensure -that your locale is set properly before starting Bacula. - -To ensure that Bacula configuration files can be correctly read including -foreign characters the {bf LANG} environment variable -must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The -exact syntax may vary a bit from OS to OS, and exactly how you define -it will also vary. On most newer Win32 machines, you can use {\bf notepad} -to edit the conf files, then choose output encoding UTF-8. - -Bacula assumes that all filenames are in UTF-8 format on Linux and -Unix machines. On Win32 they are in Unicode (UTF-16), and will -be automatically converted to UTF-8 format. - -\section{Resource Directive Format} -\index[general]{Resource Directive Format } -\index[general]{Format!Resource Directive } - -Although, you won't need to know the details of all the directives a basic -knowledge of Bacula resource directives is essential. Each directive contained -within the resource (within the braces) is composed of a keyword followed by -an equal sign (=) followed by one or more values. The keywords must be one of -the known Bacula resource record keywords, and it may be composed of upper or -lower case characters and spaces. - -Each resource definition MUST contain a Name directive, and may optionally -contain a Description directive. The Name directive is used to -uniquely identify the resource. The Description directive is (will be) used -during display of the Resource to provide easier human recognition. For -example: - -\footnotesize -\begin{verbatim} -Director { - Name = "MyDir" - Description = "Main Bacula Director" - WorkingDirectory = "$HOME/bacula/bin/working" -} -\end{verbatim} -\normalsize - -Defines the Director resource with the name "MyDir" and a working directory -\$HOME/bacula/bin/working. In general, if you want spaces in a name to the -right of the first equal sign (=), you must enclose that name within double -quotes. Otherwise quotes are not generally necessary because once defined, -quoted strings and unquoted strings are all equal. - -\label{Comments} -\subsection{Comments} -\index[general]{Comments} - -When reading the configuration file, blank lines are ignored and everything -after a hash sign (\#) until the end of the line is taken to be a comment. A -semicolon (;) is a logical end of line, and anything after the semicolon is -considered as the next statement. If a statement appears on a line by itself, -a semicolon is not necessary to terminate it, so generally in the examples in -this manual, you will not see many semicolons. -\label{Case1} - -\subsection{Upper and Lower Case and Spaces} -\index[general]{Spaces!Upper/Lower Case} -\index[general]{Upper and Lower Case and Spaces} - -Case (upper/lower) and spaces are totally ignored in the resource directive -keywords (the part before the equal sign). - -Within the keyword (i.e. before the equal sign), spaces are not significant. -Thus the keywords: {\bf name}, {\bf Name}, and {\bf N a m e} are all -identical. - -Spaces after the equal sign and before the first character of the value are -ignored. - -In general, spaces within a value are significant (not ignored), and if the -value is a name, you must enclose the name in double quotes for the spaces to -be accepted. Names may contain up to 127 characters. Currently, a name may -contain any ASCII character. Within a quoted string, any character following a -backslash (\textbackslash{}) is taken as itself (handy for inserting -backslashes and double quotes (")). - -Please note, however, that Bacula resource names as well as certain other -names (e.g. Volume names) must contain only letters (including ISO accented -letters), numbers, and a few special characters (space, underscore, ...). -All other characters and punctuation are invalid. - -\label{Includes} -\subsection{Including other Configuration Files} -\index[general]{Including other Configuration Files } -\index[general]{Files!Including other Configuration } -\index[general]{Using @ to include other files} -\index[general]{@{\bf filename}} - -If you wish to break your configuration file into smaller pieces, you can do -so by including other files using the syntax @{\bf filename} where {\bf -filename} is the full path and filename of another file. The @filename -specification can be given anywhere a primitive token would appear. - -\label{DataTypes} -\subsection{Recognized Primitive Data Types} -\index[general]{Types!Recognized Primitive Data } -\index[general]{Recognized Primitive Data Types } - -When parsing the resource directives, Bacula classifies the data according to -the types listed below. The first time you read this, it may appear a bit -overwhelming, but in reality, it is all pretty logical and straightforward. - -\begin{description} - -\item [name] - \index[fd]{name} - A keyword or name consisting of alphanumeric characters, including the -hyphen, underscore, and dollar characters. The first character of a {\bf -name} must be a letter. A name has a maximum length currently set to 127 -bytes. Typically keywords appear on the left side of an equal (i.e. they are -Bacula keywords -- i.e. Resource names or directive names). Keywords may not -be quoted. - -\item [name-string] - \index[fd]{name-string} - A name-string is similar to a name, except that the name may be quoted and -can thus contain additional characters including spaces. Name strings are -limited to 127 characters in length. Name strings are typically used on the -right side of an equal (i.e. they are values to be associated with a keyword). - - -\item [string] - \index[fd]{string} - A quoted string containing virtually any character including spaces, or a -non-quoted string. A string may be of any length. Strings are typically -values that correspond to filenames, directories, or system command names. A -backslash (\textbackslash{}) turns the next character into itself, so to -include a double quote in a string, you precede the double quote with a -backslash. Likewise to include a backslash. - -\item [directory] - \index[dir]{directory} - A directory is either a quoted or non-quoted string. A directory will be -passed to your standard shell for expansion when it is scanned. Thus -constructs such as {\bf \$HOME} are interpreted to be their correct values. - -\item [password] - \index[dir]{password} - This is a Bacula password and it is stored internally in MD5 hashed format. - -\item [integer] - \index[dir]{integer} - A 32 bit integer value. It may be positive or negative. - -\item [positive integer] - \index[dir]{positive integer } - A 32 bit positive integer value. - -\item [long integer] - \index[dir]{long integer} - A 64 bit integer value. Typically these are values such as bytes that can -exceed 4 billion and thus require a 64 bit value. - -\item [yes|no] - \index[dir]{yes or no } - Either a {\bf yes} or a {\bf no}. - -\label{Size1} -\item [size] -\index[dir]{size} -A size specified as bytes. Typically, this is a floating point scientific -input format followed by an optional modifier. The floating point input is -stored as a 64 bit integer value. If a modifier is present, it must -immediately follow the value with no intervening spaces. The following -modifiers are permitted: - -\begin{description} -\item [k] - 1,024 (kilobytes) - -\item [kb] - 1,000 (kilobytes) - -\item [m] - 1,048,576 (megabytes) - -\item [mb] - 1,000,000 (megabytes) - -\item [g] - 1,073,741,824 (gigabytes) - -\item [gb] - 1,000,000,000 (gigabytes) -\end{description} - -\label{Time} -\item [time] -\index[dir]{time} -A time or duration specified in seconds. The time is stored internally as -a 64 bit integer value, but it is specified in two parts: a number part and -a modifier part. The number can be an integer or a floating point number. -If it is entered in floating point notation, it will be rounded to the -nearest integer. The modifier is mandatory and follows the number part, -either with or without intervening spaces. The following modifiers are -permitted: - -\begin{description} - -\item [seconds] - \index[dir]{seconds} - seconds - -\item [minutes] - \index[dir]{minutes} - minutes (60 seconds) - -\item [hours] - \index[dir]{hours } - hours (3600 seconds) - -\item [days] - \index[dir]{days} - days (3600*24 seconds) - -\item [weeks] - \index[dir]{weeks} - weeks (3600*24*7 seconds) - -\item [months] - \index[dir]{months } - months (3600*24*30 seconds) - -\item [quarters] - \index[dir]{quarters } - quarters (3600*24*91 seconds) - -\item [years] - \index[dir]{years } - years (3600*24*365 seconds) -\end{description} - -Any abbreviation of these modifiers is also permitted (i.e. {\bf seconds} -may be specified as {\bf sec} or {\bf s}). A specification of {\bf m} will -be taken as months. - -The specification of a time may have as many number/modifier parts as you -wish. For example: - -\footnotesize -\begin{verbatim} -1 week 2 days 3 hours 10 mins -1 month 2 days 30 sec - -\end{verbatim} -\normalsize - -are valid date specifications. - -\end{description} - -\label{ResTypes} -\section{Resource Types} -\index[general]{Types!Resource } -\index[general]{Resource Types } - -The following table lists all current Bacula resource types. It shows what -resources must be defined for each service (daemon). The default configuration -files will already contain at least one example of each permitted resource, so -you need not worry about creating all these kinds of resources from scratch. - -\addcontentsline{lot}{table}{Resource Types} -\begin{longtable}{|l|l|l|l|l|} - \hline -\multicolumn{1}{|c| }{\bf Resource } & \multicolumn{1}{c| }{\bf Director } & -\multicolumn{1}{c| }{\bf Client } & \multicolumn{1}{c| }{\bf Storage } & -\multicolumn{1}{c| }{\bf Console } \\ - \hline -{Autochanger } & {No } & {No } & {Yes } & {No } \\ -\hline -{Catalog } & {Yes } & {No } & {No } & {No } \\ - \hline -{Client } & {Yes } & {Yes } & {No } & {No } \\ - \hline -{Console } & {Yes } & {No } & {No } & {Yes } \\ - \hline -{Device } & {No } & {No } & {Yes } & {No } \\ - \hline -{Director } & {Yes } & {Yes } & {Yes } & {Yes } \\ - \hline -{FileSet } & {Yes } & {No } & {No } & {No } \\ - \hline -{Job } & {Yes } & {No } & {No } & {No } \\ - \hline -{JobDefs } & {Yes } & {No } & {No } & {No } \\ - \hline -{Message } & {Yes } & {Yes } & {Yes } & {No } \\ - \hline -{Pool } & {Yes } & {No } & {No } & {No } \\ - \hline -{Schedule } & {Yes } & {No } & {No } & {No } \\ - \hline -{Storage } & {Yes } & {No } & {Yes } & {No } -\\ \hline - -\end{longtable} - -\section{Names, Passwords and Authorization} -\label{Names} -\index[general]{Authorization!Names Passwords and } -\index[general]{Names, Passwords and Authorization } -\index[general]{Passwords} - -In order for one daemon to contact another daemon, it must authorize itself -with a password. In most cases, the password corresponds to a particular name, -so both the name and the password must match to be authorized. Passwords are -plain text, any text. They are not generated by any special process; just -use random text. - -The default configuration files are automatically defined for correct -authorization with random passwords. If you add to or modify these files, you -will need to take care to keep them consistent. - -Here is sort of a picture of what names/passwords in which files/Resources -must match up: - -\includegraphics{./Conf-Diagram.eps} - -In the left column, you will find the Director, Storage, and Client resources, -with their names and passwords -- these are all in {\bf bacula-dir.conf}. In -the right column are where the corresponding values should be found in the -Console, Storage daemon (SD), and File daemon (FD) configuration files. - -Please note that the Address, {\bf fd-sd}, that appears in the Storage -resource of the Director, preceded with and asterisk in the above example, is -passed to the File daemon in symbolic form. The File daemon then resolves it -to an IP address. For this reason, you must use either an IP address or a -fully qualified name. A name such as {\bf localhost}, not being a fully -qualified name, will resolve in the File daemon to the localhost of the File -daemon, which is most likely not what is desired. The password used for the -File daemon to authorize with the Storage daemon is a temporary password -unique to each Job created by the daemons and is not specified in any .conf -file. - -\section{Detailed Information for each Daemon} -\index[general]{Detailed Information for each Daemon } -\index[general]{Daemon!Detailed Information for each } - -The details of each Resource and the directives permitted therein are -described in the following chapters. - -The following configuration files must be defined: - -\begin{itemize} -\item - \ilink{Console}{ConsoleConfChapter} -- to define the resources for - the Console program (user interface to the Director). It defines which -Directors are available so that you may interact with them. -\item - \ilink{Director}{DirectorChapter} -- to define the resources - necessary for the Director. You define all the Clients and Storage daemons -that you use in this configuration file. -\item - \ilink{Client}{FiledConfChapter} -- to define the resources for - each client to be backed up. That is, you will have a separate Client -resource file on each machine that runs a File daemon. -\item - \ilink{Storage}{StoredConfChapter} -- to define the resources to - be used by each Storage daemon. Normally, you will have a single Storage -daemon that controls your tape drive or tape drives. However, if you have -tape drives on several machines, you will have at least one Storage daemon -per machine. -\end{itemize} diff --git a/docs/manual/console.tex b/docs/manual/console.tex deleted file mode 100644 index 4bb6869e..00000000 --- a/docs/manual/console.tex +++ /dev/null @@ -1,1583 +0,0 @@ -%% -%% - -\chapter{Bacula Console} -\label{_ConsoleChapter} -\index[general]{Console!Bacula} -\index[general]{Bacula Console} -\index[console]{Console!Bacula} -\index[console]{Bacula Console} - -The {\bf Bacula Console} (sometimes called the User Agent) is a program that -allows the user or the System Administrator, to interact with the Bacula -Director daemon while the daemon is running. - -The current Bacula Console comes in two versions: a shell interface (TTY -style), and a GNOME GUI interface. Both permit the administrator or authorized -users to interact with Bacula. You can determine the status of a particular -job, examine the contents of the Catalog as well as perform certain tape -manipulations with the Console program. - -In addition, there is a bwx-console built with wxWidgets that allows a graphic -restore of files. As of version 1.34.1 it is in an early stage of development, -but it already is quite useful. Unfortunately, it has not been enhanced for -some time now. - -Since the Console program interacts with the Director through the network, your -Console and Director programs do not necessarily need to run on the same -machine. - -In fact, a certain minimal knowledge of the Console program is needed in order -for Bacula to be able to write on more than one tape, because when Bacula -requests a new tape, it waits until the user, via the Console program, -indicates that the new tape is mounted. - -\section{Console Configuration} -\index[general]{Console Configuration} -\index[general]{Configuration!Console} -\index[console]{Console Configuration} -\index[console]{Configuration!Console} - -When the Console starts, it reads a standard Bacula configuration file named -{\bf bconsole.conf} or {\bf bgnome-console.conf} in the case of the GNOME -Console version. This file allows default configuration of the Console, and at -the current time, the only Resource Record defined is the Director resource, -which gives the Console the name and address of the Director. For more -information on configuration of the Console program, please see the -\ilink{Console Configuration File}{ConsoleConfChapter} Chapter of -this document. - -\section{Running the Console Program} -\index[general]{Running the Console Program} -\index[general]{Program!Running the Console} -\index[console]{Running the Console Program} -\index[console]{Program!Running the Console} - -The console program can be run with the following options: -\footnotesize -\begin{verbatim} -Usage: bconsole [-s] [-c config_file] [-d debug_level] - -c set configuration file to file - -dnn set debug level to nn - -n no conio - -s no signals - -t test - read configuration and exit - -? print this message. -\end{verbatim} -\normalsize - - -After launching the Console program (bconsole), it will prompt you for the -next command with an asterisk (*). (Note, in the GNOME version, the prompt is -not present; you simply enter the commands you want in the command text box at -the bottom of the screen.) Generally, for all commands, you can simply enter -the command name and the Console program will prompt you for the necessary -arguments. Alternatively, in most cases, you may enter the command followed by -arguments. The general format is: - -\footnotesize -\begin{verbatim} - [=] [=] ... -\end{verbatim} -\normalsize - -where {\bf command} is one of the commands listed below; {\bf keyword} is one -of the keywords listed below (usually followed by an argument); and {\bf -argument} is the value. The command may be abbreviated to the shortest unique -form. If two commands have the same starting letters, the one that will be -selected is the one that appears first in the {\bf help} listing. If you want -the second command, simply spell out the full command. None of the keywords -following the command may be abbreviated. - -For example: - -\footnotesize -\begin{verbatim} -list files jobid=23 -\end{verbatim} -\normalsize - -will list all files saved for JobId 23. Or: - -\footnotesize -\begin{verbatim} -show pools -\end{verbatim} -\normalsize - -will display all the Pool resource records. - -The maximum command line length is limited to 511 characters, so if you -are scripting the console, you may need to take some care to limit the -line length. - -\section{Stopping the Console Program} -\index[general]{Program!Stopping the Console} -\index[general]{Stopping the Console Program} -\index[console]{Program!Stopping the Console} -\index[console]{Stopping the Console Program} - -Normally, you simply enter {\bf quit} or {\bf exit} and the Console program -will terminate. However, it waits until the Director acknowledges the command. -If the Director is already doing a lengthy command (e.g. prune), it may take -some time. If you want to immediately terminate the Console program, enter the -{\bf .quit} command. - -There is currently no way to interrupt a Console command once issued (i.e. -Ctrl-C does not work). However, if you are at a prompt that is asking you to -select one of several possibilities and you would like to abort the command, -you can enter a period ({\bf .}), and in most cases, you will either be -returned to the main command prompt or if appropriate the previous prompt (in -the case of nested prompts). In a few places such as where it is asking for a -Volume name, the period will be taken to be the Volume name. In that case, you -will most likely be able to cancel at the next prompt. - -\label{keywords} -\section{Alphabetic List of Console Keywords} -\index[general]{Keywords!Alphabetic List of Console} -\index[general]{Alphabetic List of Console Keywords} -\index[console]{Keywords!Alphabetic List of Console} -\index[console]{Alphabetic List of Console Keywords} -Unless otherwise specified, each of the following keywords -takes an argument, which is specified after the keyword following -an equal sign. For example: - -\begin{verbatim} -jobid=536 -\end{verbatim} - -Please note, this list is incomplete as it is currently in -the process of being created and is not currently totally in -alphabetic -order ... - -\begin{description} -\item [restart] - Permitted on the python command, and causes the Python - interpreter to be restarted. Takes no argument. -\item [all] - Permitted on the status and show commands to specify all components or - resources respectively. -\item [allfrompool] - Permitted on the update command to specify that all Volumes in the - pool (specified on the command line) should be updated. -\item [allfrompools] - Permitted on the update command to specify that all Volumes in all - pools should be updated. -\item [before] - Used in the restore command. -\item [bootstrap] - Used in the restore command. -\item [catalog] - Allowed in the use command to specify the catalog name - to be used. -\item [catalogs] - Used in the show command. Takes no arguments. -\item [client | fd] -\item [clients] - Used in the show, list, and llist commands. Takes no arguments. -\item [counters] - Used in the show command. Takes no arguments. -\item [current] - Used in the restore command. Takes no argument. -\item [days] - Used to define the number of days the "list nextvol" command - should consider when looking for jobs to be run. The days keyword - can also be used on the "status dir" command so that it will display - jobs scheduled for the number of days you want. -\item [devices] - Used in the show command. Takes no arguments. -\item [dir | director] -\item [directors] - Used in the show command. Takes no arguments. -\item [directory] - Used in the restore command. Its argument specifies the directory - to be restored. -\item [enabled] - This keyword can appear on the {\bf update volume} as well - as the {\bf update slots} commands, and can - allows one of the following arguments: yes, true, no, false, archived, - 0, 1, 2. Where 0 corresponds to no or false, 1 corresponds to yes or true, and - 2 corresponds to archived. Archived volumes will not be used, nor will - the Media record in the catalog be pruned. Volumes that are not enabled, - will not be used for backup or restore. -\item [done] - Used in the restore command. Takes no argument. -\item [file] - Used in the restore command. -\item [files] - Used in the list and llist commands. Takes no arguments. -\item [fileset] -\item [filesets] - Used in the show command. Takes no arguments. -\item [help] - Used in the show command. Takes no arguments. -\item [jobs] - Used in the show, list and llist commands. Takes no arguments. -\item [jobmedia] - Used in the list and llist commands. Takes no arguments. -\item [jobtotals] - Used in the list and llist commands. Takes no arguments. -\item [jobid] - The JobId is the numeric jobid that is printed in the Job - Report output. It is the index of the database record for the - given job. While it is unique for all the existing Job records - in the catalog database, the same JobId can be reused once a - Job is removed from the catalog. Probably you will refer - specific Jobs that ran using their numeric JobId. -\item [job | jobname] - The Job or Jobname keyword refers to the name you specified - in the Job resource, and hence it refers to any number of - Jobs that ran. It is typically useful if you want to list - all jobs of a particular name. -\item [level] -\item [listing] - Permitted on the estimate command. Takes no argument. -\item [limit] -\item [messages] - Used in the show command. Takes no arguments. -\item [media] - Used in the list and llist commands. Takes no arguments. -\item [nextvol | nextvolume] - Used in the list and llist commands. Takes no arguments. -\item [on] - Takes no keyword. -\item [off] - Takes no keyword. -\item [pool] -\item [pools] - Used in the show, list, and llist commands. Takes no arguments. -\item [select] - Used in the restore command. Takes no argument. -\item [storages] - Used in the show command. Takes no arguments. -\item [schedules] - Used in the show command. Takes no arguments. -\item [sd | store | storage] -\item [ujobid] - The ujobid is a unique job identification that is printed - in the Job Report output. At the current time, it consists - of the Job name (from the Name directive for the job) appended - with the date and time the job was run. This keyword is useful - if you want to completely identify the Job instance run. -\item [volume] -\item [volumes] - Used in the list and llist commands. Takes no arguments. -\item [where] - Used in the restore command. -\item [yes] - Used in the restore command. Takes no argument. -\end{description} - -\label{list} -\section{Alphabetic List of Console Commands} -\index[general]{Commands!Alphabetic List of Console} -\index[general]{Alphabetic List of Console Commands} -\index[console]{Commands!Alphabetic List of Console} -\index[console]{Alphabetic List of Console Commands} - -The following commands are currently implemented: - -\begin{description} -\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{} - jobid=\lt{}JobId\gt{}]} ] - \index[console]{add} - This command is used to add Volumes to an existing Pool. That is, - it creates the Volume name in the catalog and inserts into the Pool - in the catalog, but does not attempt to access the physical Volume. - Once - added, Bacula expects that Volume to exist and to be labeled. - This command is not normally used since Bacula will - automatically do the equivalent when Volumes are labeled. However, - there may be times when you have removed a Volume from the catalog - and want to later add it back. - - Normally, the {\bf label} command is used rather than this command - because the {\bf label} command labels the physical media (tape, disk, - DVD, ...) and does the equivalent of the {\bf add} command. The {\bf - add} command affects only the Catalog and not the physical media (data - on Volumes). The physical media must exist and be labeled before use - (usually with the {\bf label} command). This command can, however, be - useful if you wish to add a number of Volumes to the Pool that will be - physically labeled at a later time. It can also be useful if you are - importing a tape from another site. Please see the {\bf label} command - below for the list of legal characters in a Volume name. - -\item [autodisplay on/off] - \index[console]{autodisplay on/off} - This command accepts {\bf on} or {\bf off} as an argument, and turns - auto-display of messages on or off respectively. The default for the - console program is {\bf off}, which means that you will be notified when - there are console messages pending, but they will not automatically be - displayed. The default for the bgnome-console program is {\bf on}, which - means that messages will be displayed when they are received (usually - within five seconds of them being generated). - - When autodisplay is turned off, you must explicitly retrieve the - messages with the {\bf messages} command. When autodisplay is turned - on, the messages will be displayed on the console as they are received. - -\item [automount on/off] - \index[console]{automount on/off} - This command accepts {\bf on} or {\bf off} as the argument, and turns - auto-mounting of the Volume after a {\bf label} command on or off - respectively. The default is {\bf on}. If {\bf automount} is turned - off, you must explicitly {\bf mount} tape Volumes after a label command to - use it. - -\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}] - \index[console]{cancel jobid} - This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf - job=xxx} as an argument where nnn is replaced by the JobId and xxx is - replaced by the job name. If you do not specify a keyword, the Console - program will prompt you with the names of all the active jobs allowing - you to choose one. - - Once a Job is marked to be canceled, it may take a bit of time - (generally within a minute) before it actually terminates, depending on - what operations it is doing. - -\item [{create [pool=\lt{}pool-name\gt{}]}] - \index[console]{create pool} - This command is not normally used as the Pool records are automatically - created by the Director when it starts based on what it finds in - the conf file. If needed, this command can be - to create a Pool record in the database using the - Pool resource record defined in the Director's configuration file. So - in a sense, this command simply transfers the information from the Pool - resource in the configuration file into the Catalog. Normally this - command is done automatically for you when the Director starts providing - the Pool is referenced within a Job resource. If you use this command - on an existing Pool, it will automatically update the Catalog to have - the same information as the Pool resource. After creating a Pool, you - will most likely use the {\bf label} command to label one or more - volumes and add their names to the Media database. - - When starting a Job, if Bacula determines that there is no Pool record - in the database, but there is a Pool resource of the appropriate name, - it will create it for you. If you want the Pool record to appear in the - database immediately, simply use this command to force it to be created. - -\item [{delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job - jobid=\lt{}id\gt{}]}] - \index[console]{delete} - The delete command is used to delete a Volume, Pool or Job record from - the Catalog as well as all associated catalog Volume records that were - created. This command operates only on the Catalog database and has no - effect on the actual data written to a Volume. This command can be - dangerous and we strongly recommend that you do not use it unless you - know what you are doing. - - If the keyword {\bf Volume} appears on the command line, the named - Volume will be deleted from the catalog, if the keyword {\bf Pool} - appears on the command line, a Pool will be deleted, and if the keyword - {\bf Job} appears on the command line, a Job and all its associated - records (File and JobMedia) will be deleted from the catalog. The full - form of this command is: - -\begin{verbatim} -delete pool= -\end{verbatim} - - or - -\begin{verbatim} -delete volume=>volume-name> pool=>pool-name> or -\end{verbatim} - -\begin{verbatim} -delete JobId=>job-id> JobId=>job-id2> ... or -\end{verbatim} - -\begin{verbatim} -delete Job JobId=n,m,o-r,t ... -\end{verbatim} - - The first form deletes a Pool record from the catalog database. The - second form deletes a Volume record from the specified pool in the - catalog database. The third form deletes the specified Job record from - the catalog database. The last form deletes JobId records for JobIds - n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a - number. That is a "delete jobid" accepts lists and ranges of - jobids. - -\item [disable job\lt{}job-name\gt{}] - \index[console]{disable} - This command permits you to disable a Job for automatic scheduling. - The job may have been previously enabled with the Job resource - {\bf Enabled} directive or using the console {\bf enable} command. - The next time the Director is restarted or the conf file is reloaded, - the Enable/Disable state will be set to the value in the Job resource - (default enabled) as defined in the bacula-dir.conf file. - -\item [enable job\lt{}job-name\gt{}] - \index[console]{enable} - This command permits you to enable a Job for automatic scheduling. - The job may have been previously disabled with the Job resource - {\bf Enabled} directive or using the console {\bf disable} command. - The next time the Director is restarted or the conf file is reloaded, - the Enable/Disable state will be set to the value in the Job resource - (default enabled) as defined in the bacula-dir.conf file. - -\label{estimate} -\item [estimate] - \index[console]{estimate} - Using this command, you can get an idea how many files will be backed - up, or if you are unsure about your Include statements in your FileSet, - you can test them without doing an actual backup. The default is to - assume a Full backup. However, you can override this by specifying a - {\bf level=Incremental} or {\bf level=Differential} on the command line. - A Job name must be specified or you will be prompted for one, and - optionally a Client and FileSet may be specified on the command line. - It then contacts the client which computes the number of files and bytes - that would be backed up. Please note that this is an estimate - calculated from the number of blocks in the file rather than by reading - the actual bytes. As such, the estimated backup size will generally be - larger than an actual backup. - - Optionally you may specify the keyword {\bf listing} in which case, all the - files to be backed up will be listed. Note, it could take quite some time to - display them if the backup is large. The full form is: - - -\begin{verbatim} -estimate job= listing client= - fileset= level= -\end{verbatim} - - Specification of the {\bf job} is sufficient, but you can also override - the client, fileset and/or level by specifying them on the estimate - command line. - - -As an example, you might do: - -\footnotesize -\begin{verbatim} - @output /tmp/listing - estimate job=NightlySave listing level=Incremental - @output -\end{verbatim} -\normalsize - - which will do a full listing of all files to be backed up for the Job {\bf - NightlySave} during an Incremental save and put it in the file {\bf - /tmp/listing}. Note, the byte estimate provided by this command is - based on the file size contained in the directory item. This can give - wildly incorrect estimates of the actual storage used if there are - sparse files on your systems. Sparse files are often found on 64 bit - systems for certain system files. The size that is returned is the size - Bacula will backup if the sparse option is not specified in the FileSet. - There is currently no way to get an estimate of the real file size that - would be found should the sparse option be enabled. - - -\item [help] - \index[console]{help} - This command displays the list of commands available. - -\item [label] - \index[console]{label} - \index[console]{relabel} - \index[general]{label} - \index[general]{relabel} - This command is used to label physical volumes. The full form of this command - is: - -\begin{verbatim} -label storage=>storage-name> volume=>volume-name> - slot=>slot> -\end{verbatim} - - If you leave out any part, you will be prompted for it. The media type - is automatically taken from the Storage resource definition that you - supply. Once the necessary information is obtained, the Console program - contacts the specified Storage daemon and requests that the Volume be - labeled. If the Volume labeling is successful, the Console program will - create a Volume record in the appropriate Pool. - - The Volume name is restricted to letters, numbers, and the special - characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and - period ({\bf .}). All other characters including a space are invalid. - This restriction is to ensure good readability of Volume names to reduce - operator errors. - - Please note, when labeling a blank tape, Bacula will get {\bf read I/O - error} when it attempts to ensure that the tape is not already labeled. If - you wish to avoid getting these messages, please write an EOF mark on - your tape before attempting to label it: - -\footnotesize -\begin{verbatim} - mt rewind - mt weof - -\end{verbatim} -\normalsize - -The label command can fail for a number of reasons: - -\begin{enumerate} -\item The Volume name you specify is already in the Volume database. - -\item The Storage daemon has a tape or other Volume already mounted on the - device, in which case you must {\bf unmount} the device, insert a blank - tape, then do the {\bf label} command. - -\item The Volume in the device is already a Bacula labeled Volume. (Bacula will - never relabel a Bacula labeled Volume unless it is recycled and you use the - {\bf relabel} command). - -\item There is no Volume in the drive. -\end{enumerate} - -There are two ways to relabel a volume that already has a Bacula label. The -brute force method is to write an end of file mark on the tape using the -system {\bf mt} program, something like the following: - -\footnotesize -\begin{verbatim} - mt -f /dev/st0 rewind - mt -f /dev/st0 weof -\end{verbatim} -\normalsize - -For a disk volume, you would manually delete the Volume. - -Then you use the {\bf label} command to add a new label. However, this could -leave traces of the old volume in the catalog. - -The preferable method to relabel a Volume is to first {\bf purge} the volume, -either automatically, or explicitly with the {\bf purge} command, then use -the {\bf relabel} command described below. - -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" directive in the Director's Pool resource, will be -treated as a cleaning tape, and will not be labeled. However, an entry for -the cleaning tape will be created in the catalog. For example with: - -\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. Note, the full form of the command is: - -\footnotesize -\begin{verbatim} -label storage=xxx pool=yyy slots=1-5,10 barcodes -\end{verbatim} -\normalsize - -\item [list] - \index[console]{list} - The list command lists the requested contents of the Catalog. The - various fields of each record are listed on a single line. The various - forms of the list command are: -\footnotesize -\begin{verbatim} - list jobs - - list jobid= (list jobid id) - - list ujobid (list job with unique name) - - list job= (list all jobs with "job-name") - - list jobname= (same as above) - - In the above, you can add "limit=nn" to limit the output to - nn jobs. - - list jobmedia - - list jobmedia jobid= - - list jobmedia job= - - list files jobid= - - list files job= - - list pools - - list clients - - list jobtotals - - list volumes - - list volumes jobid= - - list volumes pool= - - list volumes job= - - list volume= - - list nextvolume job= - - list nextvol job= - - list nextvol job= days=nnn - -\end{verbatim} -\normalsize - - What most of the above commands do should be more or less obvious. In - general if you do not specify all the command line arguments, the - command will prompt you for what is needed. - - The {\bf list nextvol} command will print the Volume name to be used by - the specified job. You should be aware that exactly what Volume will be - used depends on a lot of factors including the time and what a prior job - will do. It may fill a tape that is not full when you issue this - command. As a consequence, this command will give you a good estimate - of what Volume will be used but not a definitive answer. In addition, - this command may have certain side effect because it runs through the - same algorithm as a job, which means it may automatically purge or - recycle a Volume. By default, the job specified must run within the - next two days or no volume will be found. You can, however, use the - {\bf days=nnn} specification to specify up to 50 days. For example, - if on Friday, you want to see what Volume will be needed on Monday, - for job MyJob, you would use {\bf list nextvol job=MyJob days=3}. - - If you wish to add specialized commands that list the contents of the - catalog, you can do so by adding them to the {\bf query.sql} file. - However, this takes some knowledge of programming SQL. Please see the - {\bf query} command below for additional information. See below for - listing the full contents of a catalog record with the {\bf llist} - command. - - As an example, the command {\bf list pools} might produce the following - output: - -\footnotesize -\begin{verbatim} -+------+---------+---------+---------+----------+-------------+ -| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat | -+------+---------+---------+---------+----------+-------------+ -| 1 | Default | 0 | 0 | Backup | * | -| 2 | Recycle | 0 | 8 | Backup | File | -+------+---------+---------+---------+----------+-------------+ -\end{verbatim} -\normalsize - - As mentioned above, the {\bf list} command lists what is in the - database. Some things are put into the database immediately when Bacula - starts up, but in general, most things are put in only when they are - first used, which is the case for a Client as with Job records, etc. - - Bacula should create a client record in the database the first time you - run a job for that client. Doing a {\bf status} will not cause a - database record to be created. The client database record will be - created whether or not the job fails, but it must at least start. When - the Client is actually contacted, additional info from the client will - be added to the client record (a "uname -a" output). - - If you want to see what Client resources you have available in your conf - file, you use the Console command {\bf show clients}. - -\item [llist] - \index[console]{llist} - The llist or "long list" command takes all the same arguments that the - list command described above does. The difference is that the llist - command list the full contents of each database record selected. It - does so by listing the various fields of the record vertically, with one - field per line. It is possible to produce a very large number of output - lines with this command. - - If instead of the {\bf list pools} as in the example above, you enter - {\bf llist pools} you might get the following output: - -\footnotesize -\begin{verbatim} - PoolId: 1 - Name: Default - NumVols: 0 - MaxVols: 0 - UseOnce: 0 - UseCatalog: 1 - AcceptAnyVolume: 1 - VolRetention: 1,296,000 - VolUseDuration: 86,400 - MaxVolJobs: 0 - MaxVolBytes: 0 - AutoPrune: 0 - Recycle: 1 - PoolType: Backup - LabelFormat: * - - PoolId: 2 - Name: Recycle - NumVols: 0 - MaxVols: 8 - UseOnce: 0 - UseCatalog: 1 - AcceptAnyVolume: 1 - VolRetention: 3,600 - VolUseDuration: 3,600 - MaxVolJobs: 1 - MaxVolBytes: 0 - AutoPrune: 0 - Recycle: 1 - PoolType: Backup - LabelFormat: File - -\end{verbatim} -\normalsize - -\item [messages] - \index[console]{messages} - This command causes any pending console messages to be immediately displayed. - - -\item [mount] - \index[console]{mount} - The mount command is used to get Bacula to read a volume on a physical - device. It is a way to tell Bacula that you have mounted a tape and - that Bacula should examine the tape. This command is normally - used only after there was no Volume in a drive and Bacula requests you to mount a new - Volume or when you have specifically unmounted a Volume with the {\bf - unmount} console command, which causes Bacula to close the drive. If - you have an autoloader, the mount command will not cause Bacula to - operate the autoloader unless you specify a {\bf slot} and possibly a - {\bf drive}. The various forms of the mount command are: - -mount storage=\lt{}storage-name\gt{} [ slot=\lt{}num\gt{} ] [ - drive=\lt{}num\gt{} ] - -mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ] - - If you have specified {\bf Automatic Mount = yes} in the Storage daemon's - Device resource, under most circumstances, Bacula will automatically access - the Volume unless you have explicitly {\bf unmount}ed it in the Console - program. - -\item[python] - \index[console]{python} - The python command takes a single argument {\bf restart}: - -python restart - - This causes the Python interpreter in the Director to be reinitialized. - This can be helpful for testing because once the Director starts and the - Python interpreter is initialized, there is no other way to make it - accept any changes to the startup script {\bf DirStartUp.py}. For more - details on Python scripting, please see the \ilink{Python - Scripting}{PythonChapter} chapter of this manual. - -\label{ManualPruning} -\item [prune] - \index[console]{prune} - The Prune command allows you to safely remove expired database records - from Jobs and Volumes. This command works only on the Catalog database - and does not affect data written to Volumes. In all cases, the Prune - command applies a retention period to the specified records. You can - Prune expired File entries from Job records; you can Prune expired Job - records from the database, and you can Prune both expired Job and File - records from specified Volumes. - -prune files|jobs|volume client=\lt{}client-name\gt{} -volume=\lt{}volume-name\gt{} - - For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or - Append, otherwise the pruning will not take place. - -\item [purge] - \index[console]{purge} - The Purge command will delete associated Catalog database records from - Jobs and Volumes without considering the retention period. {\bf Purge} - works only on the Catalog database and does not affect data written to - Volumes. This command can be dangerous because you can delete catalog - records associated with current backups of files, and we recommend that - you do not use it unless you know what you are doing. The permitted - forms of {\bf purge} are: - -purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{} - -purge jobs client=\lt{}client-name\gt{} (of all jobs) - -purge volume|volume=\lt{}vol-name\gt{} (of all jobs) - -For the {\bf purge} command to work on Volume Catalog database records the -{\bf VolStatus} must be Append, Full, Used, or Error. - -The actual data written to the Volume will be unaffected by this command. - -\item [relabel] - \index[console]{relabel} - \index[general]{relabel} - This command is used to label physical volumes. The full form of this - command is: - -relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{} - volume=\lt{}newvolume-name\gt{} - - If you leave out any part, you will be prompted for it. In order for - the Volume (old-volume-name) to be relabeled, it must be in the catalog, - and the volume status must be marked {\bf Purged} or {\bf Recycle}. - This happens automatically as a result of applying retention periods, or - you may explicitly purge the volume using the {\bf purge} command. - - Once the volume is physically relabeled, the old data previously written - on the Volume is lost and cannot be recovered. - -\item [release] - \index[console]{release} - This command is used to cause the Storage daemon to rewind (release) the - current tape in the drive, and to re-read the Volume label the next time - the tape is used. - -release storage=\lt{}storage-name\gt{} - - After a release command, the device is still kept open by Bacula (unless - Always Open is set to No in the Storage Daemon's configuration) so it - cannot be used by another program. However, with some tape drives, the - operator can remove the current tape and to insert a different one, and - when the next Job starts, Bacula will know to re-read the tape label to - find out what tape is mounted. If you want to be able to use the drive - with another program (e.g. {\bf mt}), you must use the {\bf unmount} - command to cause Bacula to completely release (close) the device. - -\item [reload] - \index[console]{reload} - The reload command causes the Director to re-read its configuration - file and apply the new values. The new values will take effect - immediately for all new jobs. However, if you change schedules, - be aware that the scheduler pre-schedules jobs up to two hours in - advance, so any changes that are to take place during the next two - hours may be delayed. Jobs that have already been scheduled to run - (i.e. surpassed their requested start time) will continue with the - old values. New jobs will use the new values. Each time you issue - a reload command while jobs are running, the prior config values - will queued until all jobs that were running before issuing - the reload terminate, at which time the old config values will - be released from memory. The Directory permits keeping up to - ten prior set of configurations before it will refuse a reload - command. Once at least one old set of config values has been - released it will again accept new reload commands. - - While it is possible to reload the Director's configuration on the fly, - even while jobs are executing, this is a complex operation and not - without side effects. Accordingly, if you have to reload the Director's - configuration while Bacula is running, it is advisable to restart the - Director at the next convenient opportunity. - -\label{restore_command} -\item [restore] - \index[console]{restore} - The restore command allows you to select one or more Jobs (JobIds) to be - restored using various methods. Once the JobIds are selected, the File - records for those Jobs are placed in an internal Bacula directory tree, - and the restore enters a file selection mode that allows you to - interactively walk up and down the file tree selecting individual files - to be restored. This mode is somewhat similar to the standard Unix {\bf - restore} program's interactive file selection mode. - -restore storage=\lt{}storage-name\gt{} client=\lt{}backup-client-name\gt{} - where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{} - restoreclient=\lt{}restore-client-name\gt{} - select current all done - - Where {\bf current}, if specified, tells the restore command to - automatically select a restore to the most current backup. If not - specified, you will be prompted. The {\bf all} specification tells the - restore command to restore all files. If it is not specified, you will - be prompted for the files to restore. For details of the {\bf restore} - command, please see the \ilink{Restore Chapter}{RestoreChapter} of this - manual. - - The client keyword initially specifies the client from which the backup - was made and the client to which the restore will be make. However, - if the restoreclient keyword is specified, then the restore is written - to that client. - -\item [run] - \index[console]{run} - This command allows you to schedule jobs to be run immediately. The full form - of the command is: - -run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{} - fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{} - storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{} - when=\lt{}universal-time-specification\gt{} yes - - Any information that is needed but not specified will be listed for - selection, and before starting the job, you will be prompted to accept, - reject, or modify the parameters of the job to be run, unless you have - specified {\bf yes}, in which case the job will be immediately sent to - the scheduler. - - On my system, when I enter a run command, I get the following prompt: - -\footnotesize -\begin{verbatim} -A job name must be specified. -The defined Job resources are: - 1: Matou - 2: Polymatou - 3: Rufus - 4: Minimatou - 5: Minou - 6: PmatouVerify - 7: MatouVerify - 8: RufusVerify - 9: Watchdog -Select Job resource (1-9): - -\end{verbatim} -\normalsize - -If I then select number 5, I am prompted with: - -\footnotesize -\begin{verbatim} -Run Backup job -JobName: Minou -FileSet: Minou Full Set -Level: Incremental -Client: Minou -Storage: DLTDrive -Pool: Default -When: 2003-04-23 17:08:18 -OK to run? (yes/mod/no): - -\end{verbatim} -\normalsize - -If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will -be presented with the following prompt. - -\footnotesize -\begin{verbatim} -Parameters to modify: - 1: Level - 2: Storage - 3: Job - 4: FileSet - 5: Client - 6: When - 7: Pool -Select parameter to modify (1-7): - -\end{verbatim} -\normalsize - -If you wish to start a job at a later time, you can do so by setting the When -time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the -desired start time in YYYY-MM-DD HH:MM:SS format. - -\item [setdebug] - \index[console]{setdebug} - \index[dir]{setdebug} - \index[dir]{debugging} - \index[dir]{debugging Win32} - \index[dir]{Windows!debugging} - This command is used to set the debug level in each daemon. The form of this - command is: - -setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director | - storage=\lt{}storage-name\gt{} | all] - - If trace=1 is set, then tracing will be enabled, and the daemon will be - placed in trace mode, which means that all debug output as set by the - debug level will be directed to the file {\bf bacula.trace} in the - current directory of the daemon. Normally, tracing is needed only for - Win32 clients where the debug output cannot be written to a terminal or - redirected to a file. When tracing, each debug output message is - appended to the trace file. You must explicitly delete the file when - you are done. - -\item [show] - \index[console]{show} - \index[dir]{show} - The show command will list the Director's resource records as defined in - the Director's configuration file (normally {\bf bacula-dir.conf}). - This command is used mainly for debugging purposes by developers. - The following keywords are accepted on the - show command line: catalogs, clients, counters, devices, directors, - filesets, jobs, messages, pools, schedules, storages, all, help. - Please don't confuse this command - with the {\bf list}, which displays the contents of the catalog. - -\item [sqlquery] - \index[console]{sqlquery} - The sqlquery command puts the Console program into SQL query mode where - each line you enter is concatenated to the previous line until a - semicolon (;) is seen. The semicolon terminates the command, which is - then passed directly to the SQL database engine. When the output from - the SQL engine is displayed, the formation of a new SQL command begins. - To terminate SQL query mode and return to the Console command prompt, - you enter a period (.) in column 1. - - Using this command, you can query the SQL catalog database directly. - Note you should really know what you are doing otherwise you could - damage the catalog database. See the {\bf query} command below for - simpler and safer way of entering SQL queries. - - Depending on what database engine you are using (MySQL, PostgreSQL or - SQLite), you will have somewhat different SQL commands available. For - more detailed information, please refer to the MySQL, PostgreSQL or - SQLite documentation. - -\item [status] - \index[dir]{status} - This command will display the status of the next jobs that are scheduled - during the next 24 hours as well as the status of currently - running jobs. The full form of this command is: - -status [all | dir=\lt{}dir-name\gt{} | director | - client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} | - days=nnn] - - If you do a {\bf status dir}, the console will list any currently - running jobs, a summary of all jobs scheduled to be run in the next 24 - hours, and a listing of the last ten terminated jobs with their statuses. - The scheduled jobs summary will include the Volume name to be used. You - should be aware of two things: 1. to obtain the volume name, the code - goes through the same code that will be used when the job runs, but it - does not do pruning nor recycling of Volumes; 2. The Volume listed is - at best a guess. The Volume actually used may be different because of - the time difference (more durations may expire when the job runs) and - another job could completely fill the Volume requiring a new one. - - In the Running Jobs listing, you may find the following types of - information: - - -\footnotesize -\begin{verbatim} -2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution -5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher - priority jobs to finish -5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs -5343 Full Rufus.2004-03-13_01.05.04 is running -\end{verbatim} -\normalsize - - Looking at the above listing from bottom to top, obviously JobId 5343 - (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to - finish because it is using the Storage resource, hence the "waiting on - max Storage jobs". JobId 5349 has a lower priority than all the other - jobs so it is waiting for higher priority jobs to finish, and finally, - JobId 2508 (MatouVerify) is waiting because only one job can run at a - time, hence it is simply "waiting execution" - - If you do a {\bf status dir}, it will by default list the first - occurrence of all jobs that are scheduled today and tomorrow. If you - wish to see the jobs that are scheduled in the next three days (e.g. on - Friday you want to see the first occurrence of what tapes are scheduled - to be used on Friday, the weekend, and Monday), you can add the {\bf - days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs - scheduled today only. If you have multiple run statements, the first - occurrence of each run statement for the job will be displayed for the - period specified. - - If your job seems to be blocked, you can get a general idea of the - problem by doing a {\bf status dir}, but you can most often get a - much more specific indication of the problem by doing a - {\bf status storage=xxx}. For example, on an idle test system, when - I do {\bf status storage=File}, I get: -\footnotesize -\begin{verbatim} -status storage=File -Connecting to Storage daemon File at 192.168.68.112:8103 - -rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz) -Daemon started 26-Mar-06 11:06, 0 Jobs run since started. - -Running Jobs: -No Jobs running. -==== - -Jobs waiting to reserve a drive: -==== - -Terminated Jobs: - JobId Level Files Bytes Status Finished Name -====================================================================== - 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave -==== - -Device status: -utochanger "DDS-4-changer" with devices: - "DDS-4" (/dev/nst0) -Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002" -Pool="*unknown*" - Slot 2 is loaded in drive 0. - Total Bytes Read=0 Blocks Read=0 Bytes/block=0 - Positioned at File=0 Block=0 -Device "Dummy" is not open or does not exist. -No DEVICE structure. - -Device "DVD-Writer" (/dev/hdc) is not open. -Device "File" (/tmp) is not open. -==== - -In Use Volume status: -==== -\end{verbatim} -\normalsize - -Now, what this tells me is that no jobs are running and that none of -the devices are in use. Now, if I {\bf unmount} the autochanger, which -will not be used in this example, and then start a Job that uses the -File device, the job will block. When I re-issue the status storage -command, I get for the Device status: - -\footnotesize -\begin{verbatim} -status storage=File -... -Device status: -Autochanger "DDS-4-changer" with devices: - "DDS-4" (/dev/nst0) -Device "DDS-4" (/dev/nst0) is not open. - Device is BLOCKED. User unmounted. - Drive 0 is not loaded. -Device "Dummy" is not open or does not exist. -No DEVICE structure. - -Device "DVD-Writer" (/dev/hdc) is not open. -Device "File" (/tmp) is not open. - Device is BLOCKED waiting for media. -==== -... -\end{verbatim} -\normalsize - -Now, here it should be clear that if a job were running that wanted -to use the Autochanger (with two devices), it would block because -the user unmounted the device. The real problem for the Job I started -using the "File" device is that the device is blocked waiting for -media -- that is Bacula needs you to label a Volume. - -\item [unmount] - \index[console]{unmount} - This command causes the indicated Bacula Storage daemon to unmount the - specified device. The forms of the command are the same as the mount command: -\footnotesize -\begin{verbatim} -unmount storage= [ drive= ] - -unmount [ jobid= | job= ] -\end{verbatim} -\normalsize - - Once you unmount a storage device, Bacula will no longer be able to use - it until you issue a mount command for that device. If Bacula needs to - access that device, it will block and issue mount requests periodically - to the operator. - - If the device you are unmounting is an autochanger, it will unload - the drive you have specified on the command line. If no drive is - specified, it will assume drive 1. - -\label{UpdateCommand} -\item [update] - \index[console]{update} - This command will update the catalog for either a specific Pool record, a Volume - record, or the Slots in an autochanger with barcode capability. In the case - of updating a Pool record, the new information will be automatically taken - from the corresponding Director's configuration resource record. It can be - used to increase the maximum number of volumes permitted or to set a maximum - number of volumes. The following main keywords may be specified: -\footnotesize -\begin{verbatim} - media, volume, pool, slots -\end{verbatim} -\normalsize - -In the case of updating a Volume, you will be prompted for which value you -wish to change. The following Volume parameters may be changed: - -\footnotesize -\begin{verbatim} - - Volume Status - Volume Retention Period - Volume Use Duration - Maximum Volume Jobs - Maximum Volume Files - Maximum Volume Bytes - Recycle Flag - Recycle Pool - Slot - InChanger Flag - Pool - Volume Files - Volume from Pool - All Volumes from Pool - All Volumes from all Pools - -\end{verbatim} -\normalsize - - For slots {\bf update slots}, Bacula will obtain a list of slots and - their barcodes from the Storage daemon, and for each barcode found, it - will automatically update the slot in the catalog Media record to - correspond to the new value. This is very useful if you have moved - cassettes in the magazine, or if you have removed the magazine and - inserted a different one. As the slot of each Volume is updated, the - InChanger flag for that Volume will also be set, and any other Volumes - in the Pool that were last mounted on the same Storage device - will have their InChanger flag turned off. This permits - Bacula to know what magazine (tape holder) is currently in the - autochanger. - - If you do not have barcodes, you can accomplish the same thing in - version 1.33 and later by using the {\bf update slots scan} command. - The {\bf scan} keyword tells Bacula to physically mount each tape and to - read its VolumeName. - - For Pool {\bf update pool}, Bacula will move the Volume record from its - existing pool to the pool specified. - - For {\bf Volume from Pool}, {\bf All Volumes from Pool} and {\bf All Volumes - from all Pools}, the following values are updated from the Pool record: - Recycle, RecyclePool, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, - and MaxVolBytes. (RecyclePool feature is available with bacula 2.1.4 or - higher.) - - The full form of the update command with all command line arguments is: - -\footnotesize -\begin{verbatim} - update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd - VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no - slot=nnn enabled=n recyclepool=zzz - -\end{verbatim} -\normalsize - -\item [use] - \index[console]{use} - This command allows you to specify which Catalog database to use. Normally, -you will be using only one database so this will be done automatically. In -the case that you are using more than one database, you can use this command -to switch from one to another. - -use \lt{}database-name\gt{} - -\item [var] - \label{var} - \index[console]{var name} - This command takes a string or quoted string and does variable expansion on - it the same way variable expansion is done on the {\bf LabelFormat} string. - Thus, for the most part, you can test your LabelFormat strings. The - difference between the {\bf var} command and the actual LabelFormat process - is that during the var command, no job is running so "dummy" values are - used in place of Job specific variables. Generally, however, you will get a - good idea of what is going to happen in the real case. - -\item [version] - \index[console]{version} - The command prints the Director's version. - -\item [quit] - \index[console]{quit} - This command terminates the console program. The console program sends the - {\bf quit} request to the Director and waits for acknowledgment. If the - Director is busy doing a previous command for you that has not terminated, it - may take some time. You may quit immediately by issuing the {\bf .quit} - command (i.e. quit preceded by a period). - -\item [query] - \index[console]{query} - This command reads a predefined SQL query from the query file (the name and - location of the query file is defined with the QueryFile resource record in - the Director's configuration file). You are prompted to select a query from - the file, and possibly enter one or more parameters, then the command is - submitted to the Catalog database SQL engine. - -The following queries are currently available (version 1.24): - -\footnotesize -\begin{verbatim} -Available queries: - 1: List Job totals: - 2: List where a file is saved: - 3: List where the most recent copies of a file are saved: - 4: List total files/bytes by Job: - 5: List total files/bytes by Volume: - 6: List last 20 Full Backups for a Client: - 7: List Volumes used by selected JobId: - 8: List Volumes to Restore All Files: - 9: List where a File is saved: -Choose a query (1-9): - -\end{verbatim} -\normalsize - -\item [exit] - \index[console]{exit} - This command terminates the console program. - -\item [wait] - \index[console]{wait} - The wait command causes the Director to pause until there are no jobs - running. This command is useful in a batch situation such as regression - testing where you wish to start a job and wait until that job completes - before continuing. This command now has the following options: -\footnotesize -\begin{verbatim} - wait [jobid=nn] [jobuid=unique id] [job=job name] -\end{verbatim} -\normalsize - If specified with a specific JobId, ... the wait command will wait - for that particular job to terminate before continuing. - -\end{description} - -\label{dotcommands} -\section{Special dot Commands} -\index[general]{Commands!Special dot} -\index[general]{Special dot Commands} - -There is a list of commands that are prefixed with a period (.). These -commands are intended to be used either by batch programs or graphical user -interface front-ends. They are not normally used by interactive users. Once -GUI development begins, this list will be considerably expanded. The following -is the list of dot commands: - -\footnotesize -\begin{verbatim} -.backups job=xxx list backups for specified job -.clients list all client names -.defaults client=xxx fileset=yyy list defaults for specified client -.die cause the Director to segment fault (for debugging) -.dir when in tree mode prints the equivalent to the dir command, - but with fields separated by commas rather than spaces. -.exit quit -.filesets list all fileset names -.help help command output -.jobs list all job names -.levels list all levels -.messages get quick messages -.msgs return any queued messages -.pools list all pool names -.quit quit -.status get status output -.storage return storage resource names -.types list job types -\end{verbatim} -\normalsize - -\label{atcommands} - -\section{Special At (@) Commands} -\index[general]{Commands!Special At @} -\index[general]{Special At (@) Commands} - -Normally, all commands entered to the Console program are immediately -forwarded to the Director, which may be on another machine, to be executed. -However, there is a small list of {\bf at} commands, all beginning with an at -character (@), that will not be sent to the Director, but rather interpreted -by the Console program directly. Note, these commands are implemented only in -the tty console program and not in the GNOME Console. These commands are: - -\begin{description} - -\item [@input \lt{}filename\gt{}] - \index[console]{@input \lt{}filename\gt{}} - Read and execute the commands contained in the file specified. - -\item [@output \lt{}filename\gt{} w/a] - \index[console]{@output \lt{}filename\gt{} w/a} - Send all following output to the filename specified either overwriting the -file (w) or appending to the file (a). To redirect the output to the -terminal, simply enter {\bf @output} without a filename specification. -WARNING: be careful not to overwrite a valid file. A typical example during a -regression test might be: - -\footnotesize -\begin{verbatim} - @output /dev/null - commands ... - @output - -\end{verbatim} -\normalsize - -\item [@tee \lt{}filename\gt{} w/a] - \index[console]{@tee \lt{}filename\gt{} w/a} - Send all subsequent output to both the specified file and the terminal. It is - turned off by specifying {\bf @tee} or {\bf @output} without a filename. - -\item [@sleep \lt{}seconds\gt{}] - \index[console]{@sleep \lt{}seconds\gt{}} - Sleep the specified number of seconds. - -\item [@time] - \index[console]{@time} - Print the current time and date. - -\item [@version] - \index[console]{@version} - Print the console's version. - -\item [@quit] - \index[console]{@quit} - quit - -\item [@exit] - \index[console]{@exit} - quit - -\item [@\# anything] - \index[console]{anything} - Comment -\end{description} - -\label{scripting} - -\section{Running the Console from a Shell Script} -\index[general]{Script!Running the Console Program from a Shell} -\index[general]{Running the Console Program from a Shell Script} - -You can automate many Console tasks by running the console program from a -shell script. For example, if you have created a file containing the following -commands: - -\footnotesize -\begin{verbatim} - ./bconsole -c ./bconsole.conf <master.keypair - -\item 2) Set the PKI Keypair statement in your bacula configuration file: - -\begin{verbatim} - PKI Keypair = master.keypair -\end{verbatim} - -\item Start the restore. The master keypair will be used to decrypt - the file data. - -\end{itemize} - - -\section{Generating Private/Public Encryption Keys} -\index[general]{Generating Private/Public Encryption Keypairs} - -Generate a Master Key Pair with: - -\footnotesize -\begin{verbatim} - openssl genrsa -out master.key 2048 - openssl req -new -key master.key -x509 -out master.cert -\end{verbatim} -\normalsize - -Generate a File Daemon Key Pair for each FD: - -\footnotesize -\begin{verbatim} - openssl genrsa -out fd-example.key 2048 - openssl req -new -key fd-example.key -x509 -out fd-example.cert - cat fd-example.key fd-example.cert >fd-example.pem -\end{verbatim} -\normalsize - -Note, there seems to be a lot of confusion around the file extensions given -to these keys. For example, a .pem file can contain all the following: -private keys (RSA and DSA), public keys (RSA and DSA) and (x509) certificates. -It is the default format for OpenSSL. It stores data Base64 encoded DER format, -surrounded by ASCII headers, so is suitable for text mode transfers between -systems. A .pem file may contain any number of keys either public or -private. We use it in cases where there is both a public and a private -key. - -Typically, above we have used the .cert extension to refer to X509 -certificate encoding that contains only a single public key. - - -\section{Example Data Encryption Configuration} -\index[general]{Example!File Daemon Configuration File} -\index[general]{Example!Data Encryption Configuration File} -\index[general]{Example Data Encryption Configuration} - -{\bf bacula-fd.conf} -\footnotesize -\begin{verbatim} -FileDaemon { - Name = example-fd - FDport = 9102 # where we listen for the director - WorkingDirectory = /var/bacula/working - Pid Directory = /var/run - Maximum Concurrent Jobs = 20 - - PKI Signatures = Yes # Enable Data Signing - PKI Encryption = Yes # Enable Data Encryption - PKI Keypair = "/etc/bacula/fd-example.pem" # Public and Private Keys - PKI Master Key = "/etc/bacula/master.cert" # ONLY the Public Key -} -\end{verbatim} -\normalsize diff --git a/docs/manual/dirdconf.tex b/docs/manual/dirdconf.tex deleted file mode 100644 index c823d640..00000000 --- a/docs/manual/dirdconf.tex +++ /dev/null @@ -1,3377 +0,0 @@ -%% -%% - -\chapter{Configuring the Director} -\label{DirectorChapter} -\index[general]{Director!Configuring the} -\index[general]{Configuring the Director} - -Of all the configuration files needed to run {\bf Bacula}, the Director's is -the most complicated, and the one that you will need to modify the most often -as you add clients or modify the FileSets. - -For a general discussion of configuration files and resources including the -data types recognized by {\bf Bacula}. Please see the -\ilink{Configuration}{ConfigureChapter} chapter of this manual. - -\section{Director Resource Types} -\index[general]{Types!Director Resource} -\index[general]{Director Resource Types} - -Director resource type may be one of the following: - -Job, JobDefs, Client, Storage, Catalog, Schedule, FileSet, Pool, Director, or -Messages. We present them here in the most logical order for defining them: - -Note, everything revolves around a job and is tied to a job in one -way or another. - -\begin{itemize} -\item - \ilink{Director}{DirectorResource4} -- to define the Director's - name and its access password used for authenticating the Console program. - Only a single Director resource definition may appear in the Director's - configuration file. If you have either {\bf /dev/random} or {\bf bc} on your - machine, Bacula will generate a random password during the configuration - process, otherwise it will be left blank. -\item - \ilink{Job}{JobResource} -- to define the backup/restore Jobs - and to tie together the Client, FileSet and Schedule resources to be used - for each Job. Normally, you will Jobs of different names corresponding - to each client (i.e. one Job per client, but a different one with a different name - for each client). -\item - \ilink{JobDefs}{JobDefsResource} -- optional resource for - providing defaults for Job resources. -\item - \ilink{Schedule}{ScheduleResource} -- to define when a Job is to - be automatically run by {\bf Bacula's} internal scheduler. You - may have any number of Schedules, but each job will reference only - one. -\item - \ilink{FileSet}{FileSetResource} -- to define the set of files - to be backed up for each Client. You may have any number of - FileSets but each Job will reference only one. -\item - \ilink{Client}{ClientResource2} -- to define what Client is to be - backed up. You will generally have multiple Client definitions. Each - Job will reference only a single client. -\item - \ilink{Storage}{StorageResource2} -- to define on what physical - device the Volumes should be mounted. You may have one or - more Storage definitions. -\item - \ilink{Pool}{PoolResource} -- to define the pool of Volumes - that can be used for a particular Job. Most people use a - single default Pool. However, if you have a large number - of clients or volumes, you may want to have multiple Pools. - Pools allow you to restrict a Job (or a Client) to use - only a particular set of Volumes. -\item - \ilink{Catalog}{CatalogResource} -- to define in what database to - keep the list of files and the Volume names where they are backed up. - Most people only use a single catalog. However, if you want to - scale the Director to many clients, multiple catalogs can be helpful. - Multiple catalogs require a bit more management because in general - you must know what catalog contains what data. Currently, all - Pools are defined in each catalog. This restriction will be removed - in a later release. -\item - \ilink{Messages}{MessagesChapter} -- to define where error and - information messages are to be sent or logged. You may define - multiple different message resources and hence direct particular - classes of messages to different users or locations (files, ...). -\end{itemize} - -\section{The Director Resource} -\label{DirectorResource4} -\index[general]{Director Resource} -\index[general]{Resource!Director} - -The Director resource defines the attributes of the Directors running on the -network. In the current implementation, there is only a single Director -resource, but the final design will contain multiple Directors to maintain -index and media database redundancy. - -\begin{description} - -\item [Director] - \index[dir]{Director} - Start of the Director resource. One and only one director resource must be -supplied. - -\item [Name = \lt{}name\gt{}] - \index[dir]{Name} - \index[dir]{Directive!Name} - The director name used by the system administrator. This directive is -required. - -\item [Description = \lt{}text\gt{}] - \index[dir]{Description} - \index[dir]{Directive!Description} - The text field contains a description of the Director that will be displayed -in the graphical user interface. This directive is optional. - -\item [Password = \lt{}UA-password\gt{}] - \index[dir]{Password} - \index[dir]{Directive!Password} - Specifies the password that must be supplied for the default Bacula - Console to be authorized. The same password must appear in the {\bf - Director} resource of the Console configuration file. For added - security, the password is never passed across the network but instead a - challenge response hash code created with the password. This directive - is required. If you have either {\bf /dev/random} or {\bf bc} on your - machine, Bacula will generate a random password during the configuration - process, otherwise it will be left blank and you must manually supply - it. - - The password is plain text. It is not generated through any special - process but as noted above, it is better to use random text for - security reasons. - -\item [Messages = \lt{}Messages-resource-name\gt{}] - \index[dir]{Messages} - \index[dir]{Directive!Messages} - The messages resource specifies where to deliver Director messages that are - not associated with a specific Job. Most messages are specific to a job and - will be directed to the Messages resource specified by the job. However, - there are a few messages that can occur when no job is running. This - directive is required. - -\item [Working Directory = \lt{}Directory\gt{}] - \index[dir]{Working Directory} - \index[dir]{Directive!Working Directory} - This directive is mandatory and specifies a directory in which the Director - may put its status files. This directory should be used only by Bacula but - may be shared by other Bacula daemons. However, please note, if this - directory is shared with other Bacula daemons (the File daemon and Storage - daemon), you must ensure that the {\bf Name} given to each daemon is - unique so that the temporary filenames used do not collide. By default - the Bacula configure process creates unique daemon names by postfixing them - with -dir, -fd, and -sd. Standard shell expansion of the {\bf - Directory} is done when the configuration file is read so that values such - as {\bf \$HOME} will be properly expanded. This directive is required. - The working directory specified must already exist and be - readable and writable by the Bacula daemon referencing it. - - If you have specified a Director user and/or a Director group on your - ./configure line with {\bf {-}{-}with-dir-user} and/or - {\bf {-}{-}with-dir-group} the Working Directory owner and group will - be set to those values. - -\item [Pid Directory = \lt{}Directory\gt{}] - \index[dir]{Pid Directory} - \index[dir]{Directive!Pid Directory} - This directive is mandatory and specifies a directory in which the Director - may put its process Id file. The process Id file is used to shutdown - Bacula and to prevent multiple copies of Bacula from running simultaneously. - Standard shell expansion of the {\bf Directory} is done when the - configuration file is read so that values such as {\bf \$HOME} will be - properly expanded. - - The PID directory specified must already exist and be - readable and writable by the Bacula daemon referencing it - - Typically on Linux systems, you will set this to: {\bf /var/run}. If you are - not installing Bacula in the system directories, you can use the {\bf Working - Directory} as defined above. This directive is required. - -\item [Scripts Directory = \lt{}Directory\gt{}] - \index[dir]{Scripts Directory} - \index[dir]{Directive!Scripts Directory} - This directive is optional and, if defined, specifies a directory in - which the Director will look for the Python startup script {\bf - DirStartup.py}. This directory may be shared by other Bacula daemons. - Standard shell expansion of the directory is done when the configuration - file is read so that values such as {\bf \$HOME} will be properly - expanded. - -\item [QueryFile = \lt{}Path\gt{}] - \index[dir]{QueryFile} - \index[dir]{Directive!QueryFile} - This directive is mandatory and specifies a directory and file in which - the Director can find the canned SQL statements for the {\bf Query} - command of the Console. Standard shell expansion of the {\bf Path} is - done when the configuration file is read so that values such as {\bf - \$HOME} will be properly expanded. This directive is required. - -\label{DirMaxConJobs} -\item [Maximum Concurrent Jobs = \lt{}number\gt{}] -\index[dir]{Maximum Concurrent Jobs} -\index[dir]{Directive!Maximum Concurrent Jobs} -\index[general]{Simultaneous Jobs} -\index[general]{Concurrent Jobs} - where \lt{}number\gt{} is the maximum number of total Director Jobs that - should run concurrently. The default is set to 1, but you may set it to a - larger number. - - Please note that the Volume format becomes much more complicated with - multiple simultaneous jobs, consequently, restores can take much longer if - Bacula must sort through interleaved volume blocks from multiple simultaneous - jobs. This can be avoided by having each simultaneously running job write to - a different volume or by using data spooling, which will first spool the data - to disk simultaneously, then write each spool file to the volume in - sequence. - - There may also still be some cases where directives such as {\bf Maximum - Volume Jobs} are not properly synchronized with multiple simultaneous jobs - (subtle timing issues can arise), so careful testing is recommended. - - At the current time, there is no configuration parameter set to limit the - number of console connections. A maximum of five simultaneous console - connections are permitted. - -\item [FD Connect Timeout = \lt{}time\gt{}] - \index[dir]{FD Connect Timeout} - \index[dir]{Directive!FD Connect Timeout} - where {\bf time} is the time that the Director should continue - attempting to contact the File daemon to start a job, and after which - the Director will cancel the job. The default is 30 minutes. - -\item [SD Connect Timeout = \lt{}time\gt{}] - \index[dir]{SD Connect Timeout} - \index[dir]{Directive!SD Connect Timeout} - where {\bf time} is the time that the Director should continue - attempting to contact the Storage daemon to start a job, and after which - the Director will cancel the job. The default is 30 minutes. - -\item [DirAddresses = \lt{}IP-address-specification\gt{}] - \index[dir]{DirAddresses} - \index[dir]{Address} - \index[general]{Address} - \index[dir]{Directive!DirAddresses} - Specify the ports and addresses on which the Director daemon will listen - for Bacula Console connections. Probably the simplest way to explain - this is to show an example: - -\footnotesize -\begin{verbatim} - DirAddresses = { - ip = { addr = 1.2.3.4; port = 1205;} - ipv4 = { - addr = 1.2.3.4; port = http;} - ipv6 = { - addr = 1.2.3.4; - port = 1205; - } - ip = { - addr = 1.2.3.4 - port = 1205 - } - ip = { addr = 1.2.3.4 } - ip = { addr = 201:220:222::2 } - ip = { - addr = bluedot.thun.net - } -} -\end{verbatim} -\normalsize - -where ip, ip4, ip6, addr, and port are all keywords. Note, that the address -can be specified as either a dotted quadruple, or IPv6 colon notation, or as -a symbolic name (only in the ip specification). Also, port can be specified -as a number or as the mnemonic value from the /etc/services file. If a port -is not specified, the default will be used. If an ip section is specified, -the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then -only IPv4 resolutions will be permitted, and likewise with ip6. - -Please note that if you use the DirAddresses directive, you must -not use either a DirPort or a DirAddress directive in the same -resource. - -\item [DirPort = \lt{}port-number\gt{}] - \index[dir]{DirPort} - \index[dir]{Directive!DirPort} - Specify the port (a positive integer) on which the Director daemon will - listen for Bacula Console connections. This same port number must be - specified in the Director resource of the Console configuration file. The - default is 9101, so normally this directive need not be specified. This - directive should not be used if you specify DirAddresses (not plural) - directive. - -\item [DirAddress = \lt{}IP-Address\gt{}] - \index[dir]{DirAddress} - \index[dir]{Directive!DirAddress} - This directive is optional, but if it is specified, it will cause the - Director server (for the Console program) to bind to the specified {\bf - IP-Address}, which is either a domain name or an IP address specified as a - dotted quadruple in string or quoted string format. If this directive is not - specified, the Director will bind to any available address (the default). - Note, unlike the DirAddresses specification noted above, this directive only - permits a single address to be specified. This directive should not be used if you - specify a DirAddresses (note plural) directive. - - - -\end{description} - -The following is an example of a valid Director resource definition: - -\footnotesize -\begin{verbatim} -Director { - Name = HeadMan - WorkingDirectory = "$HOME/bacula/bin/working" - Password = UA_password - PidDirectory = "$HOME/bacula/bin/working" - QueryFile = "$HOME/bacula/bin/query.sql" - Messages = Standard -} -\end{verbatim} -\normalsize - -\section{The Job Resource} -\label{JobResource} -\index[general]{Resource!Job} -\index[general]{Job Resource} - -The Job resource defines a Job (Backup, Restore, ...) that Bacula must -perform. Each Job resource definition contains the name of a Client and -a FileSet to backup, the Schedule for the Job, where the data -are to be stored, and what media Pool can be used. In effect, each Job -resource must specify What, Where, How, and When or FileSet, Storage, -Backup/Restore/Level, and Schedule respectively. Note, the FileSet must -be specified for a restore job for historical reasons, but it is no longer used. - -Only a single type ({\bf Backup}, {\bf Restore}, ...) can be specified for any -job. If you want to backup multiple FileSets on the same Client or multiple -Clients, you must define a Job for each one. - -Note, you define only a single Job to do the Full, Differential, and -Incremental backups since the different backup levels are tied together by -a unique Job name. Normally, you will have only one Job per Client, but -if a client has a really huge number of files (more than several million), -you might want to split it into to Jobs each with a different FileSet -covering only part of the total files. - - -\begin{description} - -\item [Job] - \index[dir]{Job} - \index[dir]{Directive!Job} - Start of the Job resource. At least one Job resource is required. - -\item [Name = \lt{}name\gt{}] - \index[dir]{Name} - \index[dir]{Directive!Name} - The Job name. This name can be specified on the {\bf Run} command in the - console program to start a job. If the name contains spaces, it must be - specified between quotes. It is generally a good idea to give your job the - same name as the Client that it will backup. This permits easy - identification of jobs. - - When the job actually runs, the unique Job Name will consist of the name you - specify here followed by the date and time the job was scheduled for - execution. This directive is required. - -\item [Enabled = \lt{}yes|no\gt{}] - \index[dir]{Enable} - \index[dir]{Directive!Enable} - This directive allows you to enable or disable automatic execution - via the scheduler of a Job. - -\item [Type = \lt{}job-type\gt{}] - \index[dir]{Type} - \index[dir]{Directive!Type} - The {\bf Type} directive specifies the Job type, which may be one of the - following: {\bf Backup}, {\bf Restore}, {\bf Verify}, or {\bf Admin}. This - directive is required. Within a particular Job Type, there are also Levels - as discussed in the next item. - -\begin{description} - -\item [Backup] - \index[dir]{Backup} - Run a backup Job. Normally you will have at least one Backup job for each - client you want to save. Normally, unless you turn off cataloging, most all - the important statistics and data concerning files backed up will be placed - in the catalog. - -\item [Restore] - \index[dir]{Restore} - Run a restore Job. Normally, you will specify only one Restore job - which acts as a sort of prototype that you will modify using the console - program in order to perform restores. Although certain basic - information from a Restore job is saved in the catalog, it is very - minimal compared to the information stored for a Backup job -- for - example, no File database entries are generated since no Files are - saved. - - {\bf Restore} jobs cannot be - automatically started by the scheduler as is the case for Backup, Verify - and Admin jobs. To restore files, you must use the {\bf restore} command - in the console. - - -\item [Verify] - \index[dir]{Verify} - Run a verify Job. In general, {\bf verify} jobs permit you to compare the - contents of the catalog to the file system, or to what was backed up. In - addition, to verifying that a tape that was written can be read, you can - also use {\bf verify} as a sort of tripwire intrusion detection. - -\item [Admin] - \index[dir]{Admin} - Run an admin Job. An {\bf Admin} job can be used to periodically run catalog - pruning, if you do not want to do it at the end of each {\bf Backup} Job. - Although an Admin job is recorded in the catalog, very little data is saved. -\end{description} - -\label{Level} - -\item [Level = \lt{}job-level\gt{}] -\index[dir]{Level} -\index[dir]{Directive!Level} - The Level directive specifies the default Job level to be run. Each - different Job Type (Backup, Restore, ...) has a different set of Levels - that can be specified. The Level is normally overridden by a different - value that is specified in the {\bf Schedule} resource. This directive - is not required, but must be specified either by a {\bf Level} directive - or as an override specified in the {\bf Schedule} resource. - -For a {\bf Backup} Job, the Level may be one of the following: - -\begin{description} - -\item [Full] -\index[dir]{Full} - When the Level is set to Full all files in the FileSet whether or not - they have changed will be backed up. - -\item [Incremental] - \index[dir]{Incremental} - When the Level is set to Incremental all files specified in the FileSet - that have changed since the last successful backup of the the same Job - using the same FileSet and Client, will be backed up. If the Director - cannot find a previous valid Full backup then the job will be upgraded - into a Full backup. When the Director looks for a valid backup record - in the catalog database, it looks for a previous Job with: - -\begin{itemize} -\item The same Job name. -\item The same Client name. -\item The same FileSet (any change to the definition of the FileSet such as - adding or deleting a file in the Include or Exclude sections constitutes a - different FileSet. -\item The Job was a Full, Differential, or Incremental backup. -\item The Job terminated normally (i.e. did not fail or was not canceled). -\end{itemize} - - If all the above conditions do not hold, the Director will upgrade the - Incremental to a Full save. Otherwise, the Incremental backup will be - performed as requested. - - The File daemon (Client) decides which files to backup for an - Incremental backup by comparing start time of the prior Job (Full, - Differential, or Incremental) against the time each file was last - "modified" (st\_mtime) and the time its attributes were last - "changed"(st\_ctime). If the file was modified or its attributes - changed on or after this start time, it will then be backed up. - - Some virus scanning software may change st\_ctime while - doing the scan. For example, if the virus scanning program attempts to - reset the access time (st\_atime), which Bacula does not use, it will - cause st\_ctime to change and hence Bacula will backup the file during - an Incremental or Differential backup. In the case of Sophos virus - scanning, you can prevent it from resetting the access time (st\_atime) - and hence changing st\_ctime by using the {\bf \verb:--:no-reset-atime} - option. For other software, please see their manual. - - When Bacula does an Incremental backup, all modified files that are - still on the system are backed up. However, any file that has been - deleted since the last Full backup remains in the Bacula catalog, which - means that if between a Full save and the time you do a restore, some - files are deleted, those deleted files will also be restored. The - deleted files will no longer appear in the catalog after doing another - Full save. However, to remove deleted files from the catalog during an - Incremental backup is quite a time consuming process and not currently - implemented in Bacula. - - In addition, if you move a directory rather than copy it, the files in - it do not have their modification time (st\_mtime) or their attribute - change time (st\_ctime) changed. As a consequence, those files will - probably not be backed up by an Incremental or Differential backup which - depend solely on these time stamps. If you move a directory, and wish - it to be properly backed up, it is generally preferable to copy it, then - delete the original. - -\item [Differential] - \index[dir]{Differential} - When the Level is set to Differential - all files specified in the FileSet that have changed since the last - successful Full backup of the same Job will be backed up. - If the Director cannot find a - valid previous Full backup for the same Job, FileSet, and Client, - backup, then the Differential job will be upgraded into a Full backup. - When the Director looks for a valid Full backup record in the catalog - database, it looks for a previous Job with: - -\begin{itemize} -\item The same Job name. -\item The same Client name. -\item The same FileSet (any change to the definition of the FileSet such as - adding or deleting a file in the Include or Exclude sections constitutes a - different FileSet. -\item The Job was a FULL backup. -\item The Job terminated normally (i.e. did not fail or was not canceled). -\end{itemize} - - If all the above conditions do not hold, the Director will upgrade the - Differential to a Full save. Otherwise, the Differential backup will be - performed as requested. - - The File daemon (Client) decides which files to backup for a - differential backup by comparing the start time of the prior Full backup - Job against the time each file was last "modified" (st\_mtime) and the - time its attributes were last "changed" (st\_ctime). If the file was - modified or its attributes were changed on or after this start time, it - will then be backed up. The start time used is displayed after the {\bf - Since} on the Job report. In rare cases, using the start time of the - prior backup may cause some files to be backed up twice, but it ensures - that no change is missed. As with the Incremental option, you should - ensure that the clocks on your server and client are synchronized or as - close as possible to avoid the possibility of a file being skipped. - Note, on versions 1.33 or greater Bacula automatically makes the - necessary adjustments to the time between the server and the client so - that the times Bacula uses are synchronized. - - When Bacula does a Differential backup, all modified files that are - still on the system are backed up. However, any file that has been - deleted since the last Full backup remains in the Bacula catalog, which - means that if between a Full save and the time you do a restore, some - files are deleted, those deleted files will also be restored. The - deleted files will no longer appear in the catalog after doing another - Full save. However, to remove deleted files from the catalog during a - Differential backup is quite a time consuming process and not currently - implemented in Bacula. It is, however, a planned future feature. - - As noted above, if you move a directory rather than copy it, the - files in it do not have their modification time (st\_mtime) or - their attribute change time (st\_ctime) changed. As a - consequence, those files will probably not be backed up by an - Incremental or Differential backup which depend solely on these - time stamps. If you move a directory, and wish it to be - properly backed up, it is generally preferable to copy it, then - delete the original. Alternatively, you can move the directory, then - use the {\bf touch} program to update the timestamps. - - Every once and a while, someone asks why we need Differential - backups as long as Incremental backups pickup all changed files. - There are possibly many answers to this question, but the one - that is the most important for me is that a Differential backup - effectively merges - all the Incremental and Differential backups since the last Full backup - into a single Differential backup. This has two effects: 1. It gives - some redundancy since the old backups could be used if the merged backup - cannot be read. 2. More importantly, it reduces the number of Volumes - that are needed to do a restore effectively eliminating the need to read - all the volumes on which the preceding Incremental and Differential - backups since the last Full are done. - -\end{description} - -For a {\bf Restore} Job, no level needs to be specified. - -For a {\bf Verify} Job, the Level may be one of the following: - -\begin{description} - -\item [InitCatalog] -\index[dir]{InitCatalog} - does a scan of the specified {\bf FileSet} and stores the file - attributes in the Catalog database. Since no file data is saved, you - might ask why you would want to do this. It turns out to be a very - simple and easy way to have a {\bf Tripwire} like feature using {\bf - Bacula}. In other words, it allows you to save the state of a set of - files defined by the {\bf FileSet} and later check to see if those files - have been modified or deleted and if any new files have been added. - This can be used to detect system intrusion. Typically you would - specify a {\bf FileSet} that contains the set of system files that - should not change (e.g. /sbin, /boot, /lib, /bin, ...). Normally, you - run the {\bf InitCatalog} level verify one time when your system is - first setup, and then once again after each modification (upgrade) to - your system. Thereafter, when your want to check the state of your - system files, you use a {\bf Verify} {\bf level = Catalog}. This - compares the results of your {\bf InitCatalog} with the current state of - the files. - -\item [Catalog] -\index[dir]{Catalog} - Compares the current state of the files against the state previously - saved during an {\bf InitCatalog}. Any discrepancies are reported. The - items reported are determined by the {\bf verify} options specified on - the {\bf Include} directive in the specified {\bf FileSet} (see the {\bf - FileSet} resource below for more details). Typically this command will - be run once a day (or night) to check for any changes to your system - files. - - Please note! If you run two Verify Catalog jobs on the same client at - the same time, the results will certainly be incorrect. This is because - Verify Catalog modifies the Catalog database while running in order to - track new files. - -\item [VolumeToCatalog] -\index[dir]{VolumeToCatalog} - This level causes Bacula to read the file attribute data written to the - Volume from the last Job. The file attribute data are compared to the - values saved in the Catalog database and any differences are reported. - This is similar to the {\bf Catalog} level except that instead of - comparing the disk file attributes to the catalog database, the - attribute data written to the Volume is read and compared to the catalog - database. Although the attribute data including the signatures (MD5 or - SHA1) are compared, the actual file data is not compared (it is not in - the catalog). - - Please note! If you run two Verify VolumeToCatalog jobs on the same - client at the same time, the results will certainly be incorrect. This - is because the Verify VolumeToCatalog modifies the Catalog database - while running. - -\item [DiskToCatalog] -\index[dir]{DiskToCatalog} - This level causes Bacula to read the files as they currently are on - disk, and to compare the current file attributes with the attributes - saved in the catalog from the last backup for the job specified on the - {\bf VerifyJob} directive. This level differs from the {\bf Catalog} - level described above by the fact that it doesn't compare against a - previous Verify job but against a previous backup. When you run this - level, you must supply the verify options on your Include statements. - Those options determine what attribute fields are compared. - - This command can be very useful if you have disk problems because it - will compare the current state of your disk against the last successful - backup, which may be several jobs. - - Note, the current implementation (1.32c) does not identify files that - have been deleted. -\end{description} - -\item [Verify Job = \lt{}Job-Resource-Name\gt{}] - \index[dir]{Verify Job} - \index[dir]{Directive!Verify Job} - If you run a verify job without this directive, the last job run will be - compared with the catalog, which means that you must immediately follow - a backup by a verify command. If you specify a {\bf Verify Job} Bacula - will find the last job with that name that ran. This permits you to run - all your backups, then run Verify jobs on those that you wish to be - verified (most often a {\bf VolumeToCatalog}) so that the tape just - written is re-read. - -\item [JobDefs = \lt{}JobDefs-Resource-Name\gt{}] -\index[dir]{JobDefs} -\index[dir]{Directive!JobDefs} - If a JobDefs-Resource-Name is specified, all the values contained in the - named JobDefs resource will be used as the defaults for the current Job. - Any value that you explicitly define in the current Job resource, will - override any defaults specified in the JobDefs resource. The use of - this directive permits writing much more compact Job resources where the - bulk of the directives are defined in one or more JobDefs. This is - particularly useful if you have many similar Jobs but with minor - variations such as different Clients. A simple example of the use of - JobDefs is provided in the default bacula-dir.conf file. - -\item [Bootstrap = \lt{}bootstrap-file\gt{}] -\index[dir]{Bootstrap} -\index[dir]{Directive!Bootstrap} - The Bootstrap directive specifies a bootstrap file that, if provided, - will be used during {\bf Restore} Jobs and is ignored in other Job - types. The {\bf bootstrap} file contains the list of tapes to be used - in a restore Job as well as which files are to be restored. - Specification of this directive is optional, and if specified, it is - used only for a restore job. In addition, when running a Restore job - from the console, this value can be changed. - - If you use the {\bf Restore} command in the Console program, to start a - restore job, the {\bf bootstrap} file will be created automatically from - the files you select to be restored. - - For additional details of the {\bf bootstrap} file, please see - \ilink{Restoring Files with the Bootstrap File}{BootstrapChapter} chapter - of this manual. - -\label{writebootstrap} -\item [Write Bootstrap = \lt{}bootstrap-file-specification\gt{}] -\index[dir]{Write Bootstrap} -\index[dir]{Directive!Write Bootstrap} - The {\bf writebootstrap} directive specifies a file name where Bacula - will write a {\bf bootstrap} file for each Backup job run. This - directive applies only to Backup Jobs. If the Backup job is a Full - save, Bacula will erase any current contents of the specified file - before writing the bootstrap records. If the Job is an Incremental - or Differential - save, Bacula will append the current bootstrap record to the end of the - file. - - Using this feature, permits you to constantly have a bootstrap file that - can recover the current state of your system. Normally, the file - specified should be a mounted drive on another machine, so that if your - hard disk is lost, you will immediately have a bootstrap record - available. Alternatively, you should copy the bootstrap file to another - machine after it is updated. Note, it is a good idea to write a separate - bootstrap file for each Job backed up including the job that backs up - your catalog database. - - If the {\bf bootstrap-file-specification} begins with a vertical bar - (|), Bacula will use the specification as the name of a program to which - it will pipe the bootstrap record. It could for example be a shell - script that emails you the bootstrap record. - - On versions 1.39.22 or greater, before opening the file or executing the - specified command, Bacula performs - \ilink{character substitution}{character substitution} like in RunScript - directive. To automatically manage your bootstrap files, you can use - this in your {\bf JobDefs} resources: -\begin{verbatim} -JobDefs { - Write Bootstrap = "%c_%n.bsr" - ... -} -\end{verbatim} - - For more details on using this file, please see the chapter entitled - \ilink{The Bootstrap File}{BootstrapChapter} of this manual. - -\item [Client = \lt{}client-resource-name\gt{}] -\index[dir]{Client} -\index[dir]{Directive!Client} - The Client directive specifies the Client (File daemon) that will be used in - the current Job. Only a single Client may be specified in any one Job. The - Client runs on the machine to be backed up, and sends the requested files to - the Storage daemon for backup, or receives them when restoring. For - additional details, see the - \ilink{Client Resource section}{ClientResource2} of this chapter. - This directive is required. - -\item [FileSet = \lt{}FileSet-resource-name\gt{}] -\index[dir]{FileSet} -\index[dir]{FileSet} - The FileSet directive specifies the FileSet that will be used in the - current Job. The FileSet specifies which directories (or files) are to - be backed up, and what options to use (e.g. compression, ...). Only a - single FileSet resource may be specified in any one Job. For additional - details, see the \ilink{FileSet Resource section}{FileSetResource} of - this chapter. This directive is required. - -\item [Messages = \lt{}messages-resource-name\gt{}] -\index[dir]{Messages} -\index[dir]{Directive!Messages} - The Messages directive defines what Messages resource should be used for - this job, and thus how and where the various messages are to be - delivered. For example, you can direct some messages to a log file, and - others can be sent by email. For additional details, see the - \ilink{Messages Resource}{MessagesChapter} Chapter of this manual. This - directive is required. - -\item [Pool = \lt{}pool-resource-name\gt{}] -\index[dir]{Pool} -\index[dir]{Directive!Pool} - The Pool directive defines the pool of Volumes where your data can be - backed up. Many Bacula installations will use only the {\bf Default} - pool. However, if you want to specify a different set of Volumes for - different Clients or different Jobs, you will probably want to use - Pools. For additional details, see the \ilink{Pool Resource - section}{PoolResource} of this chapter. This directive is required. - -\item [Full Backup Pool = \lt{}pool-resource-name\gt{}] -\index[dir]{Full Backup Pool} -\index[dir]{Directive!Full Backup Pool} - The {\it Full Backup Pool} specifies a Pool to be used for Full backups. - It will override any Pool specification during a Full backup. This - directive is optional. - -\item [Differential Backup Pool = \lt{}pool-resource-name\gt{}] -\index[dir]{Differential Backup Pool} -\index[dir]{Directive!Differential Backup Pool} - The {\it Differential Backup Pool} specifies a Pool to be used for - Differential backups. It will override any Pool specification during a - Differential backup. This directive is optional. - -\item [Incremental Backup Pool = \lt{}pool-resource-name\gt{}] -\index[dir]{Incremental Backup Pool} -\index[dir]{Directive!Incremental Backup Pool} - The {\it Incremental Backup Pool} specifies a Pool to be used for - Incremental backups. It will override any Pool specification during an - Incremental backup. This directive is optional. - -\item [Schedule = \lt{}schedule-name\gt{}] -\index[dir]{Schedule} -\index[dir]{Directive!Schedule} - The Schedule directive defines what schedule is to be used for the Job. - The schedule in turn determines when the Job will be automatically - started and what Job level (i.e. Full, Incremental, ...) is to be run. - This directive is optional, and if left out, the Job can only be started - manually using the Console program. Although you may specify only a - single Schedule resource for any one job, the Schedule resource may - contain multiple {\bf Run} directives, which allow you to run the Job at - many different times, and each {\bf run} directive permits overriding - the default Job Level Pool, Storage, and Messages resources. This gives - considerable flexibility in what can be done with a single Job. For - additional details, see the \ilink{Schedule Resource - Chapter}{ScheduleResource} of this manual. - - -\item [Storage = \lt{}storage-resource-name\gt{}] -\index[dir]{Storage} -\index[dir]{Directive!Storage} - The Storage directive defines the name of the storage services where you - want to backup the FileSet data. For additional details, see the - \ilink{Storage Resource Chapter}{StorageResource2} of this manual. - The Storage resource may also be specified in the Job's Pool resource, - in which case the value in the Pool resource overrides any value - in the Job. This Storage resource definition is not required by either - the Job resource or in the Pool, but it must be specified in - one or the other, if not an error will result. - -\item [Max Start Delay = \lt{}time\gt{}] -\index[dir]{Max Start Delay} -\index[dir]{Directive!Max Start Delay} - The time specifies the maximum delay between the scheduled time and the - actual start time for the Job. For example, a job can be scheduled to - run at 1:00am, but because other jobs are running, it may wait to run. - If the delay is set to 3600 (one hour) and the job has not begun to run - by 2:00am, the job will be canceled. This can be useful, for example, - to prevent jobs from running during day time hours. The default is 0 - which indicates no limit. - -\item [Max Run Time = \lt{}time\gt{}] -\index[dir]{Max Run Time} -\index[dir]{Directive!Max Run Time} - The time specifies the maximum allowed time that a job may run, counted - from when the job starts, ({\bf not} necessarily the same as when the - job was scheduled). This directive is implemented in version 1.33 and - later. - -\item [Max Wait Time = \lt{}time\gt{}] -\index[dir]{Max Wait Time} -\index[dir]{Directive!Max Wait Time} - The time specifies the maximum allowed time that a job may block waiting - for a resource (such as waiting for a tape to be mounted, or waiting for - the storage or file daemons to perform their duties), counted from the - when the job starts, ({\bf not} necessarily the same as when the job was - scheduled). This directive is implemented only in version 1.33 and - later. - -\item [Incremental Max Wait Time = \lt{}time\gt{}] -\index[dir]{Incremental Max Wait Time} -\index[dir]{Directive!Incremental Max Wait Time} - The time specifies the maximum allowed time that an Incremental backup - job may block waiting for a resource (such as waiting for a tape to be - mounted, or waiting for the storage or file daemons to perform their - duties), counted from the when the job starts, ({\bf not} necessarily - the same as when the job was scheduled). Please note that if there is a - {\bf Max Wait Time} it may also be applied to the job. - -\item [Differential Max Wait Time = \lt{}time\gt{}] -\index[dir]{Differential Max Wait Time} -\index[dir]{Directive!Differential Max Wait Time} - The time specifies the maximum allowed time that a Differential backup - job may block waiting for a resource (such as waiting for a tape to be - mounted, or waiting for the storage or file daemons to perform their - duties), counted from the when the job starts, ({\bf not} necessarily - the same as when the job was scheduled). Please note that if there is a - {\bf Max Wait Time} it may also be applied to the job. - -\label{PreferMountedVolumes} -\item [Prefer Mounted Volumes = \lt{}yes|no\gt{}] -\index[dir]{Prefer Mounted Volumes} -\index[dir]{Directive!Prefer Mounted Volumes} - If the Prefer Mounted Volumes directive is set to {\bf yes} (default - yes), the Storage daemon is requested to select either an Autochanger or - a drive with a valid Volume already mounted in preference to a drive - that is not ready. This means that all jobs will attempt to append - to the same Volume (providing the Volume is appropriate -- right Pool, - ... for that job). If no drive with a suitable Volume is available, it - will select the first available drive. Note, any Volume that has - been requested to be mounted, will be considered valid as a mounted - volume by another job. This if multiple jobs start at the same time - and they all prefer mounted volumes, the first job will request the - mount, and the other jobs will use the same volume. - - If the directive is set to {\bf no}, the Storage daemon will prefer - finding an unused drive, otherwise, each job started will append to the - same Volume (assuming the Pool is the same for all jobs). Setting - Prefer Mounted Volumes to no can be useful for those sites - with multiple drive autochangers that prefer to maximize backup - throughput at the expense of using additional drives and Volumes. - This means that the job will prefer to use an unused drive rather - than use a drive that is already in use. - -\item [Prune Jobs = \lt{}yes|no\gt{}] -\index[dir]{Prune Jobs} -\index[dir]{Directive!Prune Jobs} - Normally, pruning of Jobs from the Catalog is specified on a Client by - Client basis in the Client resource with the {\bf AutoPrune} directive. - If this directive is specified (not normally) and the value is {\bf - yes}, it will override the value specified in the Client resource. The - default is {\bf no}. - - -\item [Prune Files = \lt{}yes|no\gt{}] -\index[dir]{Prune Files} -\index[dir]{Directive!Prune Files} - Normally, pruning of Files from the Catalog is specified on a Client by - Client basis in the Client resource with the {\bf AutoPrune} directive. - If this directive is specified (not normally) and the value is {\bf - yes}, it will override the value specified in the Client resource. The - default is {\bf no}. - -\item [Prune Volumes = \lt{}yes|no\gt{}] -\index[dir]{Prune Volumes} -\index[dir]{Directive!Prune Volumes} - Normally, pruning of Volumes from the Catalog is specified on a Client - by Client basis in the Client resource with the {\bf AutoPrune} - directive. If this directive is specified (not normally) and the value - is {\bf yes}, it will override the value specified in the Client - resource. The default is {\bf no}. - -\item [RunScript \{\lt{}body-of-runscript\gt{}\}] - \index[dir]{RunScript} - \index[dir]{Directive!Run Script} - - This directive is implemented in version 1.39.22 and later. - The RunScript directive behaves like a resource in that it - requires opening and closing braces around a number of directives - that make up the body of the runscript. - - The specified {\bf Command} (see below for details) is run as an - external program prior or after the current Job. This is optional. - - You can use following options may be specified in the body - of the runscript:\\ - -\begin{tabular}{|c|c|c|l} -Options & Value & Default & Information \\ -\hline -\hline -Runs On Success & Yes/No & {\it Yes} & Run command if JobStatus is successful\\ -\hline -Runs On Failure & Yes/No & {\it No} & Run command if JobStatus isn't successful\\ -\hline -Runs On Client & Yes/No & {\it Yes} & Run command on client\\ -\hline -Runs When & Before|After|Always & {\it Never} & When run commands\\ -\hline -Fail Job On Error & Yes/No & {\it Yes} & Fail job if script returns - something different from 0 \\ -\hline -Command & & & Path to your script\\ -\hline -\end{tabular} - \\ - - Any output sent by the command to standard output will be included in the - Bacula job report. The command string must be a valid program name or name - of a shell script. - - In addition, the command string is parsed then fed to the OS, - which means that the path will be searched to execute your specified - command, but there is no shell interpretation, as a consequence, if you - invoke complicated commands or want any shell features such as redirection - or piping, you must call a shell script and do it inside that script. - - Before submitting the specified command to the operating system, Bacula - performs character substitution of the following characters: - -\label{character substitution} -\footnotesize -\begin{verbatim} - %% = % - %c = Client's name - %d = Director's name - %e = Job Exit Status - %i = JobId - %j = Unique Job id - %l = Job Level - %n = Job name - %s = Since time - %t = Job type (Backup, ...) - %v = Volume name - -\end{verbatim} -\normalsize - -The Job Exit Status code \%e edits the following values: - -\index[dir]{Exit Status} -\begin{itemize} -\item OK -\item Error -\item Fatal Error -\item Canceled -\item Differences -\item Unknown term code -\end{itemize} - - Thus if you edit it on a command line, you will need to enclose - it within some sort of quotes. - - -You can use these following shortcuts:\\ - -\begin{tabular}{|c|c|c|c|c|c} -Keyword & RunsOnSuccess & RunsOnFailure & FailJobOnError & Runs On Client & RunsWhen \\ -\hline -Run Before Job & & & Yes & No & Before \\ -\hline -Run After Job & Yes & No & & No & After \\ -\hline -Run After Failed Job & No & Yes & & No & After \\ -\hline -Client Run Before Job & & & Yes & Yes & Before \\ -\hline -Client Run After Job & Yes & No & & Yes & After \\ -\end{tabular} - -Examples: -\begin{verbatim} -RunScript { - RunsWhen = Before - FailJobOnError = No - Command = "/etc/init.d/apache stop" -} - -RunScript { - RunsWhen = After - RunsOnFailure = yes - Command = "/etc/init.d/apache start" -} -\end{verbatim} - - {\bf Special Windows Considerations} - - In addition, for a Windows client on version 1.33 and above, please take - note that you must ensure a correct path to your script. The script or - program can be a .com, .exe or a .bat file. If you just put the program - name in then Bacula will search using the same rules that cmd.exe uses - (current directory, Bacula bin directory, and PATH). It will even try the - different extensions in the same order as cmd.exe. - The command can be anything that cmd.exe or command.com will recognize - as an executable file. - - However, if you have slashes in the program name then Bacula figures you - are fully specifying the name, so you must also explicitly add the three - character extension. - - The command is run in a Win32 environment, so Unix like commands will not - work unless you have installed and properly configured Cygwin in addition - to and separately from Bacula. - - The System \%Path\% will be searched for the command. (under the - environment variable dialog you have have both System Environment and - User Environment, we believe that only the System environment will be - available to bacula-fd, if it is running as a service.) - - System environment variables can be referenced with \%var\% and - used as either part of the command name or arguments. - - So if you have a script in the Bacula\\bin directory then the following lines - should work fine: - -\footnotesize -\begin{verbatim} - Client Run Before Job = systemstate -or - Client Run Before Job = systemstate.bat -or - Client Run Before Job = "systemstate" -or - Client Run Before Job = "systemstate.bat" -or - ClientRunBeforeJob = "\"C:/Program Files/Bacula/systemstate.bat\"" -\end{verbatim} -\normalsize - -The outer set of quotes is removed when the configuration file is parsed. -You need to escape the inner quotes so that they are there when the code -that parses the command line for execution runs so it can tell what the -program name is. - - -\footnotesize -\begin{verbatim} -ClientRunBeforeJob = "\"C:/Program Files/Software - Vendor/Executable\" /arg1 /arg2 \"foo bar\"" -\end{verbatim} -\normalsize - - The special characters -\begin{verbatim} -&<>()@^| -\end{verbatim} - will need to be quoted, - if they are part of a filename or argument. - - If someone is logged in, a blank "command" window running the commands - will be present during the execution of the command. - - Some Suggestions from Phil Stracchino for running on Win32 machines with - the native Win32 File daemon: - - \begin{enumerate} - \item You might want the ClientRunBeforeJob directive to specify a .bat - file which runs the actual client-side commands, rather than trying - to run (for example) regedit /e directly. - \item The batch file should explicitly 'exit 0' on successful completion. - \item The path to the batch file should be specified in Unix form: - - ClientRunBeforeJob = "c:/bacula/bin/systemstate.bat" - - rather than DOS/Windows form: - - ClientRunBeforeJob = - -"c:\textbackslash{}bacula\textbackslash{}bin\textbackslash{}systemstate.bat" - INCORRECT - \end{enumerate} - -For Win32, please note that there are certain limitations: - -ClientRunBeforeJob = "C:/Program Files/Bacula/bin/pre-exec.bat" - -Lines like the above do not work because there are limitations of -cmd.exe that is used to execute the command. -Bacula prefixes the string you supply with {\bf cmd.exe /c }. To test that -your command works you should type {\bf cmd /c "C:/Program Files/test.exe"} at a -cmd prompt and see what happens. Once the command is correct insert a -backslash (\textbackslash{}) before each double quote ("), and -then put quotes around the whole thing when putting it in -the director's .conf file. You either need to have only one set of quotes -or else use the short name and don't put quotes around the command path. - -Below is the output from cmd's help as it relates to the command line -passed to the /c option. - - - If /C or /K is specified, then the remainder of the command line after - the switch is processed as a command line, where the following logic is - used to process quote (") characters: - -\begin{enumerate} -\item - If all of the following conditions are met, then quote characters - on the command line are preserved: - \begin{itemize} - \item no /S switch. - \item exactly two quote characters. - \item no special characters between the two quote characters, - where special is one of: -\begin{verbatim} -&<>()@^| -\end{verbatim} - \item there are one or more whitespace characters between the - the two quote characters. - \item the string between the two quote characters is the name - of an executable file. - \end{itemize} - -\item Otherwise, old behavior is to see if the first character is - a quote character and if so, strip the leading character and - remove the last quote character on the command line, preserving - any text after the last quote character. - -\end{enumerate} - - -The following example of the use of the Client Run Before Job directive was -submitted by a user:\\ -You could write a shell script to back up a DB2 database to a FIFO. The shell -script is: - -\footnotesize -\begin{verbatim} - #!/bin/sh - # ===== backupdb.sh - DIR=/u01/mercuryd - - mkfifo $DIR/dbpipe - db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING & - sleep 1 -\end{verbatim} -\normalsize - -The following line in the Job resource in the bacula-dir.conf file: -\footnotesize -\begin{verbatim} - Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t' -'%l'\"" -\end{verbatim} -\normalsize - -When the job is run, you will get messages from the output of the script -stating that the backup has started. Even though the command being run is -backgrounded with \&, the job will block until the "db2 BACKUP DATABASE" -command, thus the backup stalls. - -To remedy this situation, the "db2 BACKUP DATABASE" line should be changed to -the following: - -\footnotesize -\begin{verbatim} - db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log -2>&1 < /dev/null & -\end{verbatim} -\normalsize - -It is important to redirect the input and outputs of a backgrounded command to -/dev/null to prevent the script from blocking. - -\item [Run Before Job = \lt{}command\gt{}] -\index[dir]{Run Before Job} -\index[dir]{Directive!Run Before Job} -\index[dir]{Directive!Run Before Job} -The specified {\bf command} is run as an external program prior to running the -current Job. This directive is not required, but if it is defined, and if the -exit code of the program run is non-zero, the current Bacula job will be -canceled. - -\begin{verbatim} -Run Before Job = "echo test" -\end{verbatim} - it's equivalent to : -\begin{verbatim} -RunScript { - Command = "echo test" - RunsOnClient = No - RunsWhen = Before -} -\end{verbatim} - - Lutz Kittler has pointed out that using the RunBeforeJob directive can be a - simple way to modify your schedules during a holiday. For example, suppose - that you normally do Full backups on Fridays, but Thursday and Friday are - holidays. To avoid having to change tapes between Thursday and Friday when - no one is in the office, you can create a RunBeforeJob that returns a - non-zero status on Thursday and zero on all other days. That way, the - Thursday job will not run, and on Friday the tape you inserted on Wednesday - before leaving will be used. - -\item [Run After Job = \lt{}command\gt{}] -\index[dir]{Run After Job} -\index[dir]{Directive!Run After Job} - The specified {\bf command} is run as an external program if the current - job terminates normally (without error or without being canceled). This - directive is not required. If the exit code of the program run is - non-zero, Bacula will print a warning message. Before submitting the - specified command to the operating system, Bacula performs character - substitution as described above for the {\bf RunScript} directive. - - An example of the use of this directive is given in the - \ilink{Tips Chapter}{JobNotification} of this manual. - - See the {\bf Run After Failed Job} if you - want to run a script after the job has terminated with any - non-normal status. - -\item [Run After Failed Job = \lt{}command\gt{}] -\index[dir]{Run After Job} -\index[dir]{Directive!Run After Job} - The specified {\bf command} is run as an external program after the current - job terminates with any error status. This directive is not required. The - command string must be a valid program name or name of a shell script. If - the exit code of the program run is non-zero, Bacula will print a - warning message. Before submitting the specified command to the - operating system, Bacula performs character substitution as described above - for the {\bf RunScript} directive. Note, if you wish that your script - will run regardless of the exit status of the Job, you can use this : -\begin{verbatim} -RunScript { - Command = "echo test" - RunsWhen = After - RunsOnFailure = yes - RunsOnClient = no - RunsOnSuccess = yes # default, you can drop this line -} -\end{verbatim} - - An example of the use of this directive is given in the - \ilink{Tips Chapter}{JobNotification} of this manual. - - -\item [Client Run Before Job = \lt{}command\gt{}] -\index[dir]{Client Run Before Job} -\index[dir]{Directive!Client Run Before Job} - This directive is the same as {\bf Run Before Job} except that the - program is run on the client machine. The same restrictions apply to - Unix systems as noted above for the {\bf RunScript}. - -\item [Client Run After Job = \lt{}command\gt{}] - \index[dir]{Client Run After Job} - \index[dir]{Directive!Client Run After Job} - The specified {\bf command} is run on the client machine as soon - as data spooling is complete in order to allow restarting applications - on the client as soon as possible. . - - Note, please see the notes above in {\bf RunScript} - concerning Windows clients. - -\item [Rerun Failed Levels = \lt{}yes|no\gt{}] - \index[dir]{Rerun Failed Levels} - \index[dir]{Directive!Rerun Failed Levels} - If this directive is set to {\bf yes} (default no), and Bacula detects that - a previous job at a higher level (i.e. Full or Differential) has failed, - the current job level will be upgraded to the higher level. This is - particularly useful for Laptops where they may often be unreachable, and if - a prior Full save has failed, you wish the very next backup to be a Full - save rather than whatever level it is started as. - - There are several points that must be taken into account when using this - directive: first, a failed job is defined as one that has not terminated - normally, which includes any running job of the same name (you need to - ensure that two jobs of the same name do not run simultaneously); - secondly, the {\bf Ignore FileSet Changes} directive is not considered - when checking for failed levels, which means that any FileSet change will - trigger a rerun. - -\item [Spool Data = \lt{}yes|no\gt{}] - \index[dir]{Spool Data} - \index[dir]{Directive!Spool Data} - - If this directive is set to {\bf yes} (default no), the Storage daemon will - be requested to spool the data for this Job to disk rather than write it - directly to tape. Once all the data arrives or the spool files' maximum sizes - are reached, the data will be despooled and written to tape. Spooling data - prevents tape shoe-shine (start and stop) during - Incremental saves. If you are writing to a disk file using this option - will probably just slow down the backup jobs. - - NOTE: When this directive is set to yes, Spool Attributes is also - automatically set to yes. - -\item [Spool Attributes = \lt{}yes|no\gt{}] - \index[dir]{Spool Attributes} - \index[dir]{Directive!Spool Attributes} - \index[dir]{slow} - \index[general]{slow} - \index[dir]{Backups!slow} - \index[general]{Backups!slow} - The default is set to {\bf no}, which means that the File attributes are - sent by the Storage daemon to the Director as they are stored on tape. - However, if you want to avoid the possibility that database updates will - slow down writing to the tape, you may want to set the value to {\bf - yes}, in which case the Storage daemon will buffer the File attributes - and Storage coordinates to a temporary file in the Working Directory, - then when writing the Job data to the tape is completed, the attributes - and storage coordinates will be sent to the Director. - - NOTE: When Spool Data is set to yes, Spool Attributes is also - automatically set to yes. - -\item [Where = \lt{}directory\gt{}] - \index[dir]{Where} - \index[dir]{Directive!Where} - This directive applies only to a Restore job and specifies a prefix to - the directory name of all files being restored. This permits files to - be restored in a different location from which they were saved. If {\bf - Where} is not specified or is set to backslash ({\bf /}), the files will - be restored to their original location. By default, we have set {\bf - Where} in the example configuration files to be {\bf - /tmp/bacula-restores}. This is to prevent accidental overwriting of - your files. - -\item [Add Prefix = \lt{}directory\gt{}] - \label{confaddprefix} - \index[dir]{AddPrefix} - \index[dir]{Directive!AddPrefix} - This directive applies only to a Restore job and specifies a prefix to the - directory name of all files being restored. This will use \ilink{File - Relocation}{filerelocation} feature implemented in Bacula 2.1.8 or later. - -\item [Add Suffix = \lt{}extention\gt{}] - \index[dir]{AddSuffix} - \index[dir]{Directive!AddSuffix} - This directive applies only to a Restore job and specifies a suffix to all - files being restored. This will use \ilink{File Relocation}{filerelocation} - feature implemented in Bacula 2.1.8 or later. - - Using \texttt{Add Suffix=.old}, \texttt{/etc/passwd} will be restored to - \texttt{/etc/passwsd.old} - -\item [Strip Prefix = \lt{}directory\gt{}] - \index[dir]{StripPrefix} - \index[dir]{Directive!StripPrefix} - This directive applies only to a Restore job and specifies a prefix to remove - from the directory name of all files being restored. This will use the - \ilink{File Relocation}{filerelocation} feature implemented in Bacula 2.1.8 - or later. - - Using \texttt{Strip Prefix=/etc}, \texttt{/etc/passwd} will be restored to - \texttt{/passwd} - - Under Windows, if you want to restore \texttt{c:/files} to \texttt{d:/files}, - you can use : - -\begin{verbatim} - Strip Prefix = c: - Add Prefix = d: -\end{verbatim} - -\item [RegexWhere = \lt{}expressions\gt{}] - \index[dir]{RegexWhere} - \index[dir]{Directive!RegexWhere} - This directive applies only to a Restore job and specifies a regex filename - manipulation of all files being restored. This will use \ilink{File - Relocation}{filerelocation} feature implemented in Bacula 2.1.8 or later. - - For more informations about how use this option, see - \ilink{this}{useregexwhere}. - -\item [Replace = \lt{}replace-option\gt{}] - \index[dir]{Replace} - \index[dir]{Directive!Replace} - This directive applies only to a Restore job and specifies what happens - when Bacula wants to restore a file or directory that already exists. - You have the following options for {\bf replace-option}: - -\begin{description} - -\item [always] - \index[dir]{always} - when the file to be restored already exists, it is deleted and then - replaced by the copy that was backed up. - -\item [ifnewer] -\index[dir]{ifnewer} - if the backed up file (on tape) is newer than the existing file, the - existing file is deleted and replaced by the back up. - -\item [ifolder] - \index[dir]{ifolder} - if the backed up file (on tape) is older than the existing file, the - existing file is deleted and replaced by the back up. - -\item [never] - \index[dir]{never} - if the backed up file already exists, Bacula skips restoring this file. -\end{description} - -\item [Prefix Links=\lt{}yes|no\gt{}] - \index[dir]{Prefix Links} - \index[dir]{Directive!Prefix Links} - If a {\bf Where} path prefix is specified for a recovery job, apply it - to absolute links as well. The default is {\bf No}. When set to {\bf - Yes} then while restoring files to an alternate directory, any absolute - soft links will also be modified to point to the new alternate - directory. Normally this is what is desired -- i.e. everything is self - consistent. However, if you wish to later move the files to their - original locations, all files linked with absolute names will be broken. - -\item [Maximum Concurrent Jobs = \lt{}number\gt{}] - \index[dir]{Maximum Concurrent Jobs} - \index[dir]{Directive!Maximum Concurrent Jobs} - where \lt{}number\gt{} is the maximum number of Jobs from the current - Job resource that can run concurrently. Note, this directive limits - only Jobs with the same name as the resource in which it appears. Any - other restrictions on the maximum concurrent jobs such as in the - Director, Client, or Storage resources will also apply in addition to - the limit specified here. The default is set to 1, but you may set it - to a larger number. We strongly recommend that you read the WARNING - documented under \ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the - Director's resource. - -\item [Reschedule On Error = \lt{}yes|no\gt{}] - \index[dir]{Reschedule On Error} - \index[dir]{Directive!Reschedule On Error} - If this directive is enabled, and the job terminates in error, the job - will be rescheduled as determined by the {\bf Reschedule Interval} and - {\bf Reschedule Times} directives. If you cancel the job, it will not - be rescheduled. The default is {\bf no} (i.e. the job will not be - rescheduled). - - This specification can be useful for portables, laptops, or other - machines that are not always connected to the network or switched on. - -\item [Reschedule Interval = \lt{}time-specification\gt{}] - \index[dir]{Reschedule Interval} - \index[dir]{Directive!Reschedule Interval} - If you have specified {\bf Reschedule On Error = yes} and the job - terminates in error, it will be rescheduled after the interval of time - specified by {\bf time-specification}. See \ilink{the time - specification formats}{Time} in the Configure chapter for details of - time specifications. If no interval is specified, the job will not be - rescheduled on error. - -\item [Reschedule Times = \lt{}count\gt{}] - \index[dir]{Reschedule Times} - \index[dir]{Directive!Reschedule Times} - This directive specifies the maximum number of times to reschedule the - job. If it is set to zero (the default) the job will be rescheduled an - indefinite number of times. - -\item [Run = \lt{}job-name\gt{}] - \index[dir]{Run} - \index[dir]{Directive!Run} - \index[dir]{Clone a Job} - The Run directive (not to be confused with the Run option in a - Schedule) allows you to start other jobs or to clone jobs. By using the - cloning keywords (see below), you can backup - the same data (or almost the same data) to two or more drives - at the same time. The {\bf job-name} is normally the same name - as the current Job resource (thus creating a clone). However, it - may be any Job name, so one job may start other related jobs. - - The part after the equal sign must be enclosed in double quotes, - and can contain any string or set of options (overrides) that you - can specify when entering the Run command from the console. For - example {\bf storage=DDS-4 ...}. In addition, there are two special - keywords that permit you to clone the current job. They are {\bf level=\%l} - and {\bf since=\%s}. The \%l in the level keyword permits - entering the actual level of the current job and the \%s in the since - keyword permits putting the same time for comparison as used on the - current job. Note, in the case of the since keyword, the \%s must be - enclosed in double quotes, and thus they must be preceded by a backslash - since they are already inside quotes. For example: - -\begin{verbatim} - run = "Nightly-backup level=%l since=\"%s\" storage=DDS-4" -\end{verbatim} - - A cloned job will not start additional clones, so it is not - possible to recurse. - - Please note that all cloned jobs, as specified in the Run directives are - submitted for running before the original job is run (while it is being - initialized). This means that any clone job will actually start before - the original job, and may even block the original job from starting - until the original job finishes unless you allow multiple simultaneous - jobs. Even if you set a lower priority on the clone job, if no other - jobs are running, it will start before the original job. - - If you are trying to prioritize jobs by using the clone feature (Run - directive), you will find it much easier to do using a RunScript - resource, or a RunBeforeJob directive. - -\label{Priority} -\item [Priority = \lt{}number\gt{}] - \index[dir]{Priority} - \index[dir]{Directive!Priority} - This directive permits you to control the order in which your jobs will - be run by specifying a positive non-zero number. The higher the number, - the lower the job priority. Assuming you are not running concurrent jobs, - all queued jobs of priority 1 will run before queued jobs of priority 2 - and so on, regardless of the original scheduling order. - - The priority only affects waiting jobs that are queued to run, not jobs - that are already running. If one or more jobs of priority 2 are already - running, and a new job is scheduled with priority 1, the currently - running priority 2 jobs must complete before the priority 1 job is run. - - The default priority is 10. - - If you want to run concurrent jobs you should - keep these points in mind: - -\begin{itemize} -\item See \ilink{Running Concurrent Jobs}{ConcurrentJobs} on how to setup - concurrent jobs. - -\item Bacula concurrently runs jobs of only one priority at a time. It - will not simultaneously run a priority 1 and a priority 2 job. - -\item If Bacula is running a priority 2 job and a new priority 1 job is - scheduled, it will wait until the running priority 2 job terminates even - if the Maximum Concurrent Jobs settings would otherwise allow two jobs - to run simultaneously. - -\item Suppose that bacula is running a priority 2 job and a new priority 1 - job is scheduled and queued waiting for the running priority 2 job to - terminate. If you then start a second priority 2 job, the waiting - priority 1 job will prevent the new priority 2 job from running - concurrently with the running priority 2 job. That is: as long as there - is a higher priority job waiting to run, no new lower priority jobs will - start even if the Maximum Concurrent Jobs settings would normally allow - them to run. This ensures that higher priority jobs will be run as soon - as possible. -\end{itemize} - -If you have several jobs of different priority, it may not best to start -them at exactly the same time, because Bacula must examine them one at a -time. If by Bacula starts a lower priority job first, then it will run -before your high priority jobs. If you experience this problem, you may -avoid it by starting any higher priority jobs a few seconds before lower -priority ones. This insures that Bacula will examine the jobs in the -correct order, and that your priority scheme will be respected. - -\label{WritePartAfterJob} -\item [Write Part After Job = \lt{}yes|no\gt{}] -\index[dir]{Write Part After Job} -\index[dir]{Directive!Write Part After Job} - This directive is only implemented in version 1.37 and later. - If this directive is set to {\bf yes} (default {\bf no}), a new part file - will be created after the job is finished. - - It should be set to {\bf yes} when writing to devices that require mount - (for example DVD), so you are sure that the current part, containing - this job's data, is written to the device, and that no data is left in - the temporary file on the hard disk. However, on some media, like DVD+R - and DVD-R, a lot of space (about 10Mb) is lost every time a part is - written. So, if you run several jobs each after another, you could set - this directive to {\bf no} for all jobs, except the last one, to avoid - wasting too much space, but to ensure that the data is written to the - medium when all jobs are finished. - - This directive is ignored with tape and FIFO devices. - -\item [Heartbeat Interval = \lt{}time-interval\gt{}] - \index[dir]{Heartbeat Interval} - \index[dir]{Directive!Heartbeat} - This directive is optional and if specified will cause the Director to - set a keepalive interval (heartbeat) in seconds on each of the sockets - it opens for the Client resource. This value will override any - specified at the Director level. It is implemented only on systems - (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function. - The default value is zero, which means no change is made to the socket. - -\end{description} - -The following is an example of a valid Job resource definition: - -\footnotesize -\begin{verbatim} -Job { - Name = "Minou" - Type = Backup - Level = Incremental # default - Client = Minou - FileSet="Minou Full Set" - Storage = DLTDrive - Pool = Default - Schedule = "MinouWeeklyCycle" - Messages = Standard -} -\end{verbatim} -\normalsize - -\section{The JobDefs Resource} -\label{JobDefsResource} -\index[general]{JobDefs Resource} -\index[general]{Resource!JobDefs} - -The JobDefs resource permits all the same directives that can appear in a Job -resource. However, a JobDefs resource does not create a Job, rather it can be -referenced within a Job to provide defaults for that Job. This permits you to -concisely define several nearly identical Jobs, each one referencing a JobDefs -resource which contains the defaults. Only the changes from the defaults need to -be mentioned in each Job. - -\section{The Schedule Resource} -\label{ScheduleResource} -\index[general]{Resource!Schedule} -\index[general]{Schedule Resource} - -The Schedule resource provides a means of automatically scheduling a Job as -well as the ability to override the default Level, Pool, Storage and Messages -resources. If a Schedule resource is not referenced in a Job, the Job can only -be run manually. In general, you specify an action to be taken and when. - -\begin{description} - -\item [Schedule] -\index[dir]{Schedule} -\index[dir]{Directive!Schedule} - Start of the Schedule directives. No {\bf Schedule} resource is - required, but you will need at least one if you want Jobs to be - automatically started. - -\item [Name = \lt{}name\gt{}] - \index[dir]{Name} - \index[dir]{Directive!Name} - The name of the schedule being defined. The Name directive is required. - -\item [Run = \lt{}Job-overrides\gt{} \lt{}Date-time-specification\gt{}] - \index[dir]{Run} - \index[dir]{Directive!Run} - The Run directive defines when a Job is to be run, and what overrides if - any to apply. You may specify multiple {\bf run} directives within a - {\bf Schedule} resource. If you do, they will all be applied (i.e. - multiple schedules). If you have two {\bf Run} directives that start at - the same time, two Jobs will start at the same time (well, within one - second of each other). - - The {\bf Job-overrides} permit overriding the Level, the Storage, the - Messages, and the Pool specifications provided in the Job resource. In - addition, the FullPool, the IncrementalPool, and the DifferentialPool - specifications permit overriding the Pool specification according to - what backup Job Level is in effect. - - By the use of overrides, you may customize a particular Job. For - example, you may specify a Messages override for your Incremental - backups that outputs messages to a log file, but for your weekly or - monthly Full backups, you may send the output by email by using a - different Messages override. - - {\bf Job-overrides} are specified as: {\bf keyword=value} where the - keyword is Level, Storage, Messages, Pool, FullPool, DifferentialPool, - or IncrementalPool, and the {\bf value} is as defined on the respective - directive formats for the Job resource. You may specify multiple {\bf - Job-overrides} on one {\bf Run} directive by separating them with one or - more spaces or by separating them with a trailing comma. For example: - -\begin{description} - -\item [Level=Full] - \index[dir]{Level} - \index[dir]{Directive!Level} - is all files in the FileSet whether or not they have changed. - -\item [Level=Incremental] - \index[dir]{Level} - \index[dir]{Directive!Level} - is all files that have changed since the last backup. - -\item [Pool=Weekly] - \index[dir]{Pool} - \index[dir]{Directive!Pool} - specifies to use the Pool named {\bf Weekly}. - -\item [Storage=DLT\_Drive] - \index[dir]{Storage} - \index[dir]{Directive!Storage} - specifies to use {\bf DLT\_Drive} for the storage device. - -\item [Messages=Verbose] - \index[dir]{Messages} - \index[dir]{Directive!Messages} - specifies to use the {\bf Verbose} message resource for the Job. - -\item [FullPool=Full] - \index[dir]{FullPool} - \index[dir]{Directive!FullPool} - specifies to use the Pool named {\bf Full} if the job is a full backup, or -is -upgraded from another type to a full backup. - -\item [DifferentialPool=Differential] - \index[dir]{DifferentialPool} - \index[dir]{Directive!DifferentialPool} - specifies to use the Pool named {\bf Differential} if the job is a - differential backup. - -\item [IncrementalPool=Incremental] - \index[dir]{IncrementalPool} - \index[dir]{Directive!IncrementalPool} - specifies to use the Pool named {\bf Incremental} if the job is an -incremental backup. - -\item [SpoolData=yes|no] - \index[dir]{SpoolData} - \index[dir]{Directive!SpoolData} - tells Bacula to request the Storage daemon to spool data to a disk file - before writing it to the Volume (normally a tape). Thus the data is - written in large blocks to the Volume rather than small blocks. This - directive is particularly useful when running multiple simultaneous - backups to tape. It prevents interleaving of the job data and reduces - or eliminates tape drive stop and start commonly known as "shoe-shine". - -\item [SpoolSize={\it bytes}] - \index[dir]{SpoolSize} - \index[dir]{Directive!SpoolSize} - where the bytes specify the maximum spool size for this job. - The default is take from Device Maximum Spool Size limit. - This directive is available only in Bacula version 2.3.5 or - later. - -\item [WritePartAfterJob=yes|no] - \index[dir]{WritePartAfterJob} - \index[dir]{Directive!WritePartAfterJob} - tells Bacula to request the Storage daemon to write the current part - file to the device when the job is finished (see \ilink{Write Part After - Job directive in the Job resource}{WritePartAfterJob}). Please note, - this directive is implemented only in version 1.37 and later. The - default is yes. We strongly recommend that you keep this set to yes - otherwise, when the last job has finished one part will remain in the - spool file and restore may or may not work. - -\end{description} - -{\bf Date-time-specification} determines when the Job is to be run. The -specification is a repetition, and as a default Bacula is set to run a job at -the beginning of the hour of every hour of every day of every week of every -month of every year. This is not normally what you want, so you must specify -or limit when you want the job to run. Any specification given is assumed to -be repetitive in nature and will serve to override or limit the default -repetition. This is done by specifying masks or times for the hour, day of the -month, day of the week, week of the month, week of the year, and month when -you want the job to run. By specifying one or more of the above, you can -define a schedule to repeat at almost any frequency you want. - -Basically, you must supply a {\bf month}, {\bf day}, {\bf hour}, and {\bf -minute} the Job is to be run. Of these four items to be specified, {\bf day} -is special in that you may either specify a day of the month such as 1, 2, -... 31, or you may specify a day of the week such as Monday, Tuesday, ... -Sunday. Finally, you may also specify a week qualifier to restrict the -schedule to the first, second, third, fourth, or fifth week of the month. - -For example, if you specify only a day of the week, such as {\bf Tuesday} the -Job will be run every hour of every Tuesday of every Month. That is the {\bf -month} and {\bf hour} remain set to the defaults of every month and all -hours. - -Note, by default with no other specification, your job will run at the -beginning of every hour. If you wish your job to run more than once in any -given hour, you will need to specify multiple {\bf run} specifications each -with a different minute. - -The date/time to run the Job can be specified in the following way in -pseudo-BNF: - -\footnotesize -\begin{verbatim} - = 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 -