From 147184718f5beb8fa1245147ed6233d4719fc93c Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Sun, 10 Jul 2005 21:17:29 +0000 Subject: [PATCH] Document updates --- docs/manual/ansi-labels.tex | 22 +- docs/manual/autochangerres.tex | 4 +- docs/manual/autochangers.tex | 45 +++ docs/manual/console.tex | 25 +- docs/manual/dirdconf.tex | 9 + docs/manual/faq.tex | 181 +++++++++--- docs/manual/filedconf.tex | 5 + docs/manual/fileset.tex | 9 +- docs/manual/quickstart.tex | 33 ++- docs/manual/restore.tex | 442 ++++++++++++++++++++++-------- docs/manual/spooling.tex | 22 +- docs/manual/state.tex | 21 +- docs/manual/storedconf.tex | 40 ++- docs/manual/supportedchangers.tex | 3 +- docs/manual/supporteddrives.tex | 53 +++- docs/manual/win32.tex | 9 + 16 files changed, 713 insertions(+), 210 deletions(-) diff --git a/docs/manual/ansi-labels.tex b/docs/manual/ansi-labels.tex index ee8664b9..d23e6602 100644 --- a/docs/manual/ansi-labels.tex +++ b/docs/manual/ansi-labels.tex @@ -5,7 +5,7 @@ \index[general]{Labels!Tape} \addcontentsline{toc}{section}{ANSI and IBM Tape Labels} -Bacula can support ANSI or IBM tape labels as long as you +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. @@ -18,9 +18,17 @@ 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 keep your Volume +When using ANSI or IBM tape labeling, you must restrict your Volume names to a maximum of 6 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. + \subsection*{Director Pool Directive} \addcontentsline{toc}{section}{Director Pool Directive} @@ -29,7 +37,8 @@ names to a maximum of 6 characters. \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. + precedence over the value passed from the Director to the SD. The default + is Label Type = Bacula. \end{description} \subsection*{Storage Daemon Device Directives} @@ -40,11 +49,14 @@ names to a maximum of 6 characters. 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. + 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 index a178a98f..5205c692 100644 --- a/docs/manual/autochangerres.tex +++ b/docs/manual/autochangerres.tex @@ -30,7 +30,7 @@ as a tape library by autochanger manufacturers). 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 precidence over one specified in + resource (see above), it will take precedence over one specified in the Autochanger resource. \item [Changer Command = {\it name-string}] @@ -40,7 +40,7 @@ as a tape library by autochanger manufacturers). 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 specified in the Device resource, it will take - precidence over the one specified in the Autochanger resource. + precedence over the one specified in the Autochanger resource. \end{description} diff --git a/docs/manual/autochangers.tex b/docs/manual/autochangers.tex index 4df2bff6..e30ae04a 100644 --- a/docs/manual/autochangers.tex +++ b/docs/manual/autochangers.tex @@ -342,6 +342,51 @@ 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. +\subsection*{A Multi-drive Example Configuration File} +\index[general]{Multi-drive Example Configuration File } +\addcontentsline{toc}{subsection}{A 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; + Mount Anonymous Volumes = no; +} + +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; + Mount Anonymous Volumes = no; +} + +\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} \subsection*{Specifying Slots When Labeling} diff --git a/docs/manual/console.tex b/docs/manual/console.tex index fa913c3f..d02f73a4 100644 --- a/docs/manual/console.tex +++ b/docs/manual/console.tex @@ -304,12 +304,12 @@ The label command can fail for a number of reasons: case you must {\bf unmount} the device, insert a blank tape, then do the {\bf label} command. \item The tape in the device is already a Bacula labeled tape. (Bacula will - never relabel a Bacula labeled tape unless it is recycled and you use the + never relabel a Bacula labeled tape unless it is recycled and you use the {\bf relabel} command). \item There is no tape in the drive. \end{enumerate} -There are two ways to relabel a volume that already has a Bacula label. The +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: @@ -333,8 +333,11 @@ 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: +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} @@ -543,8 +546,8 @@ 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 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) @@ -560,17 +563,17 @@ The actual data written to the Volume will be unaffected by this command. This command is used to label physical volumes. The full form of this command is: -relabel storage=\lt{}storage-name\gt{} volume=\lt{}newvolume-name\gt{} -name=\lt{}old-volume-name\gt{} - +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 written on the Volume -is lost and cannot be recovered. +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 } diff --git a/docs/manual/dirdconf.tex b/docs/manual/dirdconf.tex index 5479082d..2fbc57df 100644 --- a/docs/manual/dirdconf.tex +++ b/docs/manual/dirdconf.tex @@ -2531,6 +2531,15 @@ Storage { Device = "HP DLT 80" # same as Device in Storage daemon Media Type = DLT8000 # same as MediaType in Storage daemon } +# Definition for a DLT autochanger device +Storage { + Name = Autochanger + Address = rufus + Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ" + Device = "Autochanger" # same as Device in Storage daemon + Media Type = DLT-8000 # Different from DLTDrive + Autochanger = yes +} # Definition of DDS tape storage device Storage { Name = SDT-10000 diff --git a/docs/manual/faq.tex b/docs/manual/faq.tex index 71181160..a81c35db 100644 --- a/docs/manual/faq.tex +++ b/docs/manual/faq.tex @@ -29,14 +29,15 @@ of known bugs and solutions. Yes, Bacula compiles and runs on Windows machines (Win98, WinMe, WinXP, WinNT, and Win2000). We provide a binary version of the Client (bacula-fd), but have not tested the Director nor the Storage daemon. Note, Win95 is no - longer supported because it doesn't have the GetFileAttributesExA API call. + longer supported because it doesn't have the GetFileAttributesExA API call. + \label{lang} \item [What language is Bacula written in?] \index[general]{What language is Bacula written in? } - It is written in C++, but it is mostly C code using only a limited set of the - C++ extensions over C. Thus Bacula is completely compiled using the C++ - compiler. There are several modules, including the Win32 interface, that + It is written in C++, but it is mostly C code using only a limited set of + the C++ extensions over C. Thus Bacula is completely compiled using the + C++ compiler. There are several modules, including the Win32 interface, that are written using the object oriented C++ features. Over time, we are slowly adding a larger subset of C++. @@ -44,11 +45,12 @@ of known bugs and solutions. \item [On what machines does Bacula run? ] \index[general]{On what machines does Bacula run? } {\bf Bacula} builds and executes on RedHat Linux (versions RH7.1-RHEL 3.0, - SUSE, Gentoo, Debian, Mandriva, ...), FreeBSD, Solaris, Alpha, SGI (client), + SuSE, Gentoo, Debian, Mandriva, ...), FreeBSD, Solaris, Alpha, SGI (client), NetBSD, OpenBSD, Mac OS X (client), and Win32 (client). - Bacula has been my only backup tool for over four years backing up 5 machines - nightly (3 Linux boxes running RedHat, a WinXP machine, and a WinNT machine). + Bacula has been my only backup tool for over four years backing up 5 + machines nightly (3 Linux boxes running RedHat, a WinXP machine, and a WinNT + machine). \label{stable} @@ -58,13 +60,17 @@ of known bugs and solutions. unimplemented or partially implemented features. With a program of this size (100,000+ lines of C++ code not including the SQL programs) there are bound to be bugs. The current test environment (a twisted pair local network and a - HP DLT backup tape) is not exactly ideal, so additional testing on other sites is - necessary. The File daemon has never crashed -- running months at a time with + HP DLT backup tape) is not exactly ideal, so additional testing on other +sites is + necessary. The File daemon has never crashed -- running months at a time +with no intervention. The Storage daemon is remarkably stable with most of the problems arising during labeling or switching tapes. Storage daemon crashes - are rare. The Director, given the multitude of functions it fulfills is also + are rare. The Director, given the multitude of functions it fulfills is +also relatively stable. In a production environment, it rarely if ever crashes. Of - the three daemons, the Director is the most prone to having problems. Still, it + the three daemons, the Director is the most prone to having problems. Still, +it frequently runs several months with no problems. There are a number of reasons for this stability. @@ -77,7 +83,8 @@ of known bugs and solutions. \item All memory leaks (orphaned buffers) are reported each time the program terminates.\\ \item Any signal (segmentation fault, ...) generates a - traceback that is emailed to the developer. This permits quick resolution of + traceback that is emailed to the developer. This permits quick resolution +of bugs even if they only show up rarely in a production system.\\ \item There is a reasonably comprehensive set of regression tests that avoids re-creating the most common errors in new versions of @@ -153,7 +160,7 @@ of known bugs and solutions. \item It is a Windows Client, and the client died because of an improper configuration file. Check that the Bacula icon is in the system tray and the the menu items work. If the client has died, the icon will disappear only -when you move the mouse over the icon. + when you move the mouse over the icon. \item The Client address or port is incorrect or not resolved by DNS. See if you can ping the client machine using the same address as in the Client record. @@ -163,7 +170,12 @@ when you move the mouse over the icon. \item Your password or names are not correct in both the Director and the Client machine. Try configuring everything identical to how you run the client on the same machine as the Director, but just change the Address. If -that works, make the other changes one step at a time until it works. + that works, make the other changes one step at a time until it works. +\item You may also be having problems betwen your File daemon and your + Storage daemon. The name you use in the Storage resource of your + Director's conf file must be known (resolvable) by the File daemon, + because it is passed symbolically to the File daemon, which then + resolves it to get an IP address used to contact the Storage daemon. \end{itemize} \label{startover} @@ -212,8 +224,10 @@ where you need to adjust the device name for your system. you for the tape, and if the wrong one is mounted, it will inform you. If you have previously done an {\bf unmount} command, all Storage daemon - sessions (jobs) will be completely blocked from using the drive unmounted, so - be sure to do a {\bf mount} after your unmount. If in doubt, do a second {\bf + sessions (jobs) will be completely blocked from using the drive unmounted, +so + be sure to do a {\bf mount} after your unmount. If in doubt, do a second +{\bf mount}, it won't cause any harm. \label{windowstart} @@ -255,8 +269,10 @@ directory, which you can examine and thereby determine the problem. \label{scroll} \item [When I Start the Console, the Error Messages Fly By. How can I see them? ] - \index[general]{When I Start the Console, the Error Messages Fly By. How can I see them? } - Either use a shell window with a scroll bar, or use the gnome-console. In any + \index[general]{When I Start the Console, the Error Messages Fly By. How can +I see them? } + Either use a shell window with a scroll bar, or use the gnome-console. In +any case, you probably should be logging all output to a file, and then you can simply view the file using an editor or the {\bf less} program. To log all output, I have the following in my Director's Message resource definition: @@ -432,8 +448,12 @@ please use the one distributed in the source code. but can grow as needed to handle any length. Most of the work is carried out by lower level routines making the coding rather easy. + Note that due to limitations Win32 path and filenames cannot exceed + 260 characters. By using Win32 Unicode functions, we will remove this + restriction in later versions of Bacula. + \label{unique} -\item [What Is the Really Unique Feature of Bacula? ] +\item [What Is the Really Unique Feature of Bacula?] \index[general]{What Is the Really Unique Feature of Bacula? } Well, it is hard to come up with unique features when backup programs for Unix machines have been around since the 1960s. That said, I believe that @@ -451,7 +471,6 @@ please use the one distributed in the source code. implemented, this will enormously reduce tape usage. \label{sequence} - \item [If I Do Run Multiple Simultaneous Jobs, How Can I Force One Particular Job to Run After Another Job? ] \index[general]{If I Do Run Multiple Simultaneous Jobs, How Can I Force One @@ -482,7 +501,8 @@ manual. \item [I Change Recycling, Retention Periods, or File Sizes in my Pool Resource and they Still Don``t Work.] - \index[general]{I Change Recycling, Retention Periods, or File Sizes in my Pool + \index[general]{I Change Recycling, Retention Periods, or File Sizes in my +Pool Resource and they Still Don"t Work. } The different variables associated with a Pool are defined in the Pool Resource, but are actually read by Bacula from the Catalog database. On @@ -507,7 +527,8 @@ manual. the tape drive hardware, and you either enable or disable it with system tools such as {\bf mt}. This compression works independently of Bacula. - Bacula also has compression code, which is normally used only when backing up + Bacula also has compression code, which is normally used only when backing +up to file Volumes. There are two conditions for this ''software`` to become enabled. @@ -540,7 +561,8 @@ There are several reasons why Bacula will request a new tape. \begin{itemize} \item There is an I/O error on the tape. Bacula prints an error message and - requests a new tape. Bacula does not attempt to continue writing after an I/O + requests a new tape. Bacula does not attempt to continue writing after an +I/O error. \item Bacula encounters and end of medium on the tape. This is not always distinguishable from an I/O error. @@ -551,13 +573,14 @@ There are several reasons why Bacula will request a new tape. \end{itemize} \label{LevelChanging} - \item [Bacula is Not Doing the Right Thing When I Request an Incremental Backup. Why?] - \index[general]{Bacula is Not Doing the Right Thing When I Request an Incremental + \index[general]{Bacula is Not Doing the Right Thing When I Request an +Incremental Backup. Why? } As explained in one of the previous questions, Bacula will automatically - upgrade an Incremental or Differential job to a Full backup if it cannot find + upgrade an Incremental or Differential job to a Full backup if it cannot +find a prior Full backup or a suitable Full backup. For the gory details on how/when Bacula decides to upgrade levels please see the \ilink{Level record}{Level} in the Director's configuration @@ -586,12 +609,15 @@ there is not much we can do. \label{WaitForever} \item [I am Backing Up an Offsite Machine with an Unreliable Connection. - The Director Waits Forever for the Client to Contact the SD. What Can I Do?] - \index[general]{I am Backing Up an Offsite Machine with an Unreliable Connection. + The Director Waits Forever for the Client to Contact the SD. What Can I +Do?] + \index[general]{I am Backing Up an Offsite Machine with an Unreliable +Connection. The Director Waits Forever for the Client to Contact the SD. What Can I Do?} Bacula was written on the assumption that it will have a good TCP/IP connection between all the daemons. As a consequence, the current Bacula - doesn't deal with faulty connections very well. This situation is slowly being + doesn't deal with faulty connections very well. This situation is slowly +being corrected over time. There are several things you can do to improve the situation. @@ -614,7 +640,8 @@ in the FileDaemon resource. \label{sshHanging} \item [When I ssh into a machine and start Bacula then attempt to exit, ssh hangs forever.] - \index[general]{When I ssh into a machine and start Bacula then attempt to exit, + \index[general]{When I ssh into a machine and start Bacula then attempt to +exit, ssh hangs forever. } This happens because Bacula leaves stdin, stdout, and stderr open for debug purposes. To avoid it, the simplest thing to do is to redirect the output of @@ -635,19 +662,24 @@ and likewise for the other daemons. \item [I'm confused by the different Retention periods: File Retention, Job Retention, Volume Retention. Why are there so many?] - \index[general]{I'm confused by the different Retention periods: File Retention, + \index[general]{I'm confused by the different Retention periods: File +Retention, Job Retention, Volume Retention. Why are there so many? } Yes, this certainly can be confusing. The basic reason for so many is to - allow flexibility. The File records take quite a lot of space in the catalog, + allow flexibility. The File records take quite a lot of space in the +catalog, so they are typically records you want to remove rather quickly. The Job - records, take very little space, and they can be useful even without the File + records, take very little space, and they can be useful even without the +File records to see what Jobs actually ran and when. One must understand that if the File records are removed from the catalog, you cannot use the {\bf restore} command to restore an individual file since Bacula no longer knows - where it is. However, as long as the Volume Retention period has not expired, + where it is. However, as long as the Volume Retention period has not +expired, the data will still be on the tape, and can be recovered from the tape. - For example, I keep a 30 day retention period for my Files to keep my catalog + For example, I keep a 30 day retention period for my Files to keep my +catalog from getting too big, but I keep my tapes for a minimum of one year, just in case. @@ -655,7 +687,8 @@ and likewise for the other daemons. \item [Why Does Bacula Ignore the MaxVolumeSize Set in my Pool?] \index[general]{Why Does Bacula Ignore the MaxVolumeSize Set in my Pool? } The MaxVolumeSize that Bacula uses comes from the Media record, so most - likely you changed your Pool, which is used as the default for creating Media + likely you changed your Pool, which is used as the default for creating +Media records, {\bf after} you created your Volume. Check what is in the Media record by doing: @@ -678,9 +711,11 @@ to change it. \label{ConnectionRefused} \item [In connecting to my Client, I get ''ERR:Connection Refused. Packet Size too big from File daemon:192.168.1.4:9102`` Why?] - \index[general]{In connecting to my Client, I get &htmlQuoteERR:Connection Refused. + \index[general]{In connecting to my Client, I get &htmlQuoteERR:Connection +Refused. Packet Size too big from File daemon:192.168.1.4:9102&htmlQuote Why? } - This is typically a communications error resulting from one of the following: + This is typically a communications error resulting from one of the +following: \begin{itemize} @@ -707,4 +742,74 @@ Another solution might be to run the daemon with the debug option by: This will cause the FD to write a file {\bf bacula.trace} in the current directory, which you can examine to determine the problem. +\item [During long running jobs my File daemon dies with Pipe Error, or + some other communications error. Why?] + \index[general]{Communications Errors} + \index[general]{Pipe Errors} + There are a number of reasons why a connection might break. + Most often, it is a router between your two computers that times out + inactive lines (not respecting the keepalive feature that Bacula uses). + In that case, you can use the {\bf Heartbeat Interval} directive in + both the Storage daemon and the File daemon. + + In at least one case, the problem has been a bad driver for a Win32 + NVidia NForce 3 ethernet card with driver (4.4.2 17/05/2004). + In this case, a good driver is (4.8.2.0 06/04/2005). Moral of + the story, make sure you have the latest ethernet drivers + loaded. + + Lack of communications, or communications that get interrupted can + also be caused by Linux firewalls where you have a rule that throttles + connections or traffic. For example, if you have: + +\footnotesize +\begin{verbatim} +iptables -t filter -A INPUT -m limit --limit 3/second --limit-burst 3 -j DROP +\end{verbatim} +\normalsize + + you will want to add the following rules {\bf before} the above rule: +\footnotesize +\begin{verbatim} +iptables -t filter -A INPUT --dport 9101 -j ACCEPT +iptables -t filter -A INPUT --dport 9102 -j ACCEPT +iptables -t filter -A INPUT --dport 9103 -j ACCEPT +\end{verbatim} +\normalsize + This will ensure that any Bacula traffic will not get terminated because + of high usage rates. + +\item[I can't figure out how to tell the job which volume to use] + \index[general]{What tape to mount} + This is an interesting statement. I now see that a number of people new to + Bacula have the same problem as you, probably from using programs like tar. + + In fact, you do not tell Bacula what tapes to use. It is the inverse. Bacula + tells you want tapes it wants. You put tapes at its disposition and it + chooses. + + Now, if you *really* want to be tricky and try to tell Bacula what to do, it + will be reasonable if for example you mount a valid tape that it can use on a + drive, it will most likely go ahead and use it. It also has a documented + algorithm for choosing tapes -- but you are asking for problems ... + + So, the trick is to invert your concept of things and put Bacula in charge of + handling the tapes. Once you do that, you will be fine. If you want to + anticipate what it is going to do, you can generally figure it out correctly + and get what you want. + + If you start with the idea that you are going to force or tell Bacula to use + particular tapes or you insist on trying to run in that kind of mode, you will + probably not be too happy. + + I don't want to worry about what tape has what data. That is what Bacula is + designed for. + + If you have an application where you *really* need to remove a tape each day + and insert a new one, it can be done the directives exist to accomplish that. + In such a case, one little "trick" to knowing what tape Bacula will want at + 2am while you are asleep is to run a tiny job at 4pm while you are still at + work that backs up say one directory, or even one file. You will quickly find + out what tape it wants, and you can mount it before you go home ... + \end{description} diff --git a/docs/manual/filedconf.tex b/docs/manual/filedconf.tex index 2fa9382e..b5ab5442 100644 --- a/docs/manual/filedconf.tex +++ b/docs/manual/filedconf.tex @@ -92,6 +92,11 @@ Directory} as defined above. connection after a short duration despite the fact that keepalive is set. This usually results in a broken pipe error message. + If you continue getting broken pipe error messages despite using the + Heartbeat Interval, and you are using Windows, you should consider + upgrading your ethernet driver. This is a known problem with NVidia + NForce 3 drivers (4.4.2 17/05/2004). + \item [Maximum Concurrent Jobs = \lt{}number\gt{}] \index[fd]{Maximum Concurrent Jobs } where \lt{}number\gt{} is the maximum number of Jobs that should run diff --git a/docs/manual/fileset.tex b/docs/manual/fileset.tex index 3773c514..8f4cfcf7 100644 --- a/docs/manual/fileset.tex +++ b/docs/manual/fileset.tex @@ -558,9 +558,8 @@ df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \ If the vertical bar (|) in front of my\_partitions is preceded by a backslash as in \textbackslash{}|, the program will be executed on the - Client's machine instead of on the Director's machine -- (this is - implemented but not thoroughly tested, and is reported to work on - Windows). Please note that if the filename is given within quotes, you + Client's machine instead of on the Director's machine. + Please note that if the filename is given within quotes, you will need to use two slashes. An example, provided by John Donagher, that backs up all the local UFS partitions on a remote system is: @@ -576,9 +575,9 @@ FileSet { \end{verbatim} \normalsize - Note, it requires two backslash characters after the double quote (one + The above requires two backslash characters after the double quote (one preserves the next one). If you are a Linux user, just change the {\bf ufs} - to {\bf ext3} (or your preferred filesystem type) and you will be in + to {\bf ext3} (or your preferred filesystem type), and you will be in business. \item Any file-list item preceded by a less-than sign (\lt{}) will be taken diff --git a/docs/manual/quickstart.tex b/docs/manual/quickstart.tex index b61648a2..59c1ca34 100644 --- a/docs/manual/quickstart.tex +++ b/docs/manual/quickstart.tex @@ -77,7 +77,8 @@ Bacula, you must create valid configuration files for the Director, the File daemon, the Storage daemon, and the Console programs. If you have followed our recommendations, default configuration files as well as the daemon binaries will be located in your installation directory. In any case, the binaries are -found in the directory you specified on the {\bf \verb:--:sbindir} option to the {\bf +found in the directory you specified on the {\bf \verb:--:sbindir} option to the +{\bf ./configure} command, and the configuration files are found in the directory you specified on the {\bf \verb:--:sysconfdir} option. @@ -98,15 +99,18 @@ The Console program is used by the administrator to interact with the Director and to manually start/stop Jobs or to obtain Job status information. The Console configuration file is found in the directory specified on the {\bf -\verb:--:sysconfdir} option that you specified on the {\bf ./configure} command and +\verb:--:sysconfdir} option that you specified on the {\bf ./configure} command +and by default is named {\bf console.conf}. -If you choose to build the GNOME console with the {\bf \verb:--:enable-gnome} option, +If you choose to build the GNOME console with the {\bf \verb:--:enable-gnome} +option, you also find a default configuration file for it, named {\bf gnome-console.conf}. The same applies to the wxWidgets console, which is build with the {\bf -\verb:--:enable-wx-console} option, and the name of the default configuration file +\verb:--:enable-wx-console} option, and the name of the default configuration +file is, in this case, {\bf wx-console.conf}. Normally, for first time users, no change is needed to these files. Reasonable @@ -132,7 +136,8 @@ status for each of the daemons. The image shows the status for the Storage daemon (MainSD) that is currently selected. The Monitor configuration file is found in the directory specified on the {\bf -\verb:--:sysconfdir} option that you specified on the {\bf ./configure} command and +\verb:--:sysconfdir} option that you specified on the {\bf ./configure} command +and by default is named {\bf tray-monitor.conf}. Normally, for first time users, you just need to change the permission of this file to allow non-root users to run the Monitor, as this application must run as the same user as the @@ -151,7 +156,8 @@ request of the Director, finds the files to be backed up and sends them (their data) to the Storage daemon. The File daemon configuration file is found in the directory specified on the -{\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure} command. +{\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure} +command. By default, the File daemon's configuration file is named {\bf bacula-fd.conf}. Normally, for first time users, no change is needed to this file. Reasonable defaults are set. However, if you are going to back up more @@ -169,7 +175,8 @@ The Director is the central control program for all the other daemons. It schedules and monitors all jobs to be backed up. The Director configuration file is found in the directory specified on the -{\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure} command. +{\bf \verb:--:sysconfdir} option that you specified on the {\bf ./configure} +command. Normally the Director's configuration file is named {\bf bacula-dir.conf}. In general, the only change you must make is modify the FileSet resource so @@ -278,12 +285,14 @@ important information concerning compatibility of Bacula and your system. The new pthreads library {\bf /lib/tls} installed by default on recent Red Hat systems running kernel 2.4.x is defective. You must remove it or rename it, then reboot your system before running Bacula otherwise after a week or so of -running, Bacula will either block for long periods or deadlock entirely. The -feedback that we have concerning 2.6 kernels is the same. However, on 2.6 -systems, you may want to use the loader environment variable override rather -than removing /lib/tls. Please see -\ilink{ Supported Operating Systems}{SupportedOSes} for more +running, Bacula will either block for long periods or deadlock entirely. +You may want to use the loader environment variable override rather +than removing /lib/tls. Please see \ilink{ Supported Operating +Systems}{SupportedOSes} for more information on this problem. + +This problem does not seem to occur on systems running 2.6.x kernels. + \label{Running1} \subsection*{Running Bacula} diff --git a/docs/manual/restore.tex b/docs/manual/restore.tex index 2c2ef406..da14f520 100644 --- a/docs/manual/restore.tex +++ b/docs/manual/restore.tex @@ -11,7 +11,7 @@ \index[general]{General } \addcontentsline{toc}{subsection}{General} -Below, we will discuss restoring files with the Console {\bf Restore} command, +Below, we will discuss restoring files with the Console {\bf restore} command, which is the recommended way of doing it. However, there is a standalone program named {\bf bextract}, which also permits restoring files. For more information on this program, please see the @@ -27,8 +27,8 @@ job. That is a job with {\bf Type = Restore}. As a consequence, you will need a predefined {\bf restore} job in your {\bf bacula-dir.conf} (Director's config) file. The exact parameters (Client, FileSet, ...) that you define are not important as you can either modify them manually before running the job or -if you use the {\bf restore} command, explained below, they will be -automatically set for you. +if you use the {\bf restore} command, explained below, Bacula will +automatically set them for you. Since Bacula is a network backup program, you must be aware that when you restore files, it is up to you to ensure that you or Bacula have selected the @@ -37,8 +37,13 @@ correct Client and the correct hard disk location for restoring those files. the files to a different directory on client B. Normally, you will want to avoid this, but assuming the operating systems are not too different in their file structures, this should work perfectly well, if so desired. -\label{Example1} +By default, Bacula will restore data to the same Client that was backed +up, and those data will be restored not to the original places but to +{\bf /tmp/bacula-restores}. You may modify any of these defaults when the +restore command prompts you to run the job by selecting the {\bf mod} +option. +\label{Example1} \subsection*{The Restore Command} \index[general]{Command!Restore } \index[general]{Restore Command } @@ -57,6 +62,9 @@ interactively walk up and down the file tree selecting individual files to be restored. This mode is somewhat similar to the standard Unix {\bf restore} program's interactive file selection mode. +If your Files have been pruned, the {\bf restore} command will be unable +to find any files to restore. See below for more details on this. + Within the Console program, after entering the {\bf restore} command, you are presented with the following selection prompt: @@ -69,48 +77,90 @@ select which files from those JobIds are to be restored. To select the JobIds, you have the following choices: 1: List last 20 Jobs run 2: List Jobs where a given File is saved - 3: Enter list of JobIds to select + 3: Enter list of comma separated JobIds to select 4: Enter SQL list command 5: Select the most recent backup for a client 6: Select backup for a client before a specified time 7: Enter a list of files to restore 8: Enter a list of files to restore before a specified time - 9: Cancel -Select item: (1-9): - + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Cancel +Select item: (1-12): \end{verbatim} \normalsize \begin{itemize} -\item Item 1 will list the last 20 jobs run. If you find the Job you want, +\item Item 1 will list the last 20 jobs run. If you find the Job you want, you can then select item 3 and enter its JobId(s). \item Item 2 will list all the Jobs where a specified file is saved. If you - find the Job you want, you can then select item 3 and enter the JobId. + find the Job you want, you can then select item 3 and enter the JobId. \item Item 3 allows you the enter a list of comma separated JobIds whose - files will be put into the directory tree. + files will be put into the directory tree. You may then select which + files from those JobIds to restore. \item Item 4 allows you to enter any arbitrary SQL command. This is probably the most primitive way of finding the desired JobIds, but at the same time, the most flexible. Once you have found the JobId(s), you can select item 3 -and enter them. + and enter them. \item Item 5 will automatically select the most recent Full backup and all - subsequent incremental and differential backups for a specified Client. These - are the Jobs and Files which, if reloaded, will restore your system to the most -current saved state. It automatically enters the JobIds found into the -directory tree. This is probably the most convenient of all the above options -to use if you wish to restore a selected Client to its most recent state. + subsequent incremental and differential backups for a specified Client. + These are the Jobs and Files which, if reloaded, will restore your + system to the most current saved state. It automatically enters the + JobIds found into the directory tree. This is probably the most + convenient of all the above options to use if you wish to restore a + selected Client to its most recent state. + + There are two important things to note. First, this automatic selection + will never select a job that failed (terminated with an error status). + If you have such a job and want to recover one or more files from it, + you will need to explicitly enter the JobId in item 3, then choose the + files to restore. + + If some of the Jobs that are needed to do the restore have had their + File records pruned, the restore will be incomplete. Bacula currently + does not correctly detect this condition. You can however, check for + this by looking carefully at the list of Jobs that Bacula selects and + prints. If you find Jobs with the JobFiles column set to zero, when + files should have been backed up, then you should expect problems. + + If all the File records have been pruned, Bacula will realize that there + are no file records in any of the JobIds chosen and will inform you. It + will then propose doing a full restore (non-selective) of those JobIds. + This is possible because Bacula still knows where the beginning of the + Job data is on the Volumes, even if it does not know where particular + files are located. + \item Item 6 allows you to specify a date and time, after which Bacula will automatically select the most recent Full backup and all subsequent incremental and differential backups that started before the specified date -and time. + and time. \item Item 7 allows you to specify one or more filenames (complete path required) to be restored. Each filename is entered one at a time or if you prefix a filename with the less-than symbol (\lt{}) Bacula will read that -file and assume it is a list of filenames to be restored. The filename entry -mode is terminated by entering a blank line. + file and assume it is a list of filenames to be restored. The filename entry + mode is terminated by entering a blank line. \item Item 8 allows you to specify a date and time before entering the filenames. See Item 7 above for more details. -\item Item 9 allows you to cancel the restore command. - \end{itemize} +\item Item 9 allows you find the JobIds of the most recent backup for + a client. This is much like option 5 (it uses the same code), but + those JobIds are retained internally as if you had entered them + manually. You may then select item 11 (see below) to restore one + or more directories. +\item Item 10 is the same as item 9, except that it allows you to enter + a before date (as with item 6). These JobIds will then be retained + internally. +\item Item 11 allows you to enter a list of JobIds from which you can + select directories to be restored. The list of JobIds can have been + previously created by using either item 9 or 10 on the menu. You + may then enter a full path to a directory name or a filename preceded + by a less than sign (\lt{}). The filename should contain a list + of directories to be restored. All files in those directories will + be restored, but if the directory contains subdirectories, nothing + will be restored in the subdirectory unless you explicitly enter its + name. +\item Item 12 allows you to cancel the restore command. +\end{itemize} As an example, suppose that we select item 5 (restore to most recent state). It will then ask for the desired Client, which on my system, will print all @@ -159,14 +209,22 @@ the columns are truncated here for presentation: \footnotesize \begin{verbatim} -+-------+------+----------+-------------+-------------+------+-------+------------+ -| JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId | VolSesTime | -+-------+------+----------+-------------+-------------+------+-------+------------+ -| 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 | 1028042998 | -| 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 | 1028042998 | -| 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 | 1028042998 | -| 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 | 1028042998 | -+-------+------+----------+-------------+-------------+------+-------+------------+ ++-------+------+----------+-------------+-------------+------+-------+---------- +--+ +| JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId | +VolSesTime | ++-------+------+----------+-------------+-------------+------+-------+---------- +--+ +| 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 | +1028042998 | +| 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 | +1028042998 | +| 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 | +1028042998 | +| 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 | +1028042998 | ++-------+------+----------+-------------+-------------+------+-------+---------- +--+ You have selected the following JobId: 1792,1792,1797 Building directory tree for JobId 1792 ... Building directory tree for JobId 1797 ... @@ -177,7 +235,10 @@ $ \normalsize Depending on the number of {\bf JobFiles} for each JobId, the {\bf Building -directory tree ...``} can take a bit of time. +directory tree ...``} can take a bit of time. If you notice ath all the +JobFiles are zero, your Files have probably been pruned and you will not be +able to select any individual files -- it will be restore everything or +nothing. In our example, Bacula found four Jobs that comprise the most recent backup of the specified Client and FileSet. Two of the Jobs have the same JobId because @@ -191,11 +252,14 @@ to be restored as a default, tells you how many files are in the tree, and tells you that the current working directory ({\bf cwd}) is /. Finally, Bacula prompts with the dollar sign (\$) to indicate that you may enter commands to move around the directory tree and to select files. + +If you want all the files to automatically be marked when the directory +tree is built, enter the command {\bf restore all}. Instead of choosing item 5 on the first menu (Select the most recent backup for a client), if we had chosen item 3 (Enter list of JobIds to select) and we had entered the JobIds {\bf 1792,1797,1798} we would have arrived at the same -point. +point. One point to note, if you are manually entering JobIds, is that you must enter them in the order they were run (generally in increasing JobId order). If you @@ -203,35 +267,38 @@ enter them out of order and the same file was saved in two or more of the Jobs, you may end up with an old version of that file (i.e. not the most recent). +Directly entering the JobIds can also permit you to recover data from +a Job that wrote files to tape but that terminated with an error status. + While in file selection mode, you can enter {\bf help} or a question mark (?) to produce a summary of the available commands: \footnotesize \begin{verbatim} - Command Description + Command Description ======= =========== cd change current directory count count marked files in and below the cd - dir list current directory + dir long list current directory, wildcards allowed done leave file selection mode estimate estimate restore size - exit exit = done - find find files -- wildcards allowed + exit same as done command + find find files, wildcards allowed help print help - ls list current directory -- wildcards allowed + ls list current directory, wildcards allowed lsmark list the marked files in and below the cd - mark mark file to be restored - markdir mark directory entry to be restored -- nonrecursive + mark mark dir/file to be restored recursively in dirs + markdir mark directory name to be restored (no files) pwd print current working directory - unmark unmark file to be restored - unmarkdir unmark directory -- no recursion - quit quit + unmark unmark dir/file to be restored recursively in dir + unmarkdir unmark directory name only no recursion + quit quit and do not do restore ? print help - \end{verbatim} \normalsize -As a default no files have been selected for restore. If you want to restore +As a default no files have been selected for restore (unless you +added {\bf all} to the command line. If you want to restore everything, at this point, you should enter {\bf mark *}, and then {\bf done} and {\bf Bacula} will write the bootstrap records to a file and request your approval to start a restore job. @@ -282,11 +349,13 @@ OK to run? (yes/mod/no): \normalsize Please examine each of the items very carefully to make sure that they are -correct. In particular, look at {\bf Where}, which tells you where in the -directory structure the files will be restored, and {\bf Client}, which tells -you which client will receive the files. These items will not always be -completed with the correct values depending on which of the restore options -you chose. +correct. In particular, look at {\bf Where}, which tells you where in the +directory structure the files will be restored, and {\bf Client}, which +tells you which client will receive the files. Note that by default the +Client which will receive the files is the Client that was backed up. +These items will not always be completed with the correct values depending +on which of the restore options you chose. You can change any of these +default items by entering {\bf mod} and responding to the prompts. The above assumes that you have defined a {\bf Restore} Job resource in your Director's configuration file. Normally, you will only need one Restore Job @@ -336,14 +405,17 @@ prompt list: To select the JobIds, you have the following choices: 1: List last 20 Jobs run 2: List Jobs where a given File is saved - 3: Enter list of JobIds to select + 3: Enter list of comma separated JobIds to select 4: Enter SQL list command 5: Select the most recent backup for a client 6: Select backup for a client before a specified time 7: Enter a list of files to restore 8: Enter a list of files to restore before a specified time - 9: Cancel -Select item: (1-9): 7 + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Cancel +Select item: (1-12): \end{verbatim} \normalsize @@ -427,7 +499,7 @@ restore client=Rufus file=