X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fmanual%2Fprogs.tex;h=985462eb8202e840ae55fb358c614e5bf6b88182;hb=9d649f8088c441650b9bdf6a4185a0432e230a2e;hp=1b9fdc9862b57c432d4dc536162f2e4a0960a351;hpb=cacf6c2054bd220317c620f64101e1f9f004250f;p=bacula%2Fdocs

diff --git a/docs/manual/progs.tex b/docs/manual/progs.tex
index 1b9fdc98..985462eb 100644
--- a/docs/manual/progs.tex
+++ b/docs/manual/progs.tex
@@ -1,18 +1,16 @@
 %%
 %%
 
-\section*{Volume Utility Tools}
+\chapter{Volume Utility Tools}
 \label{_UtilityChapter}
 \index[general]{Volume Utility Tools}
 \index[general]{Tools!Volume Utility}
-\addcontentsline{toc}{section}{Volume Utility Tools}
 
 This document describes the utility programs written to aid Bacula users and
 developers in dealing with Volumes external to Bacula. 
 
-\subsection*{Specifying the Configuration File}
+\section{Specifying the Configuration File}
 \index[general]{Specifying the Configuration File}
-\addcontentsline{toc}{subsection}{Specifying the Configuration File}
 
 Starting with version 1.27, each of the following programs requires a valid
 Storage daemon configuration file (actually, the only part of the
@@ -23,10 +21,9 @@ bacula-sd.conf} in the current directory, but you may specify a different
 configuration file using the {\bf -c} option. 
 
 
-\subsection*{Specifying a Device Name For a Tape}
+\section{Specifying a Device Name For a Tape}
 \index[general]{Tape!Specifying a Device Name For a}
 \index[general]{Specifying a Device Name For a Tape}
-\addcontentsline{toc}{subsection}{Specifying a Device Name For a Tape}
 
 Each of these programs require a {\bf device-name} where the Volume can be
 found. In the case of a tape, this is the physical device name such as {\bf
@@ -40,10 +37,9 @@ one of these programs, you will either need to stop the Storage daemon, or
 will {\bf busy} because Bacula is using it.
 
 
-\subsection*{Specifying a Device Name For a File}
+\section{Specifying a Device Name For a File}
 \index[general]{File!Specifying a Device Name For a}
 \index[general]{Specifying a Device Name For a File}
-\addcontentsline{toc}{subsection}{Specifying a Device Name For a File}
 
 If you are attempting to read or write an archive file rather than a tape, the
 {\bf device-name} should be the full path to the archive location including
@@ -53,10 +49,9 @@ must have the same entry in the configuration file. So, the path is equivalent
 to the archive device name, and the filename is equivalent to the volume name.
 
 
-\subsection*{Specifying Volumes}
+\section{Specifying Volumes}
 \index[general]{Volumes!Specifying}
 \index[general]{Specifying Volumes}
-\addcontentsline{toc}{subsection}{Specifying Volumes}
 
 In general, you must specify the Volume name to each of the programs below
 (with the exception of {\bf btape}). The best method to do so is to specify a
@@ -112,11 +107,10 @@ accept any volume. For example:
 \end{verbatim}
 \normalsize
 
-\subsection*{bls}
+\section{bls}
 \label{bls}
 \index[general]{bls}
 \index[general]{program!bls}
-\addcontentsline{toc}{subsection}{bls}
 
 {\bf bls} can be used to do an {\bf ls} type listing of a {\bf Bacula} tape or
 file. It is called: 
@@ -190,10 +184,9 @@ bls: Got EOF on device /tmp
 \end{verbatim}
 \normalsize
 
-\subsubsection*{Listing Jobs}
+\subsection{Listing Jobs}
 \index[general]{Listing Jobs with bls}
 \index[general]{bls!Listing Jobs}
-\addcontentsline{toc}{subsubsection}{bls Listing Jobs}
 
 If you are listing a Volume to determine what Jobs to restore, normally the
 {\bf -j} option provides you with most of what you will need as long as you
@@ -227,10 +220,9 @@ shows a full save followed by two incremental saves.
 Adding the {\bf -v} option will display virtually all information that is
 available for each record: 
 
-\subsubsection*{Listing Blocks}
+\subsection{Listing Blocks}
 \index[general]{Listing Blocks with bls}
 \index[general]{bls!Listing Blocks}
-\addcontentsline{toc}{subsubsection}{bls Listing Blocks}
 
 Normally, except for debugging purposes, you will not need to list Bacula
 blocks (the "primitive" unit of Bacula data on the Volume). However, you can
@@ -317,11 +309,15 @@ bls: block.c:92    Rec: VId=1 VT=1035062102 FI=6 Strm=MD5 len=16 p=8101841
 \end{verbatim}
 \normalsize
 
-\subsection*{bextract}
+\section{bextract}
 \label{bextract}
 \index[general]{Bextract}
 \index[general]{program!bextract}
-\addcontentsline{toc}{subsection}{bextract}
+
+If you find yourself using {\bf bextract}, you probably have done
+something wrong. For example, if you are trying to recover a file
+but are having problems, please see the \ilink {Restoring When Things Go
+Wrong}{database_restore} section of the Restore chapter of this manual.
 
 Normally, you will restore files by running a {\bf Restore} Job from the {\bf
 Console} program. However, {\bf bextract} can be used to extract a single file
@@ -330,6 +326,10 @@ a useful tool to restore files to an empty system assuming you are able to
 boot, you have statically linked {\bf bextract} and you have an appropriate
 {\bf bootstrap} file. 
 
+Please note that one of the current limitations of bextract is that it
+will not restore access control lists (ACL) that have been backed up along
+with the file data.
+
 It is called: 
 
 \footnotesize
@@ -356,10 +356,9 @@ d:/tmp/My Documents}. That is, the original drive specification will be
 stripped. If no prefix is specified, the file will be restored to the original
 drive. 
 
