From 96e475e1103eb02c8199972b6d72b4e8e35e9018 Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Tue, 24 Apr 2007 19:29:22 +0000 Subject: [PATCH] Some doc updates --- docs/manual/bootstrap.tex | 131 ++++++++++++++++++---------------- docs/manual/dirdconf.tex | 6 ++ docs/manual/progs.tex | 11 ++- docs/manual/restore.tex | 31 ++++---- docs/manual/rpm-faq.tex | 29 ++++++-- docs/manual/supportedoses.tex | 5 ++ docs/manual/win32.tex | 7 +- 7 files changed, 133 insertions(+), 87 deletions(-) diff --git a/docs/manual/bootstrap.tex b/docs/manual/bootstrap.tex index eb370557..ab2c3908 100644 --- a/docs/manual/bootstrap.tex +++ b/docs/manual/bootstrap.tex @@ -16,13 +16,14 @@ by using a 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. It is a relatively compact +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{File Format} -\index[general]{Format!File } -\index[general]{File Format } +\section{Bootstrap File Format} +\index[general]{Format!Bootstrap} +\index[general]{Bootstrap File Format } The general format of a {\bf bootstrap} file is: @@ -63,98 +64,108 @@ matched against the Volume records are: \begin{description} \item [Volume] - \index[fd]{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. + \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[fd]{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 allows the Storage daemon to know when to stop reading the Volume. + This value is optional. \item [VolFile] - \index[fd]{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. + \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[fd]{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 on the Volume where the data is stored. This record is -currently not used. + \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[fd]{VolSessionTime } + \index[general]{VolSessionTime } The value specifies a Volume Session Time to be matched from the current -volume. + volume. \item [VolSessionId] - \index[fd]{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. + \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[fd]{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. + 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[fd]{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. + 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[fd]{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. + 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[fd]{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. + 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. -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[fd]{Slot } + \index[general]{Slot } The value specifies the autochanger slot. There may be only a single {\bf -Slot} specification for each Volume. + Slot} specification for each Volume. \item [Stream] - \index[fd]{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. + 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[fd]{*JobType } + \index[general]{*JobType } Not yet implemented. \item [*JobLevel] - \index[fd]{*JobLevel } + \index[general]{*JobLevel } Not yet implemented. \end{description} diff --git a/docs/manual/dirdconf.tex b/docs/manual/dirdconf.tex index 4d25adcc..2a9bd49c 100644 --- a/docs/manual/dirdconf.tex +++ b/docs/manual/dirdconf.tex @@ -368,6 +368,12 @@ covering only part of the total files. 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 diff --git a/docs/manual/progs.tex b/docs/manual/progs.tex index 7ecd74bf..c9305caf 100644 --- a/docs/manual/progs.tex +++ b/docs/manual/progs.tex @@ -328,7 +328,10 @@ boot, you have statically linked {\bf bextract} and you have an appropriate 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. +with the file data, also the command line length is relatively limited, +which means that you cannot enter a huge number of volumes. If you need to +enter more volumes than the command line supports, please use a bootstrap +file (see below). It is called: @@ -432,7 +435,8 @@ Volume names in the bootstrap file or you may specify the Volume names on the command line by separating them with a vertical bar. See the section above under the {\bf bls} program entitled {\bf Listing Multiple Volumes} for more information. The same techniques apply equally well to the {\bf bextract} -program. +program or read the \ilink{Bootstrap}{BootstrapChapter} +chapter of this document. \section{bscan} \label{bscan} @@ -1018,7 +1022,8 @@ It is called: \footnotesize \begin{verbatim} -Usage: dbcheck [-c config] [-C catalog name] [-d debug_level] [] +Usage: dbcheck [-c config] [-C catalog name] [-d debug_level] + [] -b batch mode -C catalog name in the director conf file -c director conf filename diff --git a/docs/manual/restore.tex b/docs/manual/restore.tex index afb98ea3..27be4355 100644 --- a/docs/manual/restore.tex +++ b/docs/manual/restore.tex @@ -1,24 +1,25 @@ %% %% - -\section*{The Bacula Console Restore Command} +\chapter{The Restore Command} \label{RestoreChapter} -\index[general]{Command!Bacula Console Restore } -\index[general]{Bacula Console Restore Command } +\index[general]{Command!Console Restore} +\index[general]{Console Restore Command} \section{General} \index[general]{General } 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 -\ilink{Bacula Utility Programs}{bextract} chapter of this manual. -You will also want to look at the {\bf bls} program in the same chapter, which -allows you to list the contents of your Volumes. Finally, if you have an old -Volume that is no longer in the catalog, you can restore the catalog entries -using the program named {\bf bscan}, documented in the same -\ilink{Bacula Utility Programs}{bextract} chapter. +which is the recommended way of doing restoring files. It is not possible +to restore files by automatically starting a job as you do with Backup, +Verify, ... jobs. However, in addition to the console restore command, +there is a standalone program named {\bf bextract}, which also permits +restoring files. For more information on this program, please see the +\ilink{Bacula Utility Programs}{bextract} chapter of this manual. You will +also want to look at the {\bf bls} program in the same chapter, which +allows you to list the contents of your Volumes. Finally, if you have an +old Volume that is no longer in the catalog, you can restore the catalog +entries using the program named {\bf bscan}, documented in the same +\ilink{Bacula Utility Programs}{bextract} chapter. In general, to restore a file or a set of files, you must run a {\bf restore} job. That is a job with {\bf Type = Restore}. As a consequence, you will need @@ -44,8 +45,8 @@ option. \label{Example1} \section{The Restore Command} -\index[general]{Command!Restore } -\index[general]{Restore Command } +\index[general]{Command!Restore} +\index[general]{Restore Command} Since Bacula maintains a catalog of your files and on which Volumes (disk or tape), they are stored, it can do most of the bookkeeping work, allowing you diff --git a/docs/manual/rpm-faq.tex b/docs/manual/rpm-faq.tex index 1fa1d76a..44383d64 100644 --- a/docs/manual/rpm-faq.tex +++ b/docs/manual/rpm-faq.tex @@ -205,7 +205,15 @@ creation of debug rpm packages is: \item \label{faq8} - {\bf I just upgraded from 1.36.x to 1.38.x and now my director daemon won't start. It appears to start but dies silently and I get a "connection refused" error when starting the console. What is wrong?} Beginning with 1.38 the rpm packages are configured to run the director and storage daemons as a non-root user. The file daemon runs as user root and group bacula, the storage daemon as user bacula and group disk, and the director as user bacula and group bacula. If you are upgrading you will need to change some file permissions for things to work. Execute the following commands as root: + {\bf I just upgraded from 1.36.x to 1.38.x and now my director daemon +won't start. It appears to start but dies silently and I get a "connection +refused" error when starting the console. What is wrong?} Beginning with +1.38 the rpm packages are configured to run the director and storage +daemons as a non-root user. The file daemon runs as user root and group +bacula, the storage daemon as user bacula and group disk, and the director +as user bacula and group bacula. If you are upgrading you will need to +change some file permissions for things to work. Execute the following +commands as root: \footnotesize \begin{verbatim} @@ -216,11 +224,20 @@ creation of debug rpm packages is: \end{verbatim} \normalsize -Further, if you are using File storage volumes rather than tapes those files will also need to have ownership set to user bacula and group bacula. +Further, if you are using File storage volumes rather than tapes those +files will also need to have ownership set to user bacula and group bacula. \item \label{faq9} - {\bf There are a lot of rpm packages. Which packages do I need for what?} For a bacula server you need to select the packsge based upon your preferred catalog database: one of bacula-mysql, bacula-postgresql or bacula-sqlite. If your system does not provide an mtx package you also need bacula-mtx to satisfy that dependancy. For a client machine you need only install bacula-client. Optionally, for either server or client machines, you may install a graphical console bacula-gconsole and/or bacula-wxconsole. One last package, bacula-updatedb is required only when upgrading a server more than one database revision level. + {\bf There are a lot of rpm packages. Which packages do I need for +what?} For a bacula server you need to select the packsge based upon your +preferred catalog database: one of bacula-mysql, bacula-postgresql or +bacula-sqlite. If your system does not provide an mtx package you also +need bacula-mtx to satisfy that dependancy. For a client machine you need +only install bacula-client. Optionally, for either server or client +machines, you may install a graphical console bacula-bgnome-console and/or +bacula-bwxconsole. One last package, bacula-updatedb is required only when +upgrading a server more than one database revision level. @@ -316,12 +333,12 @@ Build the client rpm only in place of one of the above database full builds: X86-64 support: --define "build_x86_64 1" -Supress build of gnome-console: ---define "nobuild_gconsole 1" +Supress build of bgnome-console: +--define "nobuild_bgconsole 1" Build the WXWindows console: requires wxGTK >= 2.6 ---define "build_wxconsole 1" +--define "build_bwxconsole 1" Build python scripting support: --define "build_python 1" diff --git a/docs/manual/supportedoses.tex b/docs/manual/supportedoses.tex index ea2beaa5..d5bf0d1d 100644 --- a/docs/manual/supportedoses.tex +++ b/docs/manual/supportedoses.tex @@ -15,6 +15,11 @@ \ilink{ Tape Modes on FreeBSD}{FreeBSDTapes} section of the Tape Testing chapter of this manual.) \item Windows (Win98/Me, WinNT/2K/XP) Client (File daemon) binaries. +\item Windows Vista VSS (Volume Shadow Copy) is reported not to work + with Bacula. +\item The Windows servers (Director and Storage daemon) are available + in the binary Client installer. The are reported to work in + many cases. However they are NOT supported. \item MacOS X/Darwin (see \elink{ http://fink.sourceforge.net/}{http://fink.sourceforge.net/} for obtaining the packages) \item OpenBSD Client (File daemon). diff --git a/docs/manual/win32.tex b/docs/manual/win32.tex index e80a474a..6b2abe4a 100644 --- a/docs/manual/win32.tex +++ b/docs/manual/win32.tex @@ -15,9 +15,10 @@ As of Bacula version 1.39.20 or greater, the installer is capable of installing not just the Client program, but also the Director and the Storage daemon and all the other programs that were previously available only on Unix systems. These additional -programs, notably the Director and Storage daemon, have been -tested, but still need to be documented. As a consequence, if you -install and use them, please test them carefully before putting +programs, notably the Director and Storage daemon, have been partially +tested, are reported to have some bugs, and still need to be documented. +They are not yet supported, and we cannot currently accept or fix +bug reports on them. Consequently, please test them carefully before putting them into a critical production environment. The Windows version of the Bacula File daemon has been tested on Win98, WinMe, -- 2.39.5