%%
%%
-\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
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
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
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
\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:
\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
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
\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
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
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
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
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
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
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
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}
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
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
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
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
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}
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
\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
\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:
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
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
-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.
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
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
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.
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
projects / bacula / docs / blobdiff