-\subsubsection*{Extracting with Include or Exclude Lists}
+\subsection{Extracting with Include or Exclude Lists}
 \index[general]{Lists!Extracting with Include or Exclude}
 \index[general]{Extracting with Include or Exclude Lists}
-\addcontentsline{toc}{subsubsection}{Extracting with Include or Exclude Lists}
 
 Using the {\bf -e} option, you can specify a file containing a list of files
 to be excluded. Wildcards can be used in the exclusion list. This option will
@@ -399,10 +398,9 @@ restored files will be placed in a file of the original name under the
 directory {\bf /tmp} (i.e. /tmp/home/kern/bacula/... and
 /tmp/usr/local/bin/...). 
 
-\subsubsection*{Extracting With a Bootstrap File}
+\subsection{Extracting With a Bootstrap File}
 \index[general]{File!Extracting With a Bootstrap}
 \index[general]{Extracting With a Bootstrap File}
-\addcontentsline{toc}{subsubsection}{Extracting With a Bootstrap File}
 
 The {\bf -b} option is used to specify a {\bf bootstrap} file containing the
 information needed to restore precisely the files you want. Specifying a {\bf
@@ -425,10 +423,9 @@ exclude files at the same time. The bootstrap conditions will first be
 applied, and then each file record seen will be compared to the include and
 exclude lists. 
 
-\subsubsection*{Extracting From Multiple Volumes}
+\subsection{Extracting From Multiple Volumes}
 \index[general]{Volumes!Extracting From Multiple}
 \index[general]{Extracting From Multiple Volumes}
-\addcontentsline{toc}{subsubsection}{Extracting From Multiple Volumes}
 
 If you wish to extract files that span several Volumes, you can specify the
 Volume names in the bootstrap file or you may specify the Volume names on the
@@ -437,21 +434,22 @@ under the {\bf bls} program entitled {\bf Listing Multiple Volumes} for more
 information. The same techniques apply equally well to the {\bf bextract}
 program. 
 
-\subsection*{bscan}
+\section{bscan}
 \label{bscan}
 \index[general]{bscan}
 \index[general]{program!bscan}
-\addcontentsline{toc}{subsection}{bscan}
 
-The {\bf bscan} program can be used to re-create a database (catalog) from the
-backup information written to one or more Volumes. This is normally needed
-only if one or more Volumes have been pruned or purged from your catalog so
-that the records on the Volume are no longer in the catalog. 
 If you find yourself using this program, you have probably done something
 wrong. For example, the best way to recover a lost or damaged Bacula
 database is to reload the database from using the bootstrap file that
 was written when you saved it.
 
+The {\bf bscan} program can be used to re-create a database (catalog) from
+the backup information written to one or more Volumes.  This is normally
+needed only if one or more Volumes have been pruned or purged from your
+catalog so that the records on the Volume are no longer in the catalog, or
+for Volumes that you have archived.
+
 With some care, it can also be used to synchronize your existing catalog with
 a Volume. Although we have never seen a case of bscan damaging a
 catalog, since bscan modifies your catalog, we recommend that
@@ -544,7 +542,7 @@ If you have multiple tapes, you should scan them with:
 You should, always try to specify the tapes in the order they are written.
 However, bscan can handle scanning tapes that are not sequential.  Any
 incomplete records at the end of the tape will simply be ignored in that
-case.  If you are simply reparing an existing catalog, this may be OK, but
+case.  If you are simply repairing an existing catalog, this may be OK, but
 if you are creating a new catalog from scratch, it will leave your database
 in an incorrect state.  If you do not specify all necessary Volumes on a
 single bscan command, bscan will not be able to correctly restore the
@@ -560,11 +558,9 @@ not restored by bscan. The results of bscanning are, however, perfectly valid,
 and will permit restoration of any or all the files in the catalog using the
 normal Bacula console commands. 
 
-\subsubsection*{Using bscan to Compare a Volume to an existing Catalog}
+\subsection{Using bscan to Compare a Volume to an existing Catalog}
 \index[general]{Catalog!Using bscan to Compare a Volume to an existing}
 \index[general]{Using bscan to Compare a Volume to an existing Catalog}
-\addcontentsline{toc}{subsubsection}{Using bscan to Compare a Volume to an
-existing Catalog}
 
 If you wish to compare the contents of a Volume to an existing catalog without
 changing the catalog, you can safely do so if and only if you do {\bf not}
@@ -573,11 +569,9 @@ specify either the {\bf -m} or the {\bf -s} options. However, at this time
 as they should be, so we don't particularly recommend this mode other than for
 testing. 
 
-\subsubsection*{Using bscan to Recreate a Catalog from a Volume}
-\index[general]{Volume!Using bscan to Recreate a Catalog from a}
+\subsection{Using bscan to Recreate a Catalog from a Volume}
+\index[general]{Volume!Using bscan to Recreate a Catalog from a Volume}
 \index[general]{Using bscan to Recreate a Catalog from a Volume}
-\addcontentsline{toc}{subsubsection}{Using bscan to Recreate a Catalog from a
-Volume}
 
 This is the mode for which {\bf bscan} is most useful. You can either {\bf
 bscan} into a freshly created catalog, or directly into your existing catalog
@@ -691,11 +685,9 @@ contained in the database is not saved to the tape. Nevertheless, the
 reconstruction is sufficiently complete, that you can run {\bf restore}
 against it and get valid results. 
 
-\subsubsection*{Using bscan to Correct the Volume File Count}
+\subsection{Using bscan to Correct the Volume File Count}
 \index[general]{Using bscan to Correct the Volume File Count}
-\index[general]{Count!Using bscan to Correct the Volume File}
-\addcontentsline{toc}{subsubsection}{Using bscan to Correct the Volume File
-Count}
+\index[general]{Count!Using bscan to Correct the Volume File Count}
 
 If the Storage daemon crashes during a backup Job, the catalog will not be
 properly updated for the Volume being used at the time of the crash. This
@@ -707,10 +699,9 @@ from what is in the catalog. To correct this situation, you may run a {\bf
 bscan} with the {\bf -m} option (but {\bf without} the {\bf -s} option) to
 update only the final Media record for the Volumes read. 
 
-\subsubsection*{After bscan}
+\subsection{After bscan}
 \index[general]{After bscan}
 \index[general]{Bscan!After}
-\addcontentsline{toc}{subsubsection}{After bscan}
 
 If you use {\bf bscan} to enter the contents of the Volume into an existing
 catalog, you should be aware that the records you entered may be immediately
@@ -722,11 +713,10 @@ having it immediately purged. When you have restored and backed up the data,
 you can reset the VolStatus to {\bf Used} and the Volume will be purged from
 the catalog. 
 
-\subsection*{bcopy}
+\section{bcopy}
 \label{bcopy}
 \index[general]{Bcopy}
 \index[general]{program!bcopy}
-\addcontentsline{toc}{subsection}{bcopy}
 
 The {\bf bcopy} program can be used to copy one {\bf Bacula} archive file to
 another. For example, you may copy a tape to a file, a file to a tape, a file
@@ -738,10 +728,9 @@ contains valid backup data, cannot be accessed directly from existing catalog
 entries. If you wish to be able to use the Volume with the Console restore
 command, for example, you must first bscan the new Volume into the catalog. 
 
-\subsubsection*{bcopy Command Options}
+\subsection{bcopy Command Options}
 \index[general]{Options!bcopy Command}
 \index[general]{Bcopy Command Options}
-\addcontentsline{toc}{subsubsection}{bcopy Command Options}
 
 \footnotesize
 \begin{verbatim}
@@ -769,17 +758,17 @@ As this is a new program, any feedback on its use would be appreciated. In
 addition, I only have a single tape drive, so I have never been able to test
 this program with two tape drives. 
 
-\subsection*{btape}
+\section{btape}
 \label{btape}
 \index[general]{Btape}
 \index[general]{program!btape}
-\addcontentsline{toc}{subsection}{btape}
 
 This program permits a number of elementary tape operations via a tty command
-interface. The {\bf test} command, described below, can be very useful for
-testing older tape drive compatibility problems. Aside from initial testing of
-tape drive compatibility with {\bf Bacula}, {\bf btape} will be mostly used by
-developers writing new tape drivers. 
+interface. It works only with tapes and not with other kinds of Bacula
+storage media (DVD, File, ...).  The {\bf test} command, described below,
+can be very useful for testing older tape drive compatibility problems.
+Aside from initial testing of tape drive compatibility with {\bf Bacula},
+{\bf btape} will be mostly used by developers writing new tape drivers.
 
 {\bf btape} can be dangerous to use with existing {\bf Bacula} tapes because
 it will relabel a tape or write on the tape if so requested regardless that
@@ -808,10 +797,9 @@ Usage: btape <options> <device_name>
 \end{verbatim}
 \normalsize
 
-\subsubsection*{Using btape to Verify your Tape Drive}
+\subsection{Using btape to Verify your Tape Drive}
 \index[general]{Using btape to Verify your Tape Drive}
 \index[general]{Drive!Using btape to Verify your Tape}
-\addcontentsline{toc}{subsubsection}{Using btape to Verify your Tape Drive}
 
 An important reason for this program is to ensure that a Storage daemon
 configuration file is defined so that Bacula will correctly read and write
@@ -825,10 +813,9 @@ reasonably self explanatory. Please see the
 \ilink{Tape Testing}{_ChapterStart27} Chapter of this manual for
 the details. 
 
-\subsubsection*{btape Commands}
+\subsection{btape Commands}
 \index[general]{Btape Commands}
 \index[general]{Commands!btape}
-\addcontentsline{toc}{subsubsection}{btape Commands}
 
 The full list of commands are: 
 
@@ -839,7 +826,6 @@ The full list of commands are:
   autochanger test autochanger
   bsf        backspace file
   bsr        backspace record
-  bfill      fill tape using Bacula writes
   cap        list device capabilities
   clear      clear tape errors
   eod        go to end of Bacula data for append
@@ -890,19 +876,17 @@ In the event that you want to relabel a {\bf Bacula}, you can simply use the
 note for labeling tapes, we recommend that you use the {\bf label} command in
 the {\bf Console} program since it will never overwrite a valid Bacula tape. 
 
-\subsection*{Other Programs}
+\section{Other Programs}
 \index[general]{Programs!Other}
 \index[general]{Other Programs}
-\addcontentsline{toc}{subsection}{Other Programs}
 
 The following programs are general utility programs and in general do not need
 a configuration file nor a device name. 
 
-\subsection*{bsmtp}
+\section{bsmtp}
 \label{bsmtp}
 \index[general]{Bsmtp}
 \index[general]{program!bsmtp}
-\addcontentsline{toc}{subsection}{bsmtp}
 
 {\bf bsmtp} is a simple mail transport program that permits more flexibility
 than the standard mail programs typically found on Unix systems. It can even
@@ -917,16 +901,26 @@ Usage: bsmtp [-f from] [-h mailhost] [-s subject] [-c copy] [recipient ...]
        -dnn        set debug level to nn
        -f          set the From: field
        -h          use mailhost:port as the bsmtp server
+       -l          limit the lines accepted to nn
        -s          set the Subject: field
        -?          print this message.
 \end{verbatim}
 \normalsize
 
 If the {\bf -f} option is not specified, {\bf bsmtp} will use your userid. If
-the option is not specified {\bf bsmtp} will use the value in the environment
+the option {\bf -h} is not specified {\bf bsmtp} will use the value in the environment
 variable {\bf bsmtpSERVER} or if there is none {\bf localhost}. By default
 port 25 is used. 
 
+If a line count limit is set with the {\bf -l} option, {\bf bsmtp} will
+not send an email with a body text exceeding that number of lines. This
+is especially useful for large restore job reports where the list of
+files restored might produce very long mails your mail-server would
+refuse or crash. However, be aware that you will probably suppress the
+job report and any error messages unless you check the log file written
+by the Director (see the messages resource in this manual for details).
+
+
 {\bf recipients} is a space separated list of email recipients. 
 
 The body of the email message is read from standard input. 
@@ -964,17 +958,16 @@ syntax of the from part of the message. Please test.
 
 When running {\bf bsmtp} by hand, you will need to terminate the message by
 entering a ctl-d in column 1 of the last line. 
+% TODO: is "column" the correct terminology for this?
 
 If you are getting incorrect dates (e.g. 1970) and you are
 running with a non-English language setting, you might try adding
 a LANG=''en\_US'' immediately before the bsmtp call.
 
-\subsection*{dbcheck}
+\section{dbcheck}
 \label{dbcheck}
 \index[general]{Dbcheck}
 \index[general]{program!dbcheck}
-\addcontentsline{toc}{subsection}{dbcheck}
-
 {\bf dbcheck} is a simple program that will search for logical
 inconsistencies in the Bacula tables in your database, and optionally fix them. 
 It is a database maintenance routine, in the sense that it can
@@ -1116,15 +1109,14 @@ The inconsistencies examined are the following:
 
 By the way, I personally run dbcheck only where I have messed up
 my database due to a bug in developing Bacula code, so normally
-you should never need to run dbcheck inspite of the
+you should never need to run dbcheck in spite of the
 recommendations given above, which are given so that users don't
 waste their time running dbcheck too often.
 
-\subsection*{bregex}
+\section{bregex}
 \label{regex}
 \index[general]{bregex}
 \index[general]{program!bregex}
-\addcontentsline{toc}{subsection}{bregex}
 
 {\bf bregex} is a simple program that will allow you to test 
 regular expressions against a file of data. This can be useful
@@ -1157,11 +1149,10 @@ and you can suppress printing of line numbers with the -l option.
 This program can be useful for testing regex expressions to be 
 applied against a list of filenames.
 
-\subsection*{bwild}
+\section{bwild}
 \label{wild}
 \index[general]{bwild}
 \index[general]{program!bwild}
-\addcontentsline{toc}{subsection}{bwild}
 
 {\bf bwild} is a simple program that will allow you to test 
 wild-card expressions against a file of data.
@@ -1192,11 +1183,10 @@ and you can suppress printing of line numbers with the -l option.
 This program can be useful for testing wild expressions to be 
 applied against a list of filenames.
 
-\subsection*{testfind}
+\section{testfind}
 \label{testfind}
 \index[general]{Testfind}
 \index[general]{program!testfind}
-\addcontentsline{toc}{subsection}{testfind}
 
 {\bf testfind} permits listing of files using the same search engine that is
 used for the {\bf Include} resource in Job resources. Note, much of the