From 759db8403886dde0891e971ae944317e9995fa81 Mon Sep 17 00:00:00 2001 From: Philippe Chauvat Date: Mon, 10 Dec 2012 09:18:48 +0100 Subject: [PATCH] Minor changes like typo, external references --- docs/manuals/en/console/console.tex | 2 +- docs/manuals/en/developers/catalog.tex | 29 -- docs/manuals/en/developers/daemonprotocol.tex | 61 ++-- docs/manuals/en/developers/director.tex | 11 +- docs/manuals/en/developers/file.tex | 25 +- docs/manuals/en/developers/generaldevel.tex | 314 ++++++++---------- docs/manuals/en/developers/git.tex | 3 - docs/manuals/en/developers/gui-interface.tex | 28 +- docs/manuals/en/developers/md5.tex | 71 ++-- docs/manuals/en/developers/mediaformat.tex | 1 - docs/manuals/en/developers/mempool.tex | 71 ++-- docs/manuals/en/developers/netprotocol.tex | 97 +++--- .../manuals/en/developers/platformsupport.tex | 21 +- docs/manuals/en/developers/porting.tex | 91 +++-- docs/manuals/en/developers/regression.tex | 91 +++-- docs/manuals/en/developers/smartall.tex | 129 +++---- docs/manuals/en/developers/storage.tex | 12 +- docs/manuals/en/developers/tls-techdoc.tex | 23 +- docs/manuals/en/main/configure.tex | 4 - docs/manuals/en/main/dirdconf.tex | 22 -- docs/manuals/en/main/general.tex | 5 - docs/manuals/en/main/install.tex | 1 - docs/manuals/en/main/main.tex | 2 +- docs/manuals/en/main/newbs4.0features.tex | 31 +- docs/manuals/en/main/newbsfeatures.tex | 13 +- docs/manuals/en/main/newfeatures.tex | 49 +-- docs/manuals/en/main/quickstart.tex | 2 - docs/manuals/en/main/supportedchangers.tex | 1 - docs/manuals/en/main/supporteddrives.tex | 1 - docs/manuals/en/main/supportedoses.tex | 2 +- docs/manuals/en/main/win32.tex | 51 +-- docs/manuals/en/problems/tips.tex | 2 +- docs/manuals/en/utility/progs.tex | 7 +- 33 files changed, 449 insertions(+), 824 deletions(-) diff --git a/docs/manuals/en/console/console.tex b/docs/manuals/en/console/console.tex index 05480b5e..eb7a271b 100644 --- a/docs/manuals/en/console/console.tex +++ b/docs/manuals/en/console/console.tex @@ -15,7 +15,7 @@ \usepackage[utf8]{inputenc} \usepackage[toc,title,header,page]{appendix} \usepackage[T1]{fontenc} -\usepackage{longtable,graphicx,fancyhdr,lastpage,eurosym,dcolumn,ltxtable,textcomp,varioref,lscape,pdfpages,ifthen,setspace,colortbl,diagbox} +\usepackage{longtable,graphicx,fancyhdr,lastpage,dcolumn,ltxtable,textcomp,varioref,lscape,pdfpages,ifthen,setspace,colortbl,diagbox} \usepackage{lmodern} \usepackage{MnSymbol} \usepackage{bbding,multirow} diff --git a/docs/manuals/en/developers/catalog.tex b/docs/manuals/en/developers/catalog.tex index b3500236..1529402f 100644 --- a/docs/manuals/en/developers/catalog.tex +++ b/docs/manuals/en/developers/catalog.tex @@ -8,7 +8,6 @@ \section{General} \index[general]{General } -\addcontentsline{toc}{subsection}{General} This chapter is intended to be a technical discussion of the Catalog services and as such is not targeted at end users but rather at developers and system @@ -49,7 +48,6 @@ PostgreSQL, or SQLite) to run. \subsection{Filenames and Maximum Filename Length} \index[general]{Filenames and Maximum Filename Length } \index[general]{Length!Filenames and Maximum Filename } -\addcontentsline{toc}{subsubsection}{Filenames and Maximum Filename Length} In general, either MySQL, PostgreSQL or SQLite permit storing arbitrary long path names and file names in the catalog database. In practice, there still @@ -64,7 +62,6 @@ long path and filenames. \subsection{Installing and Configuring MySQL} \index[general]{MySQL!Installing and Configuring } \index[general]{Installing and Configuring MySQL } -%\addcontentsline{toc}{subsubsection}{Installing and Configuring MySQL} For the details of installing and configuring MySQL, please see the \bsysxrlink{Installing and Configuring MySQL}{MySqlChapter}{main}{chapter} of @@ -73,7 +70,6 @@ the \mainman{}. \subsection{Installing and Configuring PostgreSQL} \index[general]{PostgreSQL!Installing and Configuring } \index[general]{Installing and Configuring PostgreSQL } -%\addcontentsline{toc}{subsubsection}{Installing and Configuring PostgreSQL} For the details of installing and configuring PostgreSQL, please see the \bsysxrlink{Installing and Configuring PostgreSQL}{PostgreSqlChapter}{main}{chapter} @@ -82,7 +78,6 @@ For the details of installing and configuring PostgreSQL, please see the \subsection{Installing and Configuring SQLite} \index[general]{Installing and Configuring SQLite } \index[general]{SQLite!Installing and Configuring } -%\addcontentsline{toc}{subsubsection}{Installing and Configuring SQLite} For the details of installing and configuring SQLite, please see the \bsysxrlink{Installing and Configuring SQLite}{SqlLiteChapter}{main}{chapter} of @@ -91,7 +86,6 @@ the \mainman{}. \subsection{Internal Bacula Catalog} \index[general]{Catalog!Internal Bacula } \index[general]{Internal Bacula Catalog } -%\addcontentsline{toc}{subsubsection}{Internal Bacula Catalog} Please see the \bsysxrlink{Internal Bacula Database} {chap:InternalBaculaDatabase}{misc}{chapter} of the \miscman{} for more details. @@ -99,7 +93,6 @@ Please see the \bsysxrlink{Internal Bacula Database} \subsection{Database Table Design} \index[general]{Design!Database Table } \index[general]{Database Table Design } -%\addcontentsline{toc}{subsubsection}{Database Table Design} All discussions that follow pertain to the MySQL database. The details for the PostgreSQL and SQLite databases are essentially identical except for that all @@ -132,8 +125,6 @@ lost or damaged database. \section{Sequence of Creation of Records for a Save Job} \index[general]{Sequence of Creation of Records for a Save Job } \index[general]{Job!Sequence of Creation of Records for a Save } -\addcontentsline{toc}{subsection}{Sequence of Creation of Records for a Save -Job} Start with StartDate, ClientName, Filename, Path, Attributes, MediaName, MediaCoordinates. (PartNumber, NumParts). In the steps below, ``Create new'' @@ -160,15 +151,12 @@ created, otherwise the existing RecordId should be used. \section{Database Tables} \index[general]{Database Tables } \index[general]{Tables!Database } -%\addcontentsline{toc}{subsection}{Database Tables} -%\addcontentsline{lot}{table}{Filename Table Layout} \LTXtable{\linewidth}{table_dbfilename} The {\bf Filename} table \bsysref{table:dbfilename} contains the name of each file backed up with the path removed. If different directories or machines contain the same filename, only one copy will be saved in this table. -%\addcontentsline{lot}{table}{Path Table Layout} \LTXtable{\linewidth}{table_dbpath} The {\bf Path} table \bsysref{table:dbpath} contains the path or directory names of all @@ -205,7 +193,6 @@ file, and indexing it on the first 50 characters takes 6 mins 43 seconds and creates a 7.35 MB database. -%\addcontentsline{lot}{table} \LTXtable{\linewidth}{table_dbfile} The {\bf File} table \bsysref{table:dbfile} contains one entry for each file backed up by @@ -223,7 +210,6 @@ of total database size. As a consequence, the user must take care to periodically reduce the number of File records using the {\bf retention} command in the Console program. -%\addcontentsline{lot}{table}{Job Table Layout} \LTXtable{\linewidth}{table_dbjob} The {\bf Job} table \bsysref{table:dbjob} contains one record for each Job run by Bacula. Thus @@ -250,7 +236,6 @@ are using the same Storage daemon. The Job Type (or simply Type) can have one of the following values: -%\addcontentsline{lot}{table}{Job Types} \LTXtable{\linewidth}{table_dbjobtypes} Note, the Job Type values in table \bsysref{table:dbjobtypes} noted above are not kept in an SQL table. @@ -260,7 +245,6 @@ following: \LTXtable{\linewidth}{table_dbjobstatuses} -%\addcontentsline{lot}{table}{File Sets Table Layout} \LTXtable{\linewidth}{table_dbfileset} The {\bf FileSet} table \bsysref{table:dbfileset} contains one entry for each FileSet that is used. The @@ -271,7 +255,6 @@ file or adds a file, we need to ensure that a Full backup is done prior to the next incremental. -%\addcontentsline{lot}{table} \LTXtable{\linewidth}{table_dbjobmedia} The {\bf JobMedia} table \bsysref{table:dbjobmedia} contains one entry at the following: start of @@ -290,7 +273,6 @@ backup. -%\addcontentsline{lot}{table}{Media Table Layout} \LTXtable{\linewidth}{table_dbmedia} The {\bf Volume} table\footnote{Internally referred to as the Media table} \bsysref{table:dbmedia} contains @@ -298,7 +280,6 @@ one entry for each volume, that is each tape, cassette (8mm, DLT, DAT, ...), or file on which information is or was backed up. There is one Volume record created for each of the NumVols specified in the Pool resource record. -%\addcontentsline{lot}{table}{Pool Table Layout} \LTXtable{\linewidth}{table_dbpool} The {\bf Pool} table \bsysref{table:dbpool} contains one entry for each media pool controlled by @@ -309,50 +290,42 @@ the Director's Storage definition record. The CurrentVol is the sequence number of the Media record for the current volume. -%\addcontentsline{lot}{table}{Client Table Layout} \LTXtable{\linewidth}{table_dbclient} The {\bf Client} table \bsysref{table:dbclient} contains one entry for each machine backed up by Bacula in this database. Normally the Name is a fully qualified domain name. -%\addcontentsline{lot}{table}{Storage Table Layout} \LTXtable{\linewidth}{table_dbstorage} The {\bf Storage} table \bsysref{table:dbstorage} contains one entry for each Storage used. -%\addcontentsline{lot}{table}{Counter Table Layout} \LTXtable{\linewidth}{table_dbcounter} The {\bf Counter} table \bsysref{table:dbcounter} contains one entry for each permanent counter defined by the user. -%\addcontentsline{lot}{table}{Job History Table Layout} \LTXtable{\linewidth}{table_dbjobhistory} The {\bf JobHisto} table \bsysref{table:dbjobhistory} is the same as the Job table, but it keeps long term statistics (i.e. it is not pruned with the Job). -%\addcontentsline{lot}{table}{Log Table Layout} \LTXtable{\linewidth}{table_dblog} The {\bf Log} table \bsysref{table:dblog} contains a log of all Job output. -%\addcontentsline{lot}{table}{Location Table Layout} \LTXtable{\linewidth}{table_dblocation} The {\bf Location} table \bsysref{table:dblocation} defines where a Volume is physically. -%\addcontentsline{lot}{table}{Location Log Table Layout} \LTXtable{\linewidth}{table_dblocationlog} The {\bf Location Log} table \bsysref{table:dblocationlog} contains a log of all Job output. -%\addcontentsline{lot}{table}{Version Table Layout} \LTXtable{\linewidth}{table_dbversion} The {\bf Version} table \bsysref{table:dbversion} defines the Bacula database version number. Bacula @@ -360,7 +333,6 @@ checks this number before reading the database to ensure that it is compatible with the Bacula binary file. -%\addcontentsline{lot}{table}{Base Files Table Layout} \LTXtable{\linewidth}{table_dbbasefiles} The {\bf BaseFiles} table \bsysref{table:dbbasefiles} contains all the File references for a particular @@ -375,7 +347,6 @@ This record is not yet implemented. \subsection{MySQL Table Definition} \index[general]{MySQL Table Definition } \index[general]{Definition!MySQL Table } -\addcontentsline{toc}{subsubsection}{MySQL Table Definition} The commands used to create the MySQL tables are as follows: diff --git a/docs/manuals/en/developers/daemonprotocol.tex b/docs/manuals/en/developers/daemonprotocol.tex index 93feb295..ab9c2ed3 100644 --- a/docs/manuals/en/developers/daemonprotocol.tex +++ b/docs/manuals/en/developers/daemonprotocol.tex @@ -8,22 +8,20 @@ \section{General} \index{General } -\addcontentsline{toc}{subsection}{General} This document describes the protocols used between the various daemons. As Bacula has developed, it has become quite out of date. The general idea still holds true, but the details of the fields for each command, and indeed the -commands themselves have changed considerably. +commands themselves have changed considerably. It is intended to be a technical discussion of the general daemon protocols and as such is not targeted at end users but rather at developers and system administrators that want or need to know more of the working details of {\bf -Bacula}. +Bacula}. \section{Low Level Network Protocol} \index{Protocol!Low Level Network } \index{Low Level Network Protocol } -\addcontentsline{toc}{subsection}{Low Level Network Protocol} At the lowest level, the network protocol is handled by {\bf BSOCK} packets which contain a lot of information about the status of the network connection: @@ -38,36 +36,35 @@ BSOCK routines expect that only a single thread is accessing the socket at a time. It is advised that multiple threads do not read/write the same socket. If you must do this, you must provide some sort of locking mechanism. It would not be appropriate for efficiency reasons to make every call to the BSOCK -routines lock and unlock the packet. +routines lock and unlock the packet. \section{General Daemon Protocol} \index{General Daemon Protocol } \index{Protocol!General Daemon } -\addcontentsline{toc}{subsection}{General Daemon Protocol} In general, all the daemons follow the following global rules. There may be exceptions depending on the specific case. Normally, one daemon will be sending commands to another daemon (specifically, the Director to the Storage -daemon and the Director to the File daemon). +daemon and the Director to the File daemon). \begin{bsysitemize} \item Commands are always ASCII commands that are upper/lower case dependent - as well as space sensitive. + as well as space sensitive. \item All binary data is converted into ASCII (either with printf statements - or using base64 encoding). + or using base64 encoding). \item All responses to commands sent are always prefixed with a return numeric code where codes in the 1000's are reserved for the Director, the 2000's are reserved for the File daemon, and the 3000's are reserved for the -Storage daemon. +Storage daemon. \item Any response that is not prefixed with a numeric code is a command (or subcommand if you like) coming from the other end. For example, while the Director is corresponding with the Storage daemon, the Storage daemon can request Catalog services from the Director. This convention permits each side to send commands to the other daemon while simultaneously responding to -commands. +commands. \item Any response that is of zero length, depending on the context, either terminates the data stream being sent or terminates command mode prior to - closing the connection. + closing the connection. \item Any response that is of negative length is a special sign that normally requires a response. For example, during data transfer from the File daemon to the Storage daemon, normally the File daemon sends continuously without @@ -76,19 +73,17 @@ of length -1 indicating that the current data stream is complete and that the Storage daemon should respond to the packet with an OK, ABORT JOB, PAUSE, etc. This permits the File daemon to efficiently send data while at the same time occasionally ``polling'' the Storage daemon for his status or any -special requests. +special requests. Currently, these negative lengths are specific to the daemon, but shortly, the range 0 to -999 will be standard daemon wide signals, while -1000 to -1999 will be for Director user, -2000 to -2999 for the File daemon, and --3000 to -3999 for the Storage daemon. +-3000 to -3999 for the Storage daemon. \end{bsysitemize} \section{The Protocol Used Between the Director and the Storage Daemon} \index{Daemon!Protocol Used Between the Director and the Storage } \index{Protocol Used Between the Director and the Storage Daemon } -\addcontentsline{toc}{subsection}{Protocol Used Between the Director and the -Storage Daemon} Before sending commands to the File daemon, the Director opens a Message channel with the Storage daemon, identifies itself and presents its password. @@ -98,7 +93,7 @@ File daemon authorization (append, read all, or read for a specific session). The Storage daemon will then pass back to the Director a enabling key for this JobId that must be presented by the File daemon when opening the job. Until this process is complete, the Storage daemon is not available for use by File -daemons. +daemons. \footnotesize \begin{lstlisting} @@ -118,15 +113,13 @@ SD: 3000 OK use device For the Director to be authorized, the \lt{}Director-name\gt{} and the \lt{}password\gt{} must match the values in one of the Storage daemon's Director resources (there may be several Directors that can access a single -Storage daemon). +Storage daemon). \section{The Protocol Used Between the Director and the File Daemon} \index{Daemon!Protocol Used Between the Director and the File } \index{Protocol Used Between the Director and the File Daemon } -\addcontentsline{toc}{subsection}{Protocol Used Between the Director and the -File Daemon} -A typical conversation might look like the following: +A typical conversation might look like the following: \footnotesize \begin{lstlisting} @@ -174,20 +167,17 @@ FD: close socket \section{The Save Protocol Between the File Daemon and the Storage Daemon} \index{Save Protocol Between the File Daemon and the Storage Daemon } \index{Daemon!Save Protocol Between the File Daemon and the Storage } -\addcontentsline{toc}{subsection}{Save Protocol Between the File Daemon and -the Storage Daemon} Once the Director has send a {\bf save} command to the File daemon, the File -daemon will contact the Storage daemon to begin the save. +daemon will contact the Storage daemon to begin the save. In what follows: FD: refers to information set via the network from the File daemon to the Storage daemon, and SD: refers to information set from the -Storage daemon to the File daemon. +Storage daemon to the File daemon. \subsection{Command and Control Information} \index{Information!Command and Control } \index{Command and Control Information } -\addcontentsline{toc}{subsubsection}{Command and Control Information} Command and control information is exchanged in human readable ASCII commands. @@ -206,41 +196,40 @@ SD: 3000 OK data address = port = \subsection{Data Information} \index{Information!Data } \index{Data Information } -\addcontentsline{toc}{subsubsection}{Data Information} The Data information consists of the file attributes and data to the Storage daemon. For the most part, the data information is sent one way: from the File daemon to the Storage daemon. This allows the File daemon to transfer information as fast as possible without a lot of handshaking and network -overhead. +overhead. However, from time to time, the File daemon needs to do a sort of checkpoint of the situation to ensure that everything is going well with the Storage daemon. To do so, the File daemon sends a packet with a negative length indicating that he wishes the Storage daemon to respond by sending a packet of information to the File daemon. The File daemon then waits to receive a packet -from the Storage daemon before continuing. +from the Storage daemon before continuing. All data sent are in binary format except for the header packet, which is in ASCII. There are two packet types used data transfer mode: a header packet, the contents of which are known to the Storage daemon, and a data packet, the -contents of which are never examined by the Storage daemon. +contents of which are never examined by the Storage daemon. The first data packet to the Storage daemon will be an ASCII header packet -consisting of the following data. +consisting of the following data. \lt{}File-Index\gt{} \lt{}Stream-Id\gt{} \lt{}Info\gt{} where {\bf \lt{}File-Index\gt{}} is a sequential number beginning from one that -increments with each file (or directory) sent. +increments with each file (or directory) sent. where {\bf \lt{}Stream-Id\gt{}} will be 1 for the Attributes record and 2 for -uncompressed File data. 3 is reserved for the MD5 signature for the file. +uncompressed File data. 3 is reserved for the MD5 signature for the file. where {\bf \lt{}Info\gt{}} transmit information about the Stream to the Storage Daemon. It is a character string field where each character has a meaning. The only character currently defined is 0 (zero), which is simply a place holder (a no op). In the future, there may be codes indicating -compressed data, encrypted data, etc. +compressed data, encrypted data, etc. Immediately following the header packet, the Storage daemon will expect any number of data packets. The series of data packets is terminated by a zero @@ -248,7 +237,7 @@ length packet, which indicates to the Storage daemon that the next packet will be another header packet. As previously mentioned, a negative length packet is a request for the Storage daemon to temporarily enter command mode and send a reply to the File daemon. Thus an actual conversation might contain the -following exchanges: +following exchanges: \footnotesize \begin{lstlisting} @@ -281,4 +270,4 @@ FD: close socket \normalsize The information returned to the File daemon by the Storage daemon in response -to the {\bf append close session} is transmit in turn to the Director. +to the {\bf append close session} is transmit in turn to the Director. diff --git a/docs/manuals/en/developers/director.tex b/docs/manuals/en/developers/director.tex index d8c4cd0f..bb6fa722 100644 --- a/docs/manuals/en/developers/director.tex +++ b/docs/manuals/en/developers/director.tex @@ -3,16 +3,15 @@ \chapter{Director Services Daemon} \label{_ChapterStart6} -\index{Daemon!Director Services } -\index{Director Services Daemon } -\addcontentsline{toc}{section}{Director Services Daemon} +\index{Daemon!Director Services} +\index{Director Services Daemon} This chapter is intended to be a technical discussion of the Director services and as such is not targeted at end users but rather at developers and system administrators that want or need to know more of the working details of {\bf -Bacula}. +Bacula}. The {\bf Bacula Director} services consist of the program that supervises all -the backup and restore operations. +the backup and restore operations. -To be written ... +To be written \ldots{} diff --git a/docs/manuals/en/developers/file.tex b/docs/manuals/en/developers/file.tex index ee89577b..15779e8c 100644 --- a/docs/manuals/en/developers/file.tex +++ b/docs/manuals/en/developers/file.tex @@ -5,23 +5,22 @@ \label{_ChapterStart11} \index{File Services Daemon } \index{Daemon!File Services } -\addcontentsline{toc}{section}{File Services Daemon} Please note, this section is somewhat out of date as the code has evolved -significantly. The basic idea has not changed though. +significantly. The basic idea has not changed though. This chapter is intended to be a technical discussion of the File daemon services and as such is not targeted at end users but rather at developers and system administrators that want or need to know more of the working details of -{\bf Bacula}. +{\bf Bacula}. The {\bf Bacula File Services} consist of the programs that run on the system to be backed up and provide the interface between the Host File system and -Bacula -- in particular, the Director and the Storage services. +Bacula -- in particular, the Director and the Storage services. When time comes for a backup, the Director gets in touch with the File daemon on the client machine and hands it a set of ``marching orders'' which, if -written in English, might be something like the following: +written in English, might be something like the following: OK, {\bf File daemon}, it's time for your daily incremental backup. I want you to get in touch with the Storage daemon on host archive.mysite.com and perform @@ -30,7 +29,7 @@ I've attached include and exclude lists and patterns you should apply when backing up the file system. As this is an incremental backup, you should save only files modified since the time you started your last backup which, as you may recall, was 2000-11-19-06:43:38. Please let me know when you're done and -how it went. Thank you. +how it went. Thank you. So, having been handed everything it needs to decide what to dump and where to store it, the File daemon doesn't need to have any further contact with the @@ -38,31 +37,27 @@ Director until the backup is complete providing there are no errors. If there are errors, the error messages will be delivered immediately to the Director. While the backup is proceeding, the File daemon will send the file coordinates and data for each file being backed up to the Storage daemon, which will in -turn pass the file coordinates to the Director to put in the catalog. +turn pass the file coordinates to the Director to put in the catalog. During a {\bf Verify} of the catalog, the situation is different, since the File daemon will have an exchange with the Director for each file, and will -not contact the Storage daemon. +not contact the Storage daemon. A {\bf Restore} operation will be very similar to the {\bf Backup} except that during the {\bf Restore} the Storage daemon will not send storage coordinates to the Director since the Director presumably already has them. On the other hand, any error messages from either the Storage daemon or File daemon will normally be sent directly to the Directory (this, of course, depends on how -the Message resource is defined). +the Message resource is defined). \section{Commands Received from the Director for a Backup} \index{Backup!Commands Received from the Director for a } \index{Commands Received from the Director for a Backup } -\addcontentsline{toc}{subsection}{Commands Received from the Director for a -Backup} -To be written ... +To be written\ldots{} \section{Commands Received from the Director for a Restore} \index{Commands Received from the Director for a Restore } \index{Restore!Commands Received from the Director for a } -\addcontentsline{toc}{subsection}{Commands Received from the Director for a -Restore} -To be written ... +To be written \ldots{} diff --git a/docs/manuals/en/developers/generaldevel.tex b/docs/manuals/en/developers/generaldevel.tex index 587ce6bf..80ffb1d8 100644 --- a/docs/manuals/en/developers/generaldevel.tex +++ b/docs/manuals/en/developers/generaldevel.tex @@ -5,15 +5,13 @@ \label{_ChapterStart10} \index{Bacula Developer Notes} \index{Notes!Bacula Developer} -\addcontentsline{toc}{section}{Bacula Developer Notes} This document is intended mostly for developers and describes how you can contribute to the Bacula project and the the general framework of making Bacula source changes. -\subsection{Contributions} +\section{Contributions} \index{Contributions} -\addcontentsline{toc}{subsubsection}{Contributions} Contributions to the Bacula project come in many forms: ideas, participation in helping people on the bacula-users email list, packaging @@ -34,12 +32,11 @@ Within this class of contributions, there are two hurdles to surmount. One is getting your patch accepted, and two is dealing with copyright issues. The following text describes some of the requirements for such code. -\subsection{Patches} +\section{Patches} \index{Patches} -\addcontentsline{toc}{subsubsection}{Patches} Subject to the copyright assignment described below, your patches should be -sent in {\bf git format-patch} format relative to the current contents of the +sent in {\bf git format-patch} format relative to the current contents of the master branch of the Source Forge Git repository. Please attach the output file or files generated by the {\bf git format-patch} to the email rather than include them directory to avoid wrapping of the lines @@ -58,15 +55,14 @@ for having developer Git write access so that you can commit your changes directly to the Git repository. To do so, you will need a userid on Source Forge. -\subsection{Copyrights} +\section{Copyrights} \index{Copyrights} -\addcontentsline{toc}{subsubsection}{Copyrights} To avoid future problems concerning changing licensing or copyrights, all code contributions more than a hand full of lines must be in the Public Domain or have the copyright transferred to the Free Software Foundation Europe e.V. with a Fiduciary License -Agreement (FLA) as the case for all the current code. +Agreement (FLA) as the case for all the current code. Prior to November 2004, all the code was copyrighted by Kern Sibbald and John Walker. After November 2004, the code was copyrighted by Kern @@ -90,7 +86,7 @@ previous contributors at \elink{ http://www.mozilla.org/MPL/missing.html} {http://www.mozilla.org/MPL/missing.html}. The other important issue is to avoid copyright, patent, or intellectual property violations as was -(May 2003) claimed by SCO against IBM. +(May 2003) claimed by SCO against IBM. Although the copyright will be held by the Free Software Foundation Europe e.V., each developer is expected to indicate @@ -100,16 +96,15 @@ unusual, but in reality, it is not. Most large projects require this. If you have any doubts about this, please don't hesitate to ask. The -objective is to assure the long term survival of the Bacula project. +objective is to assure the long term survival of the Bacula project. Items not needing a copyright assignment are: most small changes, -enhancements, or bug fixes of 5-10 lines of code, which amount to +enhancements, or bug fixes of 5-10 lines of code, which amount to less than 20% of any particular file. -\subsection{Copyright Assignment -- Fiduciary License Agreement} +\section{Copyright Assignment -- Fiduciary License Agreement} \index{Copyright Assignment} \index{Assignment!Copyright} -\addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement} Since this is not a commercial enterprise, and we prefer to believe in everyone's good faith, previously developers could assign the copyright by @@ -149,7 +144,7 @@ It should be filled out, then sent to: Please note that the above address is different from the officially registered office mentioned in the document. When you send in such a -complete document, please notify me: kern at sibbald dot com, and +complete document, please notify me: kern at sibbald dot com, and please add your email address to the FLA so that I can contact you to confirm reception of the signed FLA. @@ -157,7 +152,6 @@ to confirm reception of the signed FLA. \section{The Development Cycle} \index{Developement Cycle} \index{Cycle!Developement} -\addcontentsline{toc}{subsubsection}{Development Cycle} As discussed on the email lists, the number of contributions are increasing significantly. We expect this positive trend @@ -182,10 +176,10 @@ contributions continue to come -- and they show no signs of let up :-) {\bf Feature Requests:} \\ In addition, we have "formalizee" the feature requests a bit. -Instead of me maintaining an informal list of everything I run into -(kernstodo), we now maintain a "formal" list of projects. This -means that all new feature requests, including those recently discussed on -the email lists, must be formally submitted and approved. +Instead of me maintaining an informal list of everything I run into +(kernstodo), we now maintain a "formal" list of projects. This +means that all new feature requests, including those recently discussed on +the email lists, must be formally submitted and approved. Formal submission of feature requests will take two forms: \\ 1. non-mandatory, but highly recommended is to discuss proposed new features @@ -202,7 +196,7 @@ accept it (90% of the time), send it back asking for clarification (10% of the time), send it to the email list asking for opinions, or reject it (very few cases). -If it is accepted, it will go in the "projects" file (a simple ASCII file) +If it is accepted, it will go in the "projects" file (a simple ASCII file) maintained in the main Bacula source directory. {\bf Implementation of Feature Requests:}\\ @@ -289,7 +283,6 @@ Item 1: Implement a Migration job type that will move the job \section{Bacula Code Submissions and Projects} \index{Submissions and Projects} -\addcontentsline{toc}{subsection}{Code Submissions and Projects} Getting code implemented in Bacula works roughly as follows: @@ -334,18 +327,17 @@ Getting code implemented in Bacula works roughly as follows: \section{Patches for Released Versions} \index{Patches for Released Versions} -\addcontentsline{toc}{subsection}{Patches for Released Versions} If you fix a bug in a released version, you should, unless it is an absolutely trivial bug, create and release a patch file for the bug. The procedure is as follows: Fix the bug in the released branch and in the develpment master branch. -Make a patch file for the branch and add the branch patch to +Make a patch file for the branch and add the branch patch to the patches directory in both the branch and the trunk. -The name should be 2.2.4-xxx.patch where xxx is unique, in this case it can +The name should be 2.2.4-xxx.patch where xxx is unique, in this case it can be "restore", e.g. 2.2.4-restore.patch. Add to the top of the -file a brief description and instructions for applying it -- see for example +file a brief description and instructions for applying it -- see for example 2.2.4-poll-mount.patch. The best way to create the patch file is as follows: @@ -362,7 +354,7 @@ check to make sure no extra junk got put into the patch file (i.e. it should have the patch for that bug only). If there is not a bug report on the problem, create one, then add the -patch to the bug report. +patch to the bug report. Then upload it to the 2.2.x release of bacula-patches. @@ -383,23 +375,22 @@ So, end the end, the patch file is: \section{Developing Bacula} \index{Developing Bacula} \index{Bacula!Developing} -\addcontentsline{toc}{subsubsection}{Developing Bacula} Typically the simplest way to develop Bacula is to open one xterm window pointing to the source directory you wish to update; a second xterm window at the top source directory level, and a third xterm window at the bacula directory \lt{}top\gt{}/src/bacula. After making source changes in one of the directories, in the top source directory xterm, build the source, and start -the daemons by entering: +the daemons by entering: -make and +make and -./startit then in the enter: +./startit then in the enter: -./console or +./console or ./gnome-console to start the Console program. Enter any commands for testing. -For example: run kernsverify full. +For example: run kernsverify full. Note, the instructions here to use {\bf ./startit} are different from using a production system where the administrator starts Bacula by entering {\bf @@ -407,34 +398,32 @@ production system where the administrator starts Bacula by entering {\bf to be run on a computer at the same time that a production system is running. The {\bf ./startit} strip starts {\bf Bacula} using a different set of configuration files, and thus permits avoiding conflicts with any production -system. +system. To make additional source changes, exit from the Console program, and in the -top source directory, stop the daemons by entering: +top source directory, stop the daemons by entering: -./stopit then repeat the process. +./stopit then repeat the process. -\subsection{Debugging} +\section{Debugging} \index{Debugging} -\addcontentsline{toc}{subsubsection}{Debugging} -Probably the first thing to do is to turn on debug output. +Probably the first thing to do is to turn on debug output. A good place to start is with a debug level of 20 as in {\bf ./startit -d20}. The startit command starts all the daemons with the same debug level. Alternatively, you can start the appropriate daemon with the debug level you want. If you really need more info, a debug level of 60 is not bad, and for -just about everything a level of 200. +just about everything a level of 200. -\subsection{Using a Debugger} +\section{Using a Debugger} \index{Using a Debugger} \index{Debugger!Using a} -\addcontentsline{toc}{subsubsection}{Using a Debugger} If you have a serious problem such as a segmentation fault, it can usually be found quickly using a good multiple thread debugger such as {\bf gdb}. For example, suppose you get a segmentation violation in {\bf bacula-dir}. You -might use the following to find the problem: +might use the following to find the problem: \lt{}start the Storage and File daemons\gt{} cd dird @@ -445,18 +434,17 @@ where The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf dird} from going into the background. You may also want to add the {\bf -s} option to the run command to disable signals which can potentially interfere -with the debugging. +with the debugging. As an alternative to using the debugger, each {\bf Bacula} daemon has a built in back trace feature when a serious error is encountered. It calls the debugger on itself, produces a back trace, and emails the report to the developer. For more details on this, please see the chapter in the main Bacula -manual entitled ``What To Do When Bacula Crashes (Kaboom)''. +manual entitled ``What To Do When Bacula Crashes (Kaboom)''. -\subsection{Memory Leaks} +\section{Memory Leaks} \index{Leaks!Memory} \index{Memory Leaks} -\addcontentsline{toc}{subsubsection}{Memory Leaks} Because Bacula runs routinely and unattended on client and server machines, it may run for a long time. As a consequence, from the very beginning, Bacula @@ -468,41 +456,38 @@ during the entire time that Bacula is executing. In that case, there MUST be a routine that can be called at termination time that releases the memory. In this way, we will be able to detect memory leaks. Be sure to immediately correct any and all memory leaks that are printed at the termination of the -daemons. +daemons. -\subsection{Special Files} +\section{Special Files} \index{Files!Special} \index{Special Files} -\addcontentsline{toc}{subsubsection}{Special Files} Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus -any files with these names are subject to being rudely deleted at any time. +any files with these names are subject to being rudely deleted at any time. -\subsection{When Implementing Incomplete Code} +\section{When Implementing Incomplete Code} \index{Code!When Implementing Incomplete} \index{When Implementing Incomplete Code} -\addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code} -Please identify all incomplete code with a comment that contains +Please identify all incomplete code with a comment that contains \begin{lstlisting} ***FIXME*** -\end{lstlisting} +\end{lstlisting} where there are three asterisks (*) before and after the word FIXME (in capitals) and no intervening spaces. This is important as it allows -new programmers to easily recognize where things are partially implemented. +new programmers to easily recognize where things are partially implemented. -\subsection{Bacula Source File Structure} +\section{Bacula Source File Structure} \index{Structure!Bacula Source File} \index{Bacula Source File Structure} -\addcontentsline{toc}{subsubsection}{Bacula Source File Structure} The distribution generally comes as a tar file of the form {\bf bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update -numbers respectively. +numbers respectively. -Once you detar this file, you will have a directory structure as follows: +Once you detar this file, you will have a directory structure as follows: \footnotesize \begin{lstlisting} @@ -568,8 +553,8 @@ Project docs: |- developers (Developer's guide) |- home-page (Bacula's home page source) |- manual (html document directory) - |- manual-fr (French translation) - |- manual-de (German translation) + |- manual-fr (French translation) + |- manual-de (German translation) |- techlogs (Technical development notes); Project rescue: @@ -577,7 +562,7 @@ Project rescue: |- linux (Linux rescue CDROM) |- cdrom (Linux rescue CDROM code) ... - |- solaris (Solaris rescue -- incomplete) + |- solaris (Solaris rescue -- incomplete) |- freebsd (FreeBSD rescue -- incomplete) Project gui: @@ -589,21 +574,20 @@ Project gui: \end{lstlisting} \normalsize -\subsection{Header Files} +\section{Header Files} \index{Header Files} \index{Files!Header} -\addcontentsline{toc}{subsubsection}{Header Files} Please carefully follow the scheme defined below as it permits in general only two header file includes per C file, and thus vastly simplifies programming. With a large complex project like Bacula, it isn't always easy to ensure that the right headers are invoked in the right order (there are a few kludges to make this happen -- i.e. in a few include files because of the chicken and egg -problem, certain references to typedefs had to be replaced with {\bf void} ). +problem, certain references to typedefs had to be replaced with {\bf void} ). Every file should include {\bf bacula.h}. It pulls in just about everything, with very few exceptions. If you have system dependent ifdefing, please do it -in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}. +in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}. Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored, ...) contains a single directory dependent include file generally the name of @@ -611,50 +595,47 @@ the directory, which should be included just after the include of {\bf bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h}) contains either definitions of things generally needed in this directory, or it includes the appropriate header files. It always includes {\bf protos.h}. -See below. +See below. Each subdirectory contains a header file named {\bf protos.h}, which contains the prototypes for subroutines exported by files in that directory. {\bf -protos.h} is always included by the main directory dependent include file. +protos.h} is always included by the main directory dependent include file. -\subsection{Programming Standards} +\section{Programming Standards} \index{Standards!Programming} \index{Programming Standards} -\addcontentsline{toc}{subsubsection}{Programming Standards} For the most part, all code should be written in C unless there is a burning reason to use C++, and then only the simplest C++ constructs will be used. -Note, Bacula is slowly evolving to use more and more C++. +Note, Bacula is slowly evolving to use more and more C++. Code should have some documentation -- not a lot, but enough so that I can understand it. Look at the current code, and you will see that I document more -than most, but am definitely not a fanatic. +than most, but am definitely not a fanatic. We prefer simple linear code where possible. Gotos are strongly discouraged except for handling an error to either bail out or to retry some code, and -such use of gotos can vastly simplify the program. +such use of gotos can vastly simplify the program. Remember this is a C program that is migrating to a {\bf tiny} subset of C++, -so be conservative in your use of C++ features. +so be conservative in your use of C++ features. -\subsection{Do Not Use} +\section{Do Not Use} \index{Use!Do Not} \index{Do Not Use} -\addcontentsline{toc}{subsubsection}{Do Not Use} \begin{bsysitemize} - \item STL -- it is totally incomprehensible. + \item STL -- it is totally incomprehensible. \end{bsysitemize} -\subsection{Avoid if Possible} +\section{Avoid if Possible} \index{Possible!Avoid if} \index{Avoid if Possible} -\addcontentsline{toc}{subsubsection}{Avoid if Possible} \begin{bsysitemize} \item Using {\bf void *} because this generally means that one must using casting, and in C++ casting is rather ugly. It is OK to use - void * to pass structure address where the structure is not known + void * to pass structure address where the structure is not known to the routines accepting the packet (typically callback routines). However, declaring "void *buf" is a bad idea. Please use the correct types whenever possible. @@ -662,50 +643,49 @@ so be conservative in your use of C++ features. \item Using undefined storage specifications such as (short, int, long, long long, size\_t ...). The problem with all these is that the number of bytes they allocate depends on the compiler and the system. Instead use - Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and + Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and uint64\_t). This guarantees that the variables are given exactly the size you want. Please try at all possible to avoid using size\_t ssize\_t and the such. They are very system dependent. However, some system routines may need them, so their use is often unavoidable. \item Returning a malloc'ed buffer from a subroutine -- someone will forget - to release it. + to release it. \item Heap allocation (malloc) unless needed -- it is expensive. Use POOL\_MEM instead. -\item Templates -- they can create portability problems. +\item Templates -- they can create portability problems. \item Fancy or tricky C or C++ code, unless you give a good explanation of - why you used it. + why you used it. \item Too much inheritance -- it can complicate the code, and make reading it - difficult (unless you are in love with colons) + difficult (unless you are in love with colons) \end{bsysitemize} -\subsection{Do Use Whenever Possible} +\section{Do Use Whenever Possible} \index{Possible!Do Use Whenever} \index{Do Use Whenever Possible} -\addcontentsline{toc}{subsubsection}{Do Use Whenever Possible} \begin{bsysitemize} -\item Locking and unlocking within a single subroutine. +\item Locking and unlocking within a single subroutine. -\item A single point of exit from all subroutines. A goto is +\item A single point of exit from all subroutines. A goto is perfectly OK to use to get out early, but only to a label named bail\_out, and possibly an ok\_out. See current code examples. -\item malloc and free within a single subroutine. +\item malloc and free within a single subroutine. -\item Comments and global explanations on what your code or algorithm does. +\item Comments and global explanations on what your code or algorithm does. \item When committing a fix for a bug, make the comment of the following form: \begin{lstlisting} -Reason for bug fix or other message. Fixes bug #1234 +Reason for bug fix or other message. Fixes bug #1234 \end{lstlisting} It is important to write the {\bf bug \#1234} like @@ -741,24 +721,23 @@ keywords (or phrases), it will be ignored: \end{lstlisting} \item Use the following keywords at the beginning of -a git commit message +a git commit message \end{bsysitemize} -\subsection{Indenting Standards} +\section{Indenting Standards} \index{Standards!Indenting} \index{Indenting Standards} -\addcontentsline{toc}{subsubsection}{Indenting Standards} -We find it very hard to read code indented 8 columns at a time. +We find it very hard to read code indented 8 columns at a time. Even 4 at a time uses a lot of space, so we have adopted indenting 3 spaces at every level. Note, indention is the visual appearance of the source on the page, while tabbing is replacing a series of up to 8 spaces from -a tab character. +a tab character. The closest set of parameters for the Linux {\bf indent} program that will -produce reasonably indented code are: +produce reasonably indented code are: \footnotesize \begin{lstlisting} @@ -770,11 +749,11 @@ produce reasonably indented code are: You can put the above in your .indent.pro file, and then just invoke indent on your file. However, be warned. This does not produce perfect indenting, and it -will mess up C++ class statements pretty badly. +will mess up C++ class statements pretty badly. Braces are required in all if statements (missing in some very old code). To avoid generating too many lines, the first brace appears on the first line -(e.g. of an if), and the closing brace is on a line by itself. E.g. +(e.g. of an if), and the closing brace is on a line by itself. E.g. \footnotesize \begin{lstlisting} @@ -784,7 +763,7 @@ avoid generating too many lines, the first brace appears on the first line \end{lstlisting} \normalsize -Just follow the convention in the code. For example we I prefer non-indented cases. +Just follow the convention in the code. For example we I prefer non-indented cases. \footnotesize \begin{lstlisting} @@ -803,24 +782,24 @@ Just follow the convention in the code. For example we I prefer non-indented cas Avoid using // style comments except for temporary code or turning off debug code. Standard C comments are preferred (this also keeps the code closer to -C). +C). Attempt to keep all lines less than 85 characters long so that the whole line -of code is readable at one time. This is not a rigid requirement. +of code is readable at one time. This is not a rigid requirement. Always put a brief description at the top of any new file created describing what it does and including your name and the date it was first written. Please don't forget any Copyrights and acknowledgments if it isn't 100\% your code. -Also, include the Bacula copyright notice that is in {\bf src/c}. +Also, include the Bacula copyright notice that is in {\bf src/c}. In general you should have two includes at the top of the an include for the particular directory the code is in, for includes are needed, but this should -be rare. +be rare. In general (except for self-contained packages), prototypes should all be put -in {\bf protos.h} in each directory. +in {\bf protos.h} in each directory. -Always put space around assignment and comparison operators. +Always put space around assignment and comparison operators. \footnotesize \begin{lstlisting} @@ -831,7 +810,7 @@ Always put space around assignment and comparison operators. \end{lstlisting} \normalsize -but your can compress things in a {\bf for} statement: +but your can compress things in a {\bf for} statement: \footnotesize \begin{lstlisting} @@ -841,7 +820,7 @@ but your can compress things in a {\bf for} statement: \normalsize Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a -print statement, e.g.: +print statement, e.g.: \footnotesize \begin{lstlisting} @@ -855,32 +834,30 @@ print statement, e.g.: Leave a certain amount of debug code (Dmsg) in code you submit, so that future problems can be identified. This is particularly true for complicated code likely to break. However, try to keep the debug code to a minimum to avoid -bloating the program and above all to keep the code readable. +bloating the program and above all to keep the code readable. Please keep the same style in all new code you develop. If you include code previously written, you have the option of leaving it with the old indenting or re-indenting it. If the old code is indented with 8 spaces, then please -re-indent it to Bacula standards. +re-indent it to Bacula standards. If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth -to 3. +to 3. -\subsection{Tabbing} +\section{Tabbing} \index{Tabbing} -\addcontentsline{toc}{subsubsection}{Tabbing} Tabbing (inserting the tab character in place of spaces) is as normal on all Unix systems -- a tab is converted space up to the next column multiple of 8. My editor converts strings of spaces to tabs automatically -- this results in significant compression of the files. Thus, you can remove tabs by replacing them with spaces if you wish. Please don't confuse tabbing (use of tab -characters) with indenting (visual alignment of the code). +characters) with indenting (visual alignment of the code). -\subsection{Don'ts} +\section{Don'ts} \index{Don'ts} -\addcontentsline{toc}{subsubsection}{Don'ts} -Please don't use: +Please don't use: \footnotesize \begin{lstlisting} @@ -894,7 +871,7 @@ snprintf() \normalsize They are system dependent and un-safe. These should be replaced by the Bacula -safe equivalents: +safe equivalents: \footnotesize \begin{lstlisting} @@ -905,11 +882,11 @@ int bvsnprintf(char *str, int32_t size, const char *format, va_list ap); \end{lstlisting} \normalsize -See src/lib/bsys.c for more details on these routines. +See src/lib/bsys.c for more details on these routines. Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit 64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf -edit\_uint64()}. For example: +edit\_uint64()}. For example: \footnotesize \begin{lstlisting} @@ -931,26 +908,24 @@ screaming that I use {\bf lld}. I actually use subtle trick taught to me by John Walker. The {\bf lld} that appears in the editing routine is actually {\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and is defined in autoconf/configure.in for each OS. C string concatenation causes -the appropriate string to be concatenated to the ``\%''. +the appropriate string to be concatenated to the ``\%''. -Also please don't use the STL or Templates or any complicated C++ code. +Also please don't use the STL or Templates or any complicated C++ code. -\subsection{Message Classes} +\section{Message Classes} \index{Classes!Message} \index{Message Classes} -\addcontentsline{toc}{subsubsection}{Message Classes} -Currently, there are five classes of messages: Debug, Error, Job, Memory, +Currently, there are five classes of messages: Debug, Error, Job, Memory, and Queued. -\subsection{Debug Messages} +\section{Debug Messages} \index{Messages!Debug} \index{Debug Messages} -\addcontentsline{toc}{subsubsection}{Debug Messages} Debug messages are designed to be turned on at a specified debug level and are always sent to STDOUT. There are designed to only be used in the development -debug process. They are coded as: +debug process. They are coded as: DmsgN(level, message, arg1, ...) where the N is a number indicating how many arguments are to be substituted into the message (i.e. it is a count of the @@ -958,66 +933,46 @@ number arguments you have in your message -- generally the number of percent signs (\%)). {\bf level} is the debug level at which you wish the message to be printed. message is the debug message to be printed, and arg1, ... are the arguments to be substituted. Since not all compilers support \#defines with -varargs, you must explicitly specify how many arguments you have. +varargs, you must explicitly specify how many arguments you have. When the debug message is printed, it will automatically be prefixed by the name of the daemon which is running, the filename where the Dmsg is, and the -line number within the file. +line number within the file. -Some actual examples are: +Some actual examples are: -Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf); +Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf); -Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name); +Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name); -\subsection{Error Messages} +\section{Error Messages} \index{Messages!Error} \index{Error Messages} -\addcontentsline{toc}{subsubsection}{Error Messages} Error messages are messages that are related to the daemon as a whole rather than a particular job. For example, an out of memory condition my generate an error message. They should be very rarely needed. In general, you should be -using Job and Job Queued messages (Jmsg and Qmsg). They are coded as: - -EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must -explicitly code the of arguments to be substituted in the message. error-code -indicates the severity or class of error, and it may be one of the following: - -\addcontentsline{lot}{table}{Message Error Code Classes} -\begin{longtable}{lp{3in}} -{{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be -used only in extreme cases. It attempts to produce a traceback. } \\ -{{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This -should be used only in extreme cases. It does not produce a traceback. } \\ -{{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the -daemon keeps running } \\ -{{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue -running } \\ -{{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job -continue running } \\ -{{\bf M\_INFO} } & {Reports an informational message.} - -\end{longtable} +using Job and Job Queued messages (Jmsg and Qmsg). They are coded as: + +EmsgN(error-code, level, message, arg1, \ldots{}) As with debug messages, you + must explicitly code the of arguments to be substituted in the message. + Error-code indicates the severity or class of error, and it may be one of the + following (See table \vref{tabdev:errorcodes}: +\LTXtable{\linewidth}{table_errorcodes} There are other error message classes, but they are in a state of being redesigned or deprecated, so please do not use them. Some actual examples are: +\begin{lstlisting} +Emsg1(M\_ABORT, 0, ``Cannot create message thread: %s\n'',strerror(status)); +Emsg3(M\_WARNING, 0, ``Connect to File daemon %s at %s:%d failed. Retrying...\n'', client->hdr.name, client->address,client->port); -Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'', -strerror(status)); - -Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying -...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address, -client-\gt{}port); - -Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command: -\%d \%s\textbackslash{}n'', cmd, n, strerror(errno)); +Emsg3(M\_FATAL, 0, ``bdird -If the Jmsg is followed with a number such as Jmsg1(...), the number +If the Jmsg is followed with a number such as Jmsg1(\ldots{}), the number indicates the number of arguments to be substituted (varargs is not standard for \#defines), and what is more important is that the file and line number will be prefixed to the message. This permits a sort of debug from user's output. -\subsection{Queued Job Messages} +\section{Queued Job Messages} \index{Queued Job Messages} \index{Messages!Job} -\addcontentsline{toc}{subsubsection}{Queued Job Messages} Queued Job messages are similar to Jmsg()s except that the message is Queued rather than immediately dispatched. This is necessary within the network subroutines and in the message editing routines. This is to prevent @@ -1046,24 +1000,22 @@ recursive loops, and to ensure that messages can be delivered even in the event of a network error. -\subsection{Memory Messages} +\section{Memory Messages} \index{Messages!Memory} \index{Memory Messages} -\addcontentsline{toc}{subsubsection}{Memory Messages} Memory messages are messages that are edited into a memory buffer. Generally they are used in low level routines such as the low level device file dev.c in the Storage daemon or in the low level Catalog routines. These routines do not generally have access to the Job Control Record and so they return error -essages reformatted in a memory buffer. Mmsg() is the way to do this. +essages reformatted in a memory buffer. Mmsg() is the way to do this. -\subsection{Bugs Database} +\section{Bugs Database} \index{Database!Bugs} \index{Bugs Database} -\addcontentsline{toc}{subsubsection}{Bugs Database} We have a bugs database which is at: \elink{http://bugs.bacula.org}{http://bugs.bacula.org}, and as -a developer you will need to respond to bugs, perhaps bugs in general +a developer you will need to respond to bugs, perhaps bugs in general if you have time, otherwise just bugs that correspond to code that you wrote. @@ -1093,17 +1045,17 @@ close bug reports rather quickly, even without confirmation, especially if we have run tests and can see that for us the problem is fixed. However, in doing so, it avoids misunderstandings if you leave a note while you are closing the bug that says something to the following effect: -We are closing this bug because ... If for some reason, it does not fix +We are closing this bug because \ldots{} If for some reason, it does not fix your problem, please feel free to reopen it, or to open a new bug report describing the problem". We do not recommend that you attempt to edit any of the bug notes that have been submitted, nor to delete them or make them private. In fact, if someone accidentally makes a bug note private, you should ask the reason -and if at all possible (with his agreement) make the bug note public. +and if at all possible (with his agreement) make the bug note public. If the user has not properly filled in most of the important fields -(platorm, OS, Product Version, ...) please do not hesitate to politely ask +(platorm, OS, Product Version, \ldots{}) please do not hesitate to politely ask him. Also, if the bug report is a request for a new feature, please politely send the user to the Feature Request menu item on www.bacula.org. The same applies to a support request (we answer only bugs), you might give diff --git a/docs/manuals/en/developers/git.tex b/docs/manuals/en/developers/git.tex index e97f736d..60f50a9e 100644 --- a/docs/manuals/en/developers/git.tex +++ b/docs/manuals/en/developers/git.tex @@ -2,7 +2,6 @@ \label{_GitChapterStart} \index{Git} \index{Git!Repo} -\addcontentsline{toc}{section}{Bacula Bit Usage} This chapter is intended to help you use the Git source code repositories to obtain, modify, and submit Bacula source code. @@ -10,7 +9,6 @@ repositories to obtain, modify, and submit Bacula source code. \section{Bacula Git repositories} \index{Git} -\addcontentsline{toc}{subsection}{Git repositories} As of September 2009, the Bacula source code has been split into three Git repositories. One is a repository that holds the main Bacula source code with directories {\bf bacula}, {\bf gui}, @@ -35,7 +33,6 @@ Bacula developers must now have a certain knowledege of Git. \section{Git Usage} \index{Git Usage} -\addcontentsline{toc}{subsection}{Git Usage} Please note that if you are familiar with SVN, Git is similar, (and better), but there can be a few surprising differences that diff --git a/docs/manuals/en/developers/gui-interface.tex b/docs/manuals/en/developers/gui-interface.tex index e3a86524..ee5f857c 100644 --- a/docs/manuals/en/developers/gui-interface.tex +++ b/docs/manuals/en/developers/gui-interface.tex @@ -5,19 +5,16 @@ \label{_ChapterStart} \index[general]{Interface!Implementing a Bacula GUI } \index[general]{Implementing a Bacula GUI Interface } -\addcontentsline{toc}{section}{Implementing a Bacula GUI Interface} \section{General} \index[general]{General } -\addcontentsline{toc}{subsection}{General} This document is intended mostly for developers who wish to develop a new GUI -interface to {\bf Bacula}. +interface to {\bf Bacula}. \subsection{Minimal Code in Console Program} \index[general]{Program!Minimal Code in Console } \index[general]{Minimal Code in Console Program } -\addcontentsline{toc}{subsubsection}{Minimal Code in Console Program} Until now, I have kept all the Catalog code in the Directory (with the exception of dbcheck and bscan). This is because at some point I would like to @@ -25,38 +22,37 @@ add user level security and access. If we have code spread everywhere such as in a GUI this will be more difficult. The other advantage is that any code you add to the Director is automatically available to both the tty console program and the WX program. The major disadvantage is it increases the size of the -code -- however, compared to Networker the Bacula Director is really tiny. +code -- however, compared to Networker the Bacula Director is really tiny. \subsection{GUI Interface is Difficult} \index[general]{GUI Interface is Difficult } \index[general]{Difficult!GUI Interface is } -\addcontentsline{toc}{subsubsection}{GUI Interface is Difficult} Interfacing to an interactive program such as Bacula can be very difficult because the interfacing program must interpret all the prompts that may come. This can be next to impossible. There are are a number of ways that Bacula is -designed to facilitate this: +designed to facilitate this: \begin{bsysitemize} \item The Bacula network protocol is packet based, and thus pieces of -information sent can be ASCII or binary. -\item The packet interface permits knowing where the end of a list is. +information sent can be ASCII or binary. +\item The packet interface permits knowing where the end of a list is. \item The packet interface permits special ``signals'' to be passed rather -than data. +than data. \item The Director has a number of commands that are non-interactive. They -all begin with a period, and provide things such as the list of all Jobs, +all begin with a period, and provide things such as the list of all Jobs, list of all Clients, list of all Pools, list of all Storage, ... Thus the GUI interface can get to virtually all information that the Director has in a -deterministic way. See \lt{}bacula-source\gt{}/src/dird/ua\_dotcmds.c for -more details on this. +deterministic way. See \lt{}bacula-source\gt{}/src/dird/ua\_dotcmds.c for +more details on this. \item Most console commands allow all the arguments to be specified on the -command line: e.g. {\bf run job=NightlyBackup level=Full} +command line: e.g. {\bf run job=NightlyBackup level=Full} \end{bsysitemize} One of the first things to overcome is to be able to establish a conversation with the Director. Although you can write all your own code, it is probably easier to use the Bacula subroutines. The following code is used by the -Console program to begin a conversation. +Console program to begin a conversation. \footnotesize \begin{lstlisting} @@ -85,7 +81,7 @@ static JCR *jcr; \end{lstlisting} \normalsize -Then the read\_and\_process\_input routine looks like the following: +Then the read\_and\_process\_input routine looks like the following: \footnotesize \begin{lstlisting} diff --git a/docs/manuals/en/developers/md5.tex b/docs/manuals/en/developers/md5.tex index aed995b4..d742446e 100644 --- a/docs/manuals/en/developers/md5.tex +++ b/docs/manuals/en/developers/md5.tex @@ -3,36 +3,31 @@ \chapter{Bacula MD5 Algorithm} \label{MD5Chapter} -\addcontentsline{toc}{section}{} \section{Command Line Message Digest Utility } \index{Utility!Command Line Message Digest } \index{Command Line Message Digest Utility } -\addcontentsline{toc}{subsection}{Command Line Message Digest Utility} This page describes {\bf md5}, a command line utility usable on either Unix or MS-DOS/Windows, which generates and verifies message digests (digital signatures) using the MD5 algorithm. This program can be useful when developing shell scripts or Perl programs for software installation, file -comparison, and detection of file corruption and tampering. +comparison, and detection of file corruption and tampering. \subsection{Name} \index{Name} -\addcontentsline{toc}{subsubsection}{Name} -{\bf md5} - generate / check MD5 message digest +{\bf md5} - generate / check MD5 message digest \subsection{Synopsis} \index{Synopsis } -\addcontentsline{toc}{subsubsection}{Synopsis} {\bf md5} [ {\bf -c}{\it signature} ] [ {\bf -u} ] [ {\bf -d}{\it input\_text} -| {\it infile} ] [ {\it outfile} ] +| {\it infile} ] [ {\it outfile} ] \subsection{Description} \index{Description } -\addcontentsline{toc}{subsubsection}{Description} A {\it message digest} is a compact digital signature for an arbitrarily long stream of binary data. An ideal message digest algorithm would never generate @@ -43,32 +38,32 @@ signature of modest size created with an algorithm designed to make preparation of input text with a given signature computationally infeasible. Message digest algorithms have much in common with techniques used in encryption, but to a different end; verification that data have not been -altered since the signature was published. +altered since the signature was published. Many older programs requiring digital signatures employed 16 or 32 bit {\it cyclical redundancy codes} (CRC) originally developed to verify correct transmission in data communication protocols, but these short codes, while adequate to detect the kind of transmission errors for which they were intended, are insufficiently secure for applications such as electronic -commerce and verification of security related software distributions. +commerce and verification of security related software distributions. The most commonly used present-day message digest algorithm is the 128 bit MD5 -algorithm, developed by Ron Rivest of the -\elink{MIT}{http://web.mit.edu/} -\elink{Laboratory for Computer Science}{http://www.lcs.mit.edu/} and +algorithm, developed by Ron Rivest of the +\elink{MIT}{http://web.mit.edu/} +\elink{Laboratory for Computer Science}{http://www.lcs.mit.edu/} and \elink{RSA Data Security, Inc.}{http://www.rsa.com/} The algorithm, with a -reference implementation, was published as Internet +reference implementation, was published as Internet \elink{RFC 1321}{http://www.fourmilab.ch/md5/rfc1321.html} in April 1992, and was placed into the public domain at that time. Message digest algorithms such as MD5 are not deemed ``encryption technology'' and are not subject to the export controls some governments impose on other data security products. (Obviously, the responsibility for obeying the laws in the jurisdiction in which you reside is entirely your own, but many common Web and Mail utilities -use MD5, and I am unaware of any restrictions on their distribution and use.) +use MD5, and I am unaware of any restrictions on their distribution and use.) The MD5 algorithm has been implemented in numerous computer languages -including C, -\elink{Perl}{http://www.perl.org/}, and +including C, +\elink{Perl}{http://www.perl.org/}, and \elink{Java}{http://www.javasoft.com/}; if you're writing a program in such a language, track down a suitable subroutine and incorporate it into your program. The program described on this page is a {\it command line} @@ -77,15 +72,14 @@ is much faster than computing an MD5 signature directly in Perl). This {\bf md5} program was originally developed as part of a suite of tools intended to monitor large collections of files (for example, the contents of a Web site) to detect corruption of files and inadvertent (or perhaps malicious) changes. -That task is now best accomplished with more comprehensive packages such as +That task is now best accomplished with more comprehensive packages such as \elink{Tripwire}{ftp://coast.cs.purdue.edu/pub/COAST/Tripwire/}, but the command line {\bf md5} component continues to prove useful for verifying correct delivery and installation of software packages, comparing the contents -of two different systems, and checking for changes in specific files. +of two different systems, and checking for changes in specific files. \subsection{Options} \index{Options } -\addcontentsline{toc}{subsubsection}{Options} \begin{description} @@ -96,89 +90,82 @@ by the {\bf -d} option and compares it against the specified {\it signature}. If the two signatures match, the exit status will be zero, otherwise the exit status will be 1. No signature is written to {\it outfile} or standard output; only the exit status is set. The signature to be checked must be -specified as 32 hexadecimal digits. +specified as 32 hexadecimal digits. \item [{\bf -d}{\it input\_text} ] \index{-dinput\_text } A signature is computed for the given {\it input\_text} (which must be quoted if it contains white space characters) instead of input from {\it infile} or standard input. If input is specified with the {\bf -d} option, no {\it -infile} should be specified. +infile} should be specified. \item [{\bf -u} ] - Print how-to-call information. + Print how-to-call information. \end{description} \subsection{Files} \index{Files } -\addcontentsline{toc}{subsubsection}{Files} If no {\it infile} or {\bf -d} option is specified or {\it infile} is a single ``-'', {\bf md5} reads from standard input; if no {\it outfile} is given, or {\it outfile} is a single ``-'', output is sent to standard output. Input and output are processed strictly serially; consequently {\bf md5} may be used in -pipelines. +pipelines. \subsection{Bugs} \index{Bugs } -\addcontentsline{toc}{subsubsection}{Bugs} The mechanism used to set standard input to binary mode may be specific to Microsoft C; if you rebuild the DOS/Windows version of the program from source using another compiler, be sure to verify binary files work properly when read -via redirection or a pipe. +via redirection or a pipe. This program has not been tested on a machine on which {\tt int} and/or {\tt -long} are longer than 32 bits. +long} are longer than 32 bits. \section{ \elink{Download md5.zip}{http://www.fourmilab.ch/md5/md5.zip} (Zipped archive)} \index{Archive!Download md5.zip Zipped } \index{Download md5.zip (Zipped archive) } -\addcontentsline{toc}{subsection}{Download md5.zip (Zipped archive)} -The program is provided as -\elink{md5.zip}{http://www.fourmilab.ch/md5/md5.zip}, a +The program is provided as +\elink{md5.zip}{http://www.fourmilab.ch/md5/md5.zip}, a \elink{Zipped}{http://www.pkware.com/} archive containing an ready-to-run Win32 command-line executable program, {\tt md5.exe} (compiled using Microsoft Visual C++ 5.0), and in source code form along with a {\tt Makefile} to build -the program under Unix. +the program under Unix. \subsection{See Also} \index{ALSO!SEE } \index{See Also } -\addcontentsline{toc}{subsubsection}{SEE ALSO} -{\bf sum}(1) +{\bf sum}(1) \subsection{Exit Status} \index{Status!Exit } \index{Exit Status } -\addcontentsline{toc}{subsubsection}{Exit Status} {\bf md5} returns status 0 if processing was completed without errors, 1 if the {\bf -c} option was specified and the given signature does not match that of the input, and 2 if processing could not be performed at all due, for -example, to a nonexistent input file. +example, to a nonexistent input file. \subsection{Copying} \index{Copying } -\addcontentsline{toc}{subsubsection}{Copying} \begin{quote} This software is in the public domain. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. This software -is provided ``as is'' without express or implied warranty. +is provided ``as is'' without express or implied warranty. \end{quote} \subsection{Acknowledgements} \index{Acknowledgements } -\addcontentsline{toc}{subsubsection}{Acknowledgements} The MD5 algorithm was developed by Ron Rivest. The public domain C language -implementation used in this program was written by Colin Plumb in 1993. -{\it +implementation used in this program was written by Colin Plumb in 1993. +{\it \elink{by John Walker}{http://www.fourmilab.ch/} -January 6th, MIM } +January 6th, MIM } diff --git a/docs/manuals/en/developers/mediaformat.tex b/docs/manuals/en/developers/mediaformat.tex index 27611c47..0c204b4a 100644 --- a/docs/manuals/en/developers/mediaformat.tex +++ b/docs/manuals/en/developers/mediaformat.tex @@ -790,7 +790,6 @@ the File-Attributes separated by spaces. The File-attributes consist of the following: -%\addcontentsline{lot}{table}{File Attributes} \LTXtable{\linewidth}{table_fileattributes} \section{Old Depreciated Tape Format} diff --git a/docs/manuals/en/developers/mempool.tex b/docs/manuals/en/developers/mempool.tex index 08b2d13d..22b2cc4d 100644 --- a/docs/manuals/en/developers/mempool.tex +++ b/docs/manuals/en/developers/mempool.tex @@ -5,35 +5,32 @@ \label{_ChapterStart7} \index{Management!Bacula Memory} \index{Bacula Memory Management} -\addcontentsline{toc}{section}{Bacula Memory Management} \section{General} \index{General} -\addcontentsline{toc}{subsection}{General} This document describes the memory management routines that are used in Bacula and is meant to be a technical discussion for developers rather than part of -the user manual. +the user manual. Since Bacula may be called upon to handle filenames of varying and more or less arbitrary length, special attention needs to be used in the code to ensure that memory buffers are sufficiently large. There are four possibilities for memory usage within {\bf Bacula}. Each will be described in -turn. They are: +turn. They are: \begin{bsysitemize} -\item Statically allocated memory. -\item Dynamically allocated memory using malloc() and free(). -\item Non-pooled memory. -\item Pooled memory. +\item Statically allocated memory. +\item Dynamically allocated memory using malloc() and free(). +\item Non-pooled memory. +\item Pooled memory. \end{bsysitemize} \subsection{Statically Allocated Memory} \index{Statically Allocated Memory} \index{Memory!Statically Allocated} -\addcontentsline{toc}{subsubsection}{Statically Allocated Memory} -Statically allocated memory is of the form: +Statically allocated memory is of the form: \footnotesize \begin{lstlisting} @@ -46,15 +43,14 @@ that the strings to be used will be of a fixed length. One example of where this is appropriate is for {\bf Bacula} resource names, which are currently limited to 127 characters (MAX\_NAME\_LENGTH). Although this maximum size may change, particularly to accommodate Unicode, it will remain a relatively small -value. +value. \subsection{Dynamically Allocated Memory} \index{Dynamically Allocated Memory} \index{Memory!Dynamically Allocated} -\addcontentsline{toc}{subsubsection}{Dynamically Allocated Memory} Dynamically allocated memory is obtained using the standard malloc() routines. -As in: +As in: \footnotesize \begin{lstlisting} @@ -63,7 +59,7 @@ buf = malloc(256); \end{lstlisting} \normalsize -This kind of memory can be released with: +This kind of memory can be released with: \footnotesize \begin{lstlisting} @@ -78,12 +74,11 @@ memory. An example might be to obtain a large memory buffer for reading and writing files. When {\bf SmartAlloc} is enabled, the memory obtained by malloc() will automatically be checked for buffer overwrite (overflow) during the free() call, and all malloc'ed memory that is not released prior to -termination of the program will be reported as Orphaned memory. +termination of the program will be reported as Orphaned memory. \subsection{Pooled and Non-pooled Memory} \index{Memory!Pooled and Non-pooled} \index{Pooled and Non-pooled Memory} -\addcontentsline{toc}{subsubsection}{Pooled and Non-pooled Memory} In order to facility the handling of arbitrary length filenames and to efficiently handle a high volume of dynamic memory usage, we have implemented @@ -95,29 +90,29 @@ block. In addition, each memory block has its current size associated with the block allowing for easy checking if the buffer is of sufficient size. This kind of memory would normally be used in high volume situations (lots of malloc()s and free()s) where the buffer length may have to frequently change -to adapt to varying filename lengths. +to adapt to varying filename lengths. The non-pooled memory is handled by routines similar to those used for pooled memory, allowing for easy size checking. However, non-pooled memory is returned to the system rather than being saved in the Bacula pool. This kind of memory would normally be used in low volume situations (few malloc()s and free()s), but where the size of the buffer might have to be adjusted -frequently. +frequently. \paragraph*{Types of Memory Pool:} -Currently there are three memory pool types: +Currently there are three memory pool types: \begin{bsysitemize} -\item PM\_NOPOOL -- non-pooled memory. -\item PM\_FNAME -- a filename pool. -\item PM\_MESSAGE -- a message buffer pool. -\item PM\_EMSG -- error message buffer pool. +\item PM\_NOPOOL -- non-pooled memory. +\item PM\_FNAME -- a filename pool. +\item PM\_MESSAGE -- a message buffer pool. +\item PM\_EMSG -- error message buffer pool. \end{bsysitemize} \paragraph*{Getting Memory:} -To get memory, one uses: +To get memory, one uses: \footnotesize \begin{lstlisting} @@ -127,9 +122,9 @@ void *get_pool_memory(pool); where {\bf pool} is one of the above mentioned pool names. The size of the memory returned will be determined by the system to be most appropriate for -the application. +the application. -If you wish non-pooled memory, you may alternatively call: +If you wish non-pooled memory, you may alternatively call: \footnotesize \begin{lstlisting} @@ -138,11 +133,11 @@ void *get_memory(size_t size); \normalsize The buffer length will be set to the size specified, and it will be assigned -to the PM\_NOPOOL pool (no pooling). +to the PM\_NOPOOL pool (no pooling). \paragraph*{Releasing Memory:} -To free memory acquired by either of the above two calls, use: +To free memory acquired by either of the above two calls, use: \footnotesize \begin{lstlisting} @@ -153,11 +148,11 @@ void free_pool_memory(void *buffer); where buffer is the memory buffer returned when the memory was acquired. If the memory was originally allocated as type PM\_NOPOOL, it will be released to the system, otherwise, it will be placed on the appropriate Bacula memory pool -free chain to be used in a subsequent call for memory from that pool. +free chain to be used in a subsequent call for memory from that pool. \paragraph*{Determining the Memory Size:} -To determine the memory buffer size, use: +To determine the memory buffer size, use: \footnotesize \begin{lstlisting} @@ -167,7 +162,7 @@ size_t sizeof_pool_memory(void *buffer); \paragraph*{Resizing Pool Memory:} -To resize pool memory, use: +To resize pool memory, use: \footnotesize \begin{lstlisting} @@ -176,12 +171,12 @@ void *realloc_pool_memory(void *buffer); \normalsize The buffer will be reallocated, and the contents of the original buffer will -be preserved, but the address of the buffer may change. +be preserved, but the address of the buffer may change. \paragraph*{Automatic Size Adjustment:} To have the system check and if necessary adjust the size of your pooled -memory buffer, use: +memory buffer, use: \footnotesize \begin{lstlisting} @@ -194,12 +189,12 @@ already equal to or larger than {\bf new-size} no buffer size change will occur. However, if a buffer size change is needed, the original contents of the buffer will be preserved, but the buffer address may change. Many of the low level Bacula subroutines expect to be passed a pool memory buffer and use -this call to ensure the buffer they use is sufficiently large. +this call to ensure the buffer they use is sufficiently large. \paragraph*{Releasing All Pooled Memory:} In order to avoid orphaned buffer error messages when terminating the program, -use: +use: \footnotesize \begin{lstlisting} @@ -209,12 +204,12 @@ void close_memory_pool(); to free all unused memory retained in the Bacula memory pool. Note, any memory not returned to the pool via free\_pool\_memory() will not be released by this -call. +call. \paragraph*{Pooled Memory Statistics:} For debugging purposes and performance tuning, the following call will print -the current memory pool statistics: +the current memory pool statistics: \footnotesize \begin{lstlisting} @@ -222,7 +217,7 @@ void print_memory_pool_stats(); \end{lstlisting} \normalsize -an example output is: +an example output is: \footnotesize \begin{lstlisting} diff --git a/docs/manuals/en/developers/netprotocol.tex b/docs/manuals/en/developers/netprotocol.tex index 4e9dc326..a6a7d997 100644 --- a/docs/manuals/en/developers/netprotocol.tex +++ b/docs/manuals/en/developers/netprotocol.tex @@ -5,182 +5,164 @@ \label{_ChapterStart5} \index{TCP/IP Network Protocol} \index{Protocol!TCP/IP Network} -\addcontentsline{toc}{section}{TCP/IP Network Protocol} \section{General} \index{General} -\addcontentsline{toc}{subsection}{General} This document describes the TCP/IP protocol used by Bacula to communicate between the various daemons and services. The definitive definition of the protocol can be found in src/lib/bsock.h, src/lib/bnet.c and -src/lib/bnet\_server.c. +src/lib/bnet\_server.c. Bacula's network protocol is basically a ``packet oriented'' protocol built on a standard TCP/IP streams. At the lowest level all packet transfers are done with read() and write() requests on system sockets. Pipes are not used as they are considered unreliable for large serial data transfers between various -hosts. +hosts. Using the routines described below (bnet\_open, bnet\_write, bnet\_recv, and bnet\_close) guarantees that the number of bytes you write into the socket will be received as a single record on the other end regardless of how many low level write() and read() calls are needed. All data transferred are -considered to be binary data. +considered to be binary data. \section{bnet and Threads} \index{Threads!bnet and} \index{Bnet and Threads} -\addcontentsline{toc}{subsection}{bnet and Threads} These bnet routines work fine in a threaded environment. However, they assume that there is only one reader or writer on the socket at any time. It is highly recommended that only a single thread access any BSOCK packet. The exception to this rule is when the socket is first opened and it is waiting for a job to start. The wait in the Storage daemon is done in one thread and -then passed to another thread for subsequent handling. +then passed to another thread for subsequent handling. If you envision having two threads using the same BSOCK, think twice, then you must implement some locking mechanism. However, it probably would not be -appropriate to put locks inside the bnet subroutines for efficiency reasons. +appropriate to put locks inside the bnet subroutines for efficiency reasons. \section{bnet\_open} \index{Bnet\_open} -\addcontentsline{toc}{subsection}{bnet\_open} -To establish a connection to a server, use the subroutine: +To establish a connection to a server, use the subroutine: BSOCK *bnet\_open(void *jcr, char *host, char *service, int port, int *fatal) bnet\_open(), if successful, returns the Bacula sock descriptor pointer to be used in subsequent bnet\_send() and bnet\_read() requests. If not successful, bnet\_open() returns a NULL. If fatal is set on return, it means that a fatal error occurred and that you should not repeatedly call bnet\_open(). Any error -message will generally be sent to the JCR. +message will generally be sent to the JCR. \section{bnet\_send} \index{Bnet\_send} -\addcontentsline{toc}{subsection}{bnet\_send} -To send a packet, one uses the subroutine: +To send a packet, one uses the subroutine: int bnet\_send(BSOCK *sock) This routine is equivalent to a write() except that it handles the low level details. The data to be sent is expected to be in sock-\gt{}msg and be sock-\gt{}msglen bytes. To send a packet, bnet\_send() first writes four bytes in network byte order than indicate the size of the -following data packet. It returns: +following data packet. It returns: -\footnotesize \begin{lstlisting} Returns 0 on failure Returns 1 on success \end{lstlisting} -\normalsize In the case of a failure, an error message will be sent to the JCR contained -within the bsock packet. +within the bsock packet. \section{bnet\_fsend} \index{Bnet\_fsend} -\addcontentsline{toc}{subsection}{bnet\_fsend} -This form uses: +This form uses: int bnet\_fsend(BSOCK *sock, char *format, ...) and it allows you to send a formatted messages somewhat like fprintf(). The return status is the same as -bnet\_send. +bnet\_send. \section{Additional Error information} \index{Information!Additional Error} \index{Additional Error information} -\addcontentsline{toc}{subsection}{Additional Error information} -Fro additional error information, you can call {\bf is\_bnet\_error(BSOCK +For additional error information, you can call {\bf is\_bnet\_error(BSOCK *bsock)} which will return 0 if there is no error or non-zero if there is an error on the last transmission. The {\bf is\_bnet\_stop(BSOCK *bsock)} function will return 0 if there no errors and you can continue sending. It will return non-zero if there are errors or the line is closed (no more -transmissions should be sent). +transmissions should be sent). \section{bnet\_recv} \index{Bnet\_recv} -\addcontentsline{toc}{subsection}{bnet\_recv} -To read a packet, one uses the subroutine: +To read a packet, one uses the subroutine: int bnet\_recv(BSOCK *sock) This routine is similar to a read() except that it handles the low level details. bnet\_read() first reads packet length that follows as four bytes in network byte order. The data is read into sock-\gt{}msg and is sock-\gt{}msglen bytes. If the sock-\gt{}msg is not large enough, bnet\_recv() realloc() the buffer. It will return an error (-2) if -maxbytes is less than the record size sent. It returns: +maxbytes is less than the record size sent. It returns: -\footnotesize \begin{lstlisting} * Returns number of bytes read * Returns 0 on end of file * Returns -1 on hard end of file (i.e. network connection close) * Returns -2 on error \end{lstlisting} -\normalsize -It should be noted that bnet\_recv() is a blocking read. +It should be noted that bnet\_recv() is a blocking read. \section{bnet\_sig} \index{Bnet\_sig} -\addcontentsline{toc}{subsection}{bnet\_sig} -To send a ``signal'' from one daemon to another, one uses the subroutine: +To send a ``signal'' from one daemon to another, one uses the subroutine: -int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following: +int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following: \begin{enumerate} -\item BNET\_EOF - deprecated use BNET\_EOD -\item BNET\_EOD - End of data stream, new data may follow -\item BNET\_EOD\_POLL - End of data and poll all in one -\item BNET\_STATUS - Request full status -\item BNET\_TERMINATE - Conversation terminated, doing close() -\item BNET\_POLL - Poll request, I'm hanging on a read -\item BNET\_HEARTBEAT - Heartbeat Response requested -\item BNET\_HB\_RESPONSE - Only response permitted to HB -\item BNET\_PROMPT - Prompt for UA +\item BNET\_EOF - deprecated use BNET\_EOD +\item BNET\_EOD - End of data stream, new data may follow +\item BNET\_EOD\_POLL - End of data and poll all in one +\item BNET\_STATUS - Request full status +\item BNET\_TERMINATE - Conversation terminated, doing close() +\item BNET\_POLL - Poll request, I'm hanging on a read +\item BNET\_HEARTBEAT - Heartbeat Response requested +\item BNET\_HB\_RESPONSE - Only response permitted to HB +\item BNET\_PROMPT - Prompt for UA \end{enumerate} \section{bnet\_strerror} \index{Bnet\_strerror} -\addcontentsline{toc}{subsection}{bnet\_strerror} -Returns a formated string corresponding to the last error that occurred. +Returns a formated string corresponding to the last error that occurred. \section{bnet\_close} \index{Bnet\_close} -\addcontentsline{toc}{subsection}{bnet\_close} -The connection with the server remains open until closed by the subroutine: +The connection with the server remains open until closed by the subroutine: -void bnet\_close(BSOCK *sock) +void bnet\_close(BSOCK *sock) \section{Becoming a Server} \index{Server!Becoming a} \index{Becoming a Server} -\addcontentsline{toc}{subsection}{Becoming a Server} The bnet\_open() and bnet\_close() routines described above are used on the client side to establish a connection and terminate a connection with the server. To become a server (i.e. wait for a connection from a client), use the routine {\bf bnet\_thread\_server}. The calling sequence is a bit complicated, please refer to the code in bnet\_server.c and the code at the beginning of -each daemon as examples of how to call it. +each daemon as examples of how to call it. \section{Higher Level Conventions} \index{Conventions!Higher Level} \index{Higher Level Conventions} -\addcontentsline{toc}{subsection}{Higher Level Conventions} Within Bacula, we have established the convention that any time a single record is passed, it is sent with bnet\_send() and read with bnet\_recv(). -Thus the normal exchange between the server (S) and the client (C) are: +Thus the normal exchange between the server (S) and the client (C) are: -\footnotesize \begin{lstlisting} S: wait for connection C: attempt connection S: accept connection C: bnet_send() send request @@ -188,18 +170,16 @@ S: bnet_recv() wait for request S: act on request S: bnet_send() send ack C: bnet_recv() wait for ack \end{lstlisting} -\normalsize Thus a single command is sent, acted upon by the server, and then -acknowledged. +acknowledged. In certain cases, such as the transfer of the data for a file, all the information or data cannot be sent in a single packet. In this case, the convention is that the client will send a command to the server, who knows that more than one packet will be returned. In this case, the server will -enter a loop: +enter a loop: -\footnotesize \begin{lstlisting} while ((n=bnet_recv(bsock)) > 0) { act on request @@ -207,18 +187,15 @@ while ((n=bnet_recv(bsock)) > 0) { if (n < 0) error \end{lstlisting} -\normalsize -The client will perform the following: +The client will perform the following: -\footnotesize \begin{lstlisting} bnet_send(bsock); bnet_send(bsock); ... bnet_sig(bsock, BNET_EOD); \end{lstlisting} -\normalsize Thus the client will send multiple packets and signal to the server when all -the packets have been sent by sending a zero length record. +the packets have been sent by sending a zero length record. diff --git a/docs/manuals/en/developers/platformsupport.tex b/docs/manuals/en/developers/platformsupport.tex index 0ad65716..43ad23c2 100644 --- a/docs/manuals/en/developers/platformsupport.tex +++ b/docs/manuals/en/developers/platformsupport.tex @@ -5,34 +5,31 @@ \label{_PlatformChapter} \index{Support!Platform} \index{Platform Support} -\addcontentsline{toc}{section}{Platform Support} \section{General} \index{General } -\addcontentsline{toc}{subsection}{General} -This chapter describes the requirements for having a +This chapter describes the requirements for having a supported platform (Operating System). In general, Bacula is quite portable. It supports 32 and 64 bit architectures as well -as bigendian and littleendian machines. For full -support, the platform (Operating System) must implement POSIX Unix +as bigendian and littleendian machines. For full +support, the platform (Operating System) must implement POSIX Unix system calls. However, for File daemon support only, a small -compatibility library can be written to support almost any +compatibility library can be written to support almost any architecture. Currently Linux, FreeBSD, and Solaris are fully supported platforms, which means that the code has been tested on those machines and passes a full set of regression tests. -In addition, the Windows File daemon is supported on most versions -of Windows, and finally, there are a number of other platforms -where the File daemon (client) is known to run: NetBSD, OpenBSD, +In addition, the Windows File daemon is supported on most versions +of Windows, and finally, there are a number of other platforms +where the File daemon (client) is known to run: NetBSD, OpenBSD, Mac OSX, SGI, ... \section{Requirements to become a Supported Platform} \index{Requirements!Platform} \index{Platform Requirements} -\addcontentsline{toc}{subsection}{Platform Requirements} As mentioned above, in order to become a fully supported platform, it must support POSIX Unix system calls. In addition, the following @@ -47,7 +44,7 @@ requirements must be met: a system administrator for the machine that is available. This person need not be a developer/programmer but must be familiar with system administration of the platform. -\item There must be at least one person designated who will +\item There must be at least one person designated who will run regression tests prior to each release. Releases occur approximately once every 6 months, but can be more frequent. It takes at most a day's effort to setup the regression scripts @@ -58,7 +55,7 @@ requirements must be met: \item Ideally there are one or more persons who will package each Bacula release. \item Ideally there are one or more developers who can respond to - and fix platform specific bugs. + and fix platform specific bugs. \end{bsysitemize} Ideal requirements for a test machine: diff --git a/docs/manuals/en/developers/porting.tex b/docs/manuals/en/developers/porting.tex index 8a812465..c8975a4f 100644 --- a/docs/manuals/en/developers/porting.tex +++ b/docs/manuals/en/developers/porting.tex @@ -1,42 +1,40 @@ %% %% -\chapter{Bacula Porting Notes} -\label{_ChapterStart1} +\chapter{Bacula Porting Notes}\label{PortingChapter} +%%%\label{_portingChapter}\label{_ChapterStart1} \index{Notes!Bacula Porting} \index{Bacula Porting Notes} -\addcontentsline{toc}{section}{Bacula Porting Notes} This document is intended mostly for developers who wish to port Bacula to a -system that is not {\bf officially} supported. +system that is not {\bf officially} supported. It is hoped that Bacula clients will eventually run on every imaginable system that needs backing up (perhaps even a Palm). It is also hoped that the Bacula Directory and Storage daemons will run on every system capable of supporting -them. +them. \section{Porting Requirements} \index{Requirements!Porting} \index{Porting Requirements} -\addcontentsline{toc}{section}{Porting Requirements} -In General, the following holds true: +In General, the following holds true: \begin{bsysitemize} \item {\bf Bacula} has been compiled and run on Linux RedHat, FreeBSD, and - Solaris systems. -\item In addition, clients exist on Win32, and Irix -\item It requires GNU C++ to compile. You can try with other compilers, but + Solaris systems. +\item In addition, clients exist on Win32, and Irix +\item It requires GNU C++ to compile. You can try with other compilers, but you are on your own. The Irix client is built with the Irix complier, but, in - general, you will need GNU. -\item Your compiler must provide support for 64 bit signed and unsigned - integers. + general, you will need GNU. +\item Your compiler must provide support for 64 bit signed and unsigned + integers. \item You will need a recent copy of the {\bf autoconf} tools loaded on your system (version 2.13 or later). The {\bf autoconf} tools are used to build the configuration program, but are not part of the Bacula source -distribution. +distribution. \item There are certain third party packages that Bacula needs. Except for - MySQL, they can all be found in the {\bf depkgs} and {\bf depkgs1} releases. + MySQL, they can all be found in the {\bf depkgs} and {\bf depkgs1} releases. \item To build the Win32 binaries, we use Microsoft VC++ standard 2003. Please see the instructions in bacula-source/src/win32/README.win32 for more details. If you @@ -47,23 +45,22 @@ distribution. your own version of the Win32 FD, so you are pretty much on your own. You can ask the bacula-devel list for help, but please don't expect much. -\item {\bf Bacula} requires a good implementation of pthreads to work. +\item {\bf Bacula} requires a good implementation of pthreads to work. \item The source code has been written with portability in mind and is mostly POSIX compatible. Thus porting to any POSIX compatible operating system - should be relatively easy. + should be relatively easy. \end{bsysitemize} \section{Steps to Take for Porting} \index{Porting!Steps to Take for} \index{Steps to Take for Porting} -\addcontentsline{toc}{section}{Steps to Take for Porting} \begin{bsysitemize} \item The first step is to ensure that you have version 2.13 or later of the {\bf autoconf} tools loaded. You can skip this step, but making changes to - the configuration program will be difficult or impossible. + the configuration program will be difficult or impossible. \item The run a {\bf ./configure} command in the main source directory and - examine the output. It should look something like the following: + examine the output. It should look something like the following: \footnotesize \begin{lstlisting} @@ -105,11 +102,11 @@ The details depend on your system. The first thing to check is that it properly identified your host on the {\bf Host:} line. The first part (added in version 1.27) is the GNU four part identification of your system. The part after the -- is your system and the system version. Generally, if your system -is not yet supported, you must correct these. +is not yet supported, you must correct these. \item If the {\bf ./configure} does not function properly, you must determine the cause and fix it. Generally, it will be because some required system - routine is not available on your machine. -\item To correct problems with detection of your system type or with routines + routine is not available on your machine. +\item To correct problems with detection of your system type or with routines and libraries, you must edit the file {\bf \lt{}bacula-src\gt{}/autoconf/configure.in}. This is the ``source'' from which {\bf configure} is built. In general, most of the changes for your @@ -119,46 +116,46 @@ already added the necessary code for most systems, but if yours shows up as {\bf unknown} you will need to make changes. Then as mentioned above, you will need to set a number of system dependent items in {\bf configure.in} in the {\bf case} statement at approximately line 1050 (depending on the Bacula -release). +release). \item The items to in the case statement that corresponds to your system are - the following: + the following: \begin{bsysitemize} \item DISTVER -- set to the version of your operating system. Typically some - form of {\bf uname} obtains it. + form of {\bf uname} obtains it. \item TAPEDRIVE -- the default tape drive. Not too important as the user can - set it as an option. + set it as an option. \item PSCMD -- set to the {\bf ps} command that will provide the PID in the first field and the program name in the second field. If this is not set properly, the {\bf bacula stop} script will most likely not be able to stop -Bacula in all cases. +Bacula in all cases. \item hostname -- command to return the base host name (non-qualified) of your system. This is generally the machine name. Not too important as the - user can correct this in his configuration file. + user can correct this in his configuration file. \item CFLAGS -- set any special compiler flags needed. Many systems need a - special flag to make pthreads work. See cygwin for an example. -\item LDFLAGS -- set any special loader flags. See cygwin for an example. -\item PTHREAD\_LIB -- set for any special pthreads flags needed during - linking. See freebsd as an example. + special flag to make pthreads work. See cygwin for an example. +\item LDFLAGS -- set any special loader flags. See cygwin for an example. +\item PTHREAD\_LIB -- set for any special pthreads flags needed during + linking. See freebsd as an example. \item lld -- set so that a ``long long int'' will be properly edited in a - printf() call. -\item llu -- set so that a ``long long unsigned'' will be properly edited in - a printf() call. -\item PFILES -- set to add any files that you may define is your platform + printf() call. +\item llu -- set so that a ``long long unsigned'' will be properly edited in + a printf() call. +\item PFILES -- set to add any files that you may define is your platform subdirectory. These files are used for installation of automatic system - startup of Bacula daemons. + startup of Bacula daemons. \end{bsysitemize} \item To rebuild a new version of {\bf configure} from a changed {\bf autoconf/configure.in} you enter {\bf make configure} in the top level Bacula source directory. You must have done a ./configure prior to trying to rebuild - the configure script or it will get into an infinite loop. + the configure script or it will get into an infinite loop. \item If the {\bf make configure} gets into an infinite loop, ctl-c it, then do {\bf ./configure} (no options are necessary) and retry the {\bf make - configure}, which should now work. -\item To rebuild {\bf configure} you will need to have {\bf autoconf} version - 2.57-3 or higher loaded. Older versions of autoconf will complain about - unknown or bad options, and won't work. + configure}, which should now work. +\item To rebuild {\bf configure} you will need to have {\bf autoconf} version + 2.57-3 or higher loaded. Older versions of autoconf will complain about + unknown or bad options, and won't work. \item After you have a working {\bf configure} script, you may need to make a few system dependent changes to the way Bacula works. Generally, these are done in {\bf src/baconfig.h}. You can find a few examples of system dependent @@ -166,8 +163,8 @@ changes toward the end of this file. For example, on Irix systems, there is no definition for {\bf socklen\_t}, so it is made in this file. If your system has structure alignment requirements, check the definition of BALIGN in this file. Currently, all Bacula allocated memory is aligned on a {\bf -double} boundary. -\item If you are having problems with Bacula's type definitions, you might - look at {\bf src/bc\_types.h} where all the types such as {\bf uint32\_t}, - {\bf uint64\_t}, etc. that Bacula uses are defined. +double} boundary. +\item If you are having problems with Bacula's type definitions, you might + look at {\bf src/bc\_types.h} where all the types such as {\bf uint32\_t}, + {\bf uint64\_t}, etc. that Bacula uses are defined. \end{bsysitemize} diff --git a/docs/manuals/en/developers/regression.tex b/docs/manuals/en/developers/regression.tex index 63c6e621..bdffc2fc 100644 --- a/docs/manuals/en/developers/regression.tex +++ b/docs/manuals/en/developers/regression.tex @@ -5,15 +5,13 @@ \label{_ChapterStart8} \index{Testing!Bacula Regression} \index{Bacula Regression Testing} -\addcontentsline{toc}{section}{Bacula Regression Testing} \section{Setting up Regession Testing} \index{Setting up Regession Testing} -\addcontentsline{toc}{section}{Setting up Regression Testing} This document is intended mostly for developers who wish to ensure that their changes to Bacula don't introduce bugs in the base code. However, you -don't need to be a developer to run the regression scripts, and we +don't need to be a developer to run the regression scripts, and we recommend them before putting your system into production, and before each upgrade, especially if you build from source code. They are simply shell scripts that drive Bacula through bconsole and then typically @@ -58,8 +56,8 @@ git pull \normalsize If you want to test with SQLite and it is not installed on your system, -you will need to download the latest depkgs release from Source Forge and -unpack it into {\bf depkgs}, then simply: +you will need to download the latest depkgs release from Source Forge and +unpack it into {\bf depkgs}, then simply: \footnotesize \begin{lstlisting} @@ -70,12 +68,11 @@ make There are two different aspects of regression testing that this document will -discuss: 1. Running the Regression Script, 2. Writing a Regression test. +discuss: 1. Running the Regression Script, 2. Writing a Regression test. \section{Running the Regression Script} \index{Running the Regression Script} \index{Script!Running the Regression} -\addcontentsline{toc}{section}{Running the Regression Script} There are a number of different tests that may be run, such as: the standard set that uses disk Volumes and runs under any userid; a small set of tests @@ -88,10 +85,9 @@ drive autochanger based testing can take 3 or 4 hours. \subsection{Setting the Configuration Parameters} \index{Setting the Configuration Parameters} \index{Parameters!Setting the Configuration} -\addcontentsline{toc}{subsection}{Setting the Configuration Parameters} -There is nothing you need to change in the source directory. - +There is nothing you need to change in the source directory. + To begin: \footnotesize @@ -101,9 +97,9 @@ cd bacula/regress \normalsize -The +The very first time you are going to run the regression scripts, you will -need to create a custom config file for your system. +need to create a custom config file for your system. We suggest that you start by: \footnotesize @@ -116,7 +112,7 @@ Then you can edit the {\bf config} file directly. \footnotesize \begin{lstlisting} - + # Where to get the source to be tested BACULA_SOURCE="${HOME}/bacula/bacula" @@ -131,7 +127,7 @@ SQLITE_DIR=${HOME}/depkgs/sqlite TAPE_DRIVE="/dev/nst0" # if you don't have an autochanger set AUTOCHANGER to /dev/null AUTOCHANGER="/dev/sg0" -# For two drive tests -- set to /dev/null if you do not have it +# For two drive tests -- set to /dev/null if you do not have it TAPE_DRIVE1="/dev/null" # This must be the path to the autochanger including its name @@ -153,15 +149,15 @@ TCPWRAPPERS="--with-tcp-wrappers" OPENSSL="--with-openssl" # You may put your real host name here, but localhost or 127.0.0.1 -# is valid also and it has the advantage that it works on a +# is valid also and it has the advantage that it works on a # non-networked machine HOST="localhost" - + \end{lstlisting} \normalsize \begin{bsysitemize} -\item {\bf BACULA\_SOURCE} should be the full path to the Bacula source code +\item {\bf BACULA\_SOURCE} should be the full path to the Bacula source code that you wish to test. It will be loaded configured, compiled, and installed with the "make setup" command, which needs to be done only once each time you change the source code. @@ -176,13 +172,13 @@ HOST="localhost" be build before running a Bacula regression, if you are using SQLite. This variable is ignored if you are using MySQL or PostgreSQL. To use PostgreSQL, edit the Makefile and change (or add) WHICHDB?=``\lstinline+--with-postgresql+''. For - MySQL use ``WHICHDB=''\lstinline+--with-mysql+``. - + MySQL use ``WHICHDB=''\lstinline+--with-mysql+``. + The advantage of using SQLite is that it is totally independent of any installation you may have running on your system, and there is no special configuration or authorization that must be done to run it. With both MySQL and PostgreSQL, you must pre-install the packages, - initialize them and ensure that you have authorization to access the + initialize them and ensure that you have authorization to access the database and create and delete tables. \item {\bf TAPE\_DRIVE} is the full path to your tape drive. The base set of @@ -196,11 +192,11 @@ HOST="localhost" second tape drive. \item {\bf AUTOCHANGER} is the name of your autochanger control device. Set this to - /dev/null if you do not have an autochanger. + /dev/null if you do not have an autochanger. \item {\bf AUTOCHANGER\_PATH} is the full path including the program name for your autochanger program (normally {\bf mtx}. Leave the default value if you - do not have one. + do not have one. \item {\bf TCPWRAPPERS} defines whether or not you want the ./configure to be performed with tcpwrappers enabled. @@ -225,7 +221,6 @@ HOST="localhost" \subsection{Building the Test Bacula} \index{Building the Test Bacula} \index{Bacula!Building the Test} -\addcontentsline{toc}{subsection}{Building the Test Bacula} Once the above variables are set, you can build the setup by entering: @@ -242,8 +237,7 @@ configuration parameters. \subsection{Setting up your SQL engine} \index{Setting up your SQL engine} -\addcontentsline{toc}{subsection}{Setting up your SQL engine} -If you are using SQLite or SQLite3, there is nothing more to do; you can +If you are using SQLite or SQLite3, there is nothing more to do; you can simply run the tests as described in the next section. If you are using MySQL or PostgreSQL, you will need to establish an @@ -259,7 +253,7 @@ do it, and the scripts in bacula/regress/build/src/cats named create\_mysql\_database, create\_postgresql\_database, grant\_mysql\_privileges, and grant\_postgresql\_privileges may be of a help to you. -Generally, to do the above, you will need to run under root to +Generally, to do the above, you will need to run under root to be able to create databases and modify permissions within MySQL and PostgreSQL. @@ -286,7 +280,6 @@ hostname:port:database:username:password \subsection{Running the Disk Only Regression} \index{Regression!Running the Disk Only} \index{Running the Disk Only Regression} -\addcontentsline{toc}{subsection}{Running the Disk Only Regression} The simplest way to copy the source code, configure it, compile it, link it, and run the tests is to use a helper script: @@ -369,7 +362,7 @@ make full_test \footnotesize \begin{lstlisting} Test results - + ===== Bacula tape test OK ===== ===== Small File Size test OK ===== ===== restore-by-file-tape test OK ===== @@ -382,7 +375,7 @@ Test results Each separate test is self contained in that it initializes to run Bacula from scratch (i.e. newly created database). It will also kill any Bacula session that is currently running. In addition, it uses ports 8101, 8102, and 8103 so -that it does not intefere with a production system. +that it does not intefere with a production system. Alternatively, you can do the ./do\_disk work by hand with: @@ -402,7 +395,7 @@ again. Once Bacula is built, you can run the basic disk only non-root regression test -by entering: +by entering: \footnotesize \begin{lstlisting} @@ -414,7 +407,6 @@ make test \subsection{Other Tests} \index{Other Tests} \index{Tests!Other} -\addcontentsline{toc}{subsection}{Other Tests} There are a number of other tests that can be run as well. All the tests are a simply shell script keep in the regress directory. For example the ''make @@ -427,34 +419,33 @@ are invoked by directly running the script are: \index{all\_non-root-tests} All non-tape tests not requiring root. This is the standard set of tests, that in general, backup some data, then restore it, and finally compares the -restored data with the original data. +restored data with the original data. \item [all-root-tests] \index{all-root-tests} All non-tape tests requiring root permission. These are a relatively small number of tests that require running as root. The amount of data backed up can be quite large. For example, one test backs up /usr, another backs up -/etc. One or more of these tests reports an error -- I'll fix it one day. +/etc. One or more of these tests reports an error -- I'll fix it one day. \item [all-non-root-tape-tests] \index{all-non-root-tape-tests} All tape test not requiring root. There are currently three tests, all run without being root, and backup to a tape. The first two tests use one volume, and the third test requires an autochanger, and uses two volumes. If you -don't have an autochanger, then this script will probably produce an error. +don't have an autochanger, then this script will probably produce an error. \item [all-tape-and-file-tests] \index{all-tape-and-file-tests} All tape and file tests not requiring root. This includes just about -everything, and I don't run it very often. +everything, and I don't run it very often. \end{description} \subsection{If a Test Fails} \index{Fails!If a Test} \index{If a Test Fails} -\addcontentsline{toc}{subsection}{If a Test Fails} -If you one or more tests fail, the line output will be similar to: +If you one or more tests fail, the line output will be similar to: \footnotesize \begin{lstlisting} @@ -506,10 +497,10 @@ $ ./tests/backup-bacula-test ... \end{lstlisting} -All regression scripts must be run by hand or by calling the test scripts. +All regression scripts must be run by hand or by calling the test scripts. These are principally scripts that begin with {\bf all\_...} such as {\bf all\_disk\_tests}, {\bf ./all\_test} ... -None of the +None of the {\bf ./do\_disk}, {\bf ./do\_all}, {\bf ./nightly...} scripts will work. If you want to switch back to running the regression scripts from source, first @@ -518,7 +509,6 @@ rerun the {\bf make setup} step. \section{Running a Single Test} \index{Running a Single Test} -\addcontentsline{toc}{section}{Running a Single Test} If you wish to run a single test, you can simply: @@ -541,20 +531,18 @@ tests/backup-to-null \section{Writing a Regression Test} \index{Test!Writing a Regression} \index{Writing a Regression Test} -\addcontentsline{toc}{section}{Writing a Regression Test} Any developer, who implements a major new feature, should write a regression test that exercises and validates the new feature. Each regression test is a complete test by itself. It terminates any running Bacula, initializes the -database, starts Bacula, then runs the test by using the console program. +database, starts Bacula, then runs the test by using the console program. \subsection{Running the Tests by Hand} \index{Hand!Running the Tests by} \index{Running the Tests by Hand} -\addcontentsline{toc}{subsection}{Running the Tests by Hand} You can run any individual test by hand by cd'ing to the {\bf regress} -directory and entering: +directory and entering: \footnotesize \begin{lstlisting} @@ -565,9 +553,8 @@ tests/ \subsection{Directory Structure} \index{Structure!Directory} \index{Directory Structure} -\addcontentsline{toc}{subsection}{Directory Structure} -The directory structure of the regression tests is: +The directory structure of the regression tests is: \footnotesize \begin{lstlisting} @@ -592,21 +579,19 @@ The directory structure of the regression tests is: \subsection{Adding a New Test} \index{Adding a New Test} \index{Test!Adding a New} -\addcontentsline{toc}{subsection}{Adding a New Test} If you want to write a new regression test, it is best to start with one of -the existing test scripts, and modify it to do the new test. +the existing test scripts, and modify it to do the new test. When adding a new test, be extremely careful about adding anything to any of the daemons' configuration files. The reason is that it may change the prompts that are sent to the console. For example, adding a Pool means that the current scripts, which assume that Bacula automatically selects a Pool, will now be presented with a new prompt, so the test will fail. If you need to -enhance the configuration files, consider making your own versions. +enhance the configuration files, consider making your own versions. \subsection{Running a Test Under The Debugger} \index{Debugger} -\addcontentsline{toc}{subsection}{Running a Test Under The Debugger} You can run a test under the debugger (actually run a Bacula daemon under the debugger) by first setting the environment variable {\bf REGRESS\_WAIT} with commands such as: @@ -627,12 +612,12 @@ different shell window. For example: \begin{lstlisting} cd .../regress/bin -gdb bacula-sd +gdb bacula-sd (possibly set breakpoints, ...) run -s -f \end{lstlisting} -Then enter any character in the window with the above message. +Then enter any character in the window with the above message. An error message will appear saying that the daemon you are debugging is already running, which is the case. You can simply ignore the -error message. +error message. diff --git a/docs/manuals/en/developers/smartall.tex b/docs/manuals/en/developers/smartall.tex index 9e3a4aeb..85abc0cd 100644 --- a/docs/manuals/en/developers/smartall.tex +++ b/docs/manuals/en/developers/smartall.tex @@ -1,14 +1,7 @@ -%% -%% - -%\addcontentsline{lof}{figure}{Smart Memory Allocation with Orphaned Buffer - \chapter{Smart Memory Allocation} \label{_ChapterStart4} \index{Detection!Smart Memory Allocation With Orphaned Buffer } \index{Smart Memory Allocation With Orphaned Buffer Detection } -\addcontentsline{toc}{section}{Smart Memory Allocation With Orphaned Buffer -Detection} \bsysimageH{smartall}{Smart Memory Allocation with Orphaned Buffer Detection}{} Few things are as embarrassing as a program that leaks, yet few errors are so @@ -22,7 +15,7 @@ most easily fixed, rather than as part of a crisis debugging push when the problem is identified much later in the testing cycle (or even worse, when the code is in the hands of a customer). When program testing is complete, simply recompiling with different flags removes SMARTALLOC from your program, -permitting it to run without speed or storage penalties. +permitting it to run without speed or storage penalties. In addition to detecting orphaned buffers, SMARTALLOC also helps to find other common problems in management of dynamic storage including storing before the @@ -37,18 +30,17 @@ consistency of the heap as checked by the malloc\_debug facility available on some systems. SMARTALLOC does not conflict with malloc\_debug and both may be used together, if you wish. SMARTALLOC makes no assumptions regarding the internal structure of the heap and thus should be compatible with any C -language implementation of the standard memory allocation functions. +language implementation of the standard memory allocation functions. \subsection{ Installing SMARTALLOC} \index{SMARTALLOC!Installing } \index{Installing SMARTALLOC } -\addcontentsline{toc}{subsection}{Installing SMARTALLOC} -SMARTALLOC is provided as a Zipped archive, +SMARTALLOC is provided as a Zipped archive, \elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}; see the -download instructions below. +download instructions below. -To install SMARTALLOC in your program, simply add the statement: +To install SMARTALLOC in your program, simply add the statement: to every C program file which calls any of the memory allocation functions ({\tt malloc}, {\tt calloc}, {\tt free}, etc.). SMARTALLOC must be used for @@ -57,14 +49,14 @@ if you have such a thing. Next, define the symbol SMARTALLOC in the compilation before the inclusion of smartall.h. I usually do this by having my Makefile add the ``{\tt -DSMARTALLOC}'' option to the C compiler for non-production builds. You can define the symbol manually, if you prefer, by -adding the statement: +adding the statement: -{\tt \#define SMARTALLOC} +{\tt \#define SMARTALLOC} At the point where your program is all done and ready to relinquish control to -the operating system, add the call: +the operating system, add the call: -{\tt \ \ \ \ \ \ \ \ sm\_dump(}{\it datadump}{\tt );} +{\tt \ \ \ \ \ \ \ \ sm\_dump(}{\it datadump}{\tt );} where {\it datadump} specifies whether the contents of orphaned buffers are to be dumped in addition printing to their size and place of allocation. The data @@ -73,7 +65,7 @@ use ``{\tt sm\_dump(0);}''. If a mysterious orphaned buffer appears that can't be identified from the information this prints about it, replace the statement with ``{\tt sm\_dump(1)};''. Usually the dump of the buffer's data will furnish the additional clues you need to excavate and extirpate the elusive -error that left the buffer allocated. +error that left the buffer allocated. Finally, add the files ``smartall.h'' and ``smartall.c'' from this release to your source directory, make dependencies, and linker input. You needn't make @@ -81,9 +73,8 @@ inclusion of smartall.c in your link optional; if compiled with SMARTALLOC not defined it generates no code, so you may always include it knowing it will waste no storage in production builds. Now when you run your program, if it leaves any buffers around when it's done, each will be reported by {\tt -sm\_dump()} on stderr as follows: +sm\_dump()} on stderr as follows: -\footnotesize \begin{lstlisting} Orphaned buffer: 120 bytes allocated at line 50 of gutshot.c \end{lstlisting} @@ -92,7 +83,6 @@ Orphaned buffer: 120 bytes allocated at line 50 of gutshot.c \subsection{ Squelching a SMARTALLOC} \index{SMARTALLOC!Squelching a } \index{Squelching a SMARTALLOC } -\addcontentsline{toc}{subsection}{Squelching a SMARTALLOC} Usually, when you first install SMARTALLOC in an existing program you'll find it nattering about lots of orphaned buffers. Some of these turn out to be @@ -102,13 +92,12 @@ not intended to be released. Of course, you can get rid of the complaints about these buffers by adding code to release them, but by doing so you're adding unnecessary complexity and code size to your program just to silence the nattering of a SMARTALLOC, so an escape hatch is provided to eliminate the -need to release these buffers. +need to release these buffers. Normally all storage allocated with the functions {\tt malloc()}, {\tt calloc()}, and {\tt realloc()} is monitored by SMARTALLOC. If you make the -function call: +function call: -\footnotesize \begin{lstlisting} sm_static(1); \end{lstlisting} @@ -119,9 +108,8 @@ calloc()}, and {\tt realloc()} should not be considered orphaned if found to be allocated when {\tt sm\_dump()} is called. I use a call on ``{\tt sm\_static(1);}'' before I allocate things like program configuration tables so I don't have to add code to release them at end of program time. After -allocating unmonitored data this way, be sure to add a call to: +allocating unmonitored data this way, be sure to add a call to: -\footnotesize \begin{lstlisting} sm_static(0); \end{lstlisting} @@ -130,12 +118,11 @@ allocating unmonitored data this way, be sure to add a call to: to resume normal monitoring of buffer allocations. Buffers allocated while {\tt sm\_static(1}) is in effect are not checked for having been orphaned but all the other safeguards provided by SMARTALLOC remain in effect. You may -release such buffers, if you like; but you don't have to. +release such buffers, if you like; but you don't have to. \subsection{ Living with Libraries} \index{Libraries!Living with } \index{Living with Libraries } -\addcontentsline{toc}{subsection}{Living with Libraries} Some library functions for which source code is unavailable may gratuitously allocate and return buffers that contain their results, or require you to pass @@ -144,27 +131,14 @@ library, by far the best approach is to simply install SMARTALLOC in it, particularly since this kind of ill-structured dynamic storage management is the source of so many storage leaks. Without source code, however, there's no option but to provide a way to bypass SMARTALLOC for the buffers the library -allocates and/or releases with the standard system functions. +allocates and/or releases with the standard system functions. For each function {\it xxx} redefined by SMARTALLOC, a corresponding routine named ``{\tt actually}{\it xxx}'' is furnished which provides direct access to -the underlying system function, as follows: +the underlying system function, as follows: \begin{quote} - -\begin{longtable}{ll} -\multicolumn{1}{l }{\bf Standard function } & \multicolumn{1}{l }{\bf Direct -access function } \\ -{{\tt malloc(}{\it size}{\tt )} } & {{\tt actuallymalloc(}{\it size}{\tt )} -} \\ -{{\tt calloc(}{\it nelem}{\tt ,} {\it elsize}{\tt )} } & {{\tt -actuallycalloc(}{\it nelem}, {\it elsize}{\tt )} } \\ -{{\tt realloc(}{\it ptr}{\tt ,} {\it size}{\tt )} } & {{\tt -actuallyrealloc(}{\it ptr}, {\it size}{\tt )} } \\ -{{\tt free(}{\it ptr}{\tt )} } & {{\tt actuallyfree(}{\it ptr}{\tt )} } - -\end{longtable} - +\LTXtable{\linewidth}{table_systemsfunctions} \end{quote} For example, suppose there exists a system library function named ``{\tt @@ -173,9 +147,8 @@ buffer containing it. Since the library routine allocates the image directly with {\tt malloc()}, you can't use SMARTALLOC's {\tt free()}, as that call expects information placed in the buffer by SMARTALLOC's special version of {\tt malloc()}, and hence would report an error. To release the buffer you -should call {\tt actuallyfree()}, as in this code fragment: +should call {\tt actuallyfree()}, as in this code fragment: -\footnotesize \begin{lstlisting} struct image *ibuf = getimage("ratpack.img"); display_on_screen(ibuf); @@ -189,9 +162,8 @@ which writes an image buffer into a file and then releases the buffer with buffer allocated by SMARTALLOC's allocation routines, as it contains special information that the system {\tt free()} doesn't expect to be there. The following code uses {\tt actuallymalloc()} to obtain the buffer passed to such -a routine. +a routine. -\footnotesize \begin{lstlisting} struct image *obuf = (struct image *) actuallymalloc(sizeof(struct image)); @@ -206,19 +178,17 @@ but they're there for the rare occasions that demand them. Don't use them to subvert the error checking of SMARTALLOC; if you want to disable orphaned buffer detection, use the {\tt sm\_static(1)} mechanism described above. That way you don't forfeit all the other advantages of SMARTALLOC as you do when -using {\tt actuallymalloc()} and {\tt actuallyfree()}. +using {\tt actuallymalloc()} and {\tt actuallyfree()}. \subsection{ SMARTALLOC Details} \index{SMARTALLOC Details } \index{Details!SMARTALLOC } -\addcontentsline{toc}{subsection}{SMARTALLOC Details} When you include ``smartall.h'' and define SMARTALLOC, the following standard system library functions are redefined with the \#define mechanism to call corresponding functions within smartall.c instead. (For details of the -redefinitions, please refer to smartall.h.) +redefinitions, please refer to smartall.h.) -\footnotesize \begin{lstlisting} void *malloc(size_t size) void *calloc(size_t nelem, size_t elsize) @@ -228,7 +198,7 @@ redefinitions, please refer to smartall.h.) \end{lstlisting} \normalsize -{\tt cfree()} is a historical artifact identical to {\tt free()}. +{\tt cfree()} is a historical artifact identical to {\tt free()}. In addition to allocating storage in the same way as the standard library functions, the SMARTALLOC versions expand the buffers they allocate to include @@ -238,7 +208,7 @@ allocated buffer chain. A call on {\tt sm\_dump()} is able, by scanning the chain of allocated buffers, to find all orphaned buffers. Buffers allocated while {\tt sm\_static(1)} is in effect are specially flagged so that, despite appearing on the allocated buffer chain, {\tt sm\_dump()} will not deem them -orphans. +orphans. When a buffer is allocated by {\tt malloc()} or expanded with {\tt realloc()}, all bytes of newly allocated storage are set to the hexadecimal value 0x55 @@ -248,7 +218,7 @@ buffer are not modified. Initializing allocated storage to a distinctive nonzero pattern is intended to catch code that erroneously assumes newly allocated buffers are cleared to zero; in fact their contents are random. The {\tt calloc()} function, defined as returning a buffer cleared to zero, -continues to zero its buffers under SMARTALLOC. +continues to zero its buffers under SMARTALLOC. Buffers obtained with the SMARTALLOC functions contain a special sentinel byte at the end of the user data area. This byte is set to a special key value @@ -257,7 +227,7 @@ is tested and if it has been overwritten an assertion in the {\tt free} function will fail. This catches incorrect program code that stores beyond the storage allocated for the buffer. At {\tt free()} time the queue links are also validated and an assertion failure will occur if the program has -destroyed them by storing before the start of the allocated storage. +destroyed them by storing before the start of the allocated storage. In addition, when a buffer is released with {\tt free()}, its contents are immediately destroyed by overwriting them with the hexadecimal pattern 0xAA @@ -267,11 +237,11 @@ and later attempts to reference data within the released buffer. Incredibly, this is {\it legal} in the standard Unix memory allocation package, which permits programs to free() buffers, then raise them from the grave with {\tt realloc()}. Such program ``logic'' should be fixed, not accommodated, and -SMARTALLOC brooks no such Lazarus buffer`` nonsense. +SMARTALLOC brooks no such Lazarus buffer`` nonsense. Some C libraries allow a zero size argument in calls to {\tt malloc()}. Since this is far more likely to indicate a program error than a defensible -programming stratagem, SMARTALLOC disallows it with an assertion. +programming stratagem, SMARTALLOC disallows it with an assertion. When the standard library {\tt realloc()} function is called to expand a buffer, it attempts to expand the buffer in place if possible, moving it only @@ -288,12 +258,11 @@ actuallyrealloc()}, and {\tt actuallyfree()} for such frequently-adjusted buffers, trading error detection for performance. Although not specified in the System V Interface Definition, many C library implementations of {\tt realloc()} permit an old buffer argument of NULL, causing {\tt realloc()} to -allocate a new buffer. The SMARTALLOC version permits this. +allocate a new buffer. The SMARTALLOC version permits this. \subsection{ When SMARTALLOC is Disabled} \index{When SMARTALLOC is Disabled } \index{Disabled!When SMARTALLOC is } -\addcontentsline{toc}{subsection}{When SMARTALLOC is Disabled} When SMARTALLOC is disabled by compiling a program with the symbol SMARTALLOC not defined, calls on the functions otherwise redefined by SMARTALLOC go @@ -304,22 +273,21 @@ compiles into ''{\tt malloc(100)}``. The two special SMARTALLOC functions, {\tt sm\_dump()} and {\tt sm\_static()}, are defined to generate no code (hence the null statement). Finally, if SMARTALLOC is not defined, compilation of the file smartall.c generates no code or data at all, effectively removing -it from the program even if named in the link instructions. +it from the program even if named in the link instructions. Thus, except for unusual circumstances, a program that works with SMARTALLOC defined for testing should require no changes when built without it for -production release. +production release. \subsection{ The {\tt alloc()} Function} \index{Function!alloc } \index{Alloc() Function } -\addcontentsline{toc}{subsection}{alloc() Function} Many programs I've worked on use very few direct calls to {\tt malloc()}, using the identically declared {\tt alloc()} function instead. Alloc detects out-of-memory conditions and aborts, removing the need for error checking on every call of {\tt malloc()} (and the temptation to skip checking for -out-of-memory). +out-of-memory). As a convenience, SMARTALLOC supplies a compatible version of {\tt alloc()} in the file alloc.c, with its definition in the file alloc.h. This version of @@ -327,12 +295,11 @@ the file alloc.c, with its definition in the file alloc.h. This version of SMARTALLOC's orphaned buffer detection. In addition, when SMARTALLOC is defined and {\tt alloc()} detects an out of memory condition, it takes advantage of the SMARTALLOC diagnostic information to identify the file and -line number of the call on {\tt alloc()} that failed. +line number of the call on {\tt alloc()} that failed. \subsection{ Overlays and Underhandedness} \index{Underhandedness!Overlays and } \index{Overlays and Underhandedness } -\addcontentsline{toc}{subsection}{Overlays and Underhandedness} String constants in the C language are considered to be static arrays of characters accessed through a pointer constant. The arrays are potentially @@ -344,7 +311,7 @@ compiled-in text of the file name. This works fine as long as the program does not overlay its data among modules. If data are overlayed, the area of memory which contained the file name at the time it was saved in the buffer may contain something else entirely when {\tt sm\_dump()} gets around to using the -pointer to edit the file name which allocated the buffer. +pointer to edit the file name which allocated the buffer. If you want to use SMARTALLOC in a program with overlayed data, you'll have to modify smartall.c to either copy the file name to a fixed-length field added @@ -357,7 +324,7 @@ environments, the restrictions on SMARTALLOC with data overlaying may never prove a problem. Note that conventional overlaying of code, by far the most common form of overlaying, poses no problems for SMARTALLOC; you need only be concerned if you're using exotic tools for data overlaying on MS-DOS or other -address-space-challenged systems. +address-space-challenged systems. Since a C language ''constant`` string can actually be written into, most C compilers generate a unique copy of each string used in a module, even if the @@ -367,23 +334,21 @@ strings that identify the file name. If your compiler permits optimization of multiple occurrences of constant strings, enabling this mode will eliminate the overhead for these strings. Of course, it's up to you to make sure choosing this compiler mode won't wreak havoc on some other part of your -program. +program. \subsection{ Test and Demonstration Program} \index{Test and Demonstration Program } \index{Program!Test and Demonstration } -\addcontentsline{toc}{subsection}{Test and Demonstration Program} A test and demonstration program, smtest.c, is supplied with SMARTALLOC. You can build this program with the Makefile included. Please refer to the comments in smtest.c and the Makefile for information on this program. If you're attempting to use SMARTALLOC on a new machine or with a new compiler or -operating system, it's a wise first step to check it out with smtest first. +operating system, it's a wise first step to check it out with smtest first. \subsection{ Invitation to the Hack} \index{Hack!Invitation to the } \index{Invitation to the Hack } -\addcontentsline{toc}{subsection}{Invitation to the Hack} SMARTALLOC is not intended to be a panacea for storage management problems, nor is it universally applicable or effective; it's another weapon in the @@ -392,7 +357,7 @@ products. It represents the current state of evolution of expedient debug code which has been used in several commercial software products which have, collectively, sold more than third of a million copies in the retail market, and can be expected to continue to develop through time as it is applied to -ever more demanding projects. +ever more demanding projects. The version of SMARTALLOC here has been tested on a Sun SPARCStation, Silicon Graphics Indigo2, and on MS-DOS using both Borland and Microsoft C. Moving @@ -400,32 +365,30 @@ from compiler to compiler requires the usual small changes to resolve disputes about prototyping of functions, whether the type returned by buffer allocation is {\tt char\ *} or {\tt void\ *}, and so forth, but following those changes it works in a variety of environments. I hope you'll find SMARTALLOC as useful -for your projects as I've found it in mine. +for your projects as I've found it in mine. \section{ -\elink{}{http://www.fourmilab.ch/smartall/smartall.zip} +\elink{}{http://www.fourmilab.ch/smartall/smartall.zip} \elink{Download smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip} (Zipped archive)} \index{Archive! Download smartall.zip Zipped } \index{ Download smartall.zip (Zipped archive) } -\addcontentsline{toc}{section}{ Download smartall.zip (Zipped archive)} -SMARTALLOC is provided as -\elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}, a +SMARTALLOC is provided as +\elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}, a \elink{Zipped}{http://www.pkware.com/} archive containing source code, -documentation, and a {\tt Makefile} to build the software under Unix. +documentation, and a {\tt Makefile} to build the software under Unix. \subsection{ Copying} \index{Copying } -\addcontentsline{toc}{subsection}{Copying} \begin{quote} SMARTALLOC is in the public domain. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. This software is -provided ''as is`` without express or implied warranty. +provided ''as is`` without express or implied warranty. \end{quote} -{\it +{\it \elink{by John Walker}{http://www.fourmilab.ch} -October 30th, 1998 } +October 30th, 1998 } diff --git a/docs/manuals/en/developers/storage.tex b/docs/manuals/en/developers/storage.tex index 046efd20..94fb7e1d 100644 --- a/docs/manuals/en/developers/storage.tex +++ b/docs/manuals/en/developers/storage.tex @@ -5,7 +5,6 @@ \label{_ChapterStart3} \index{Storage Daemon Design } \index{Design!Storage Daemon } -\addcontentsline{toc}{section}{Storage Daemon Design} This chapter is intended to be a technical discussion of the Storage daemon services and as such is not targeted at end users but rather at developers and @@ -17,7 +16,6 @@ This document is somewhat out of date. \section{SD Design Introduction} \index{Introduction!SD Design } \index{SD Design Introduction } -\addcontentsline{toc}{section}{SD Design Introduction} The Bacula Storage daemon provides storage resources to a Bacula installation. An individual Storage daemon is associated with a physical permanent storage @@ -36,7 +34,6 @@ available backup repositories. \section{SD Development Outline} \index{Outline!SD Development } \index{SD Development Outline } -\addcontentsline{toc}{section}{SD Development Outline} In order to provide a high performance backup and restore solution that scales to very large capacity devices and networks, the storage daemon must be able @@ -58,7 +55,6 @@ to high-speed intermediate media, and support for tape changers and jukeboxes. \section{SD Connections and Sessions} \index{Sessions!SD Connections and } \index{SD Connections and Sessions } -\addcontentsline{toc}{section}{SD Connections and Sessions} A client connects to a storage server by initiating a conventional TCP connection. The storage server accepts the connection unless its maximum @@ -86,7 +82,6 @@ produce them in an update to this document. \subsection{SD Append Requests} \index{Requests!SD Append } \index{SD Append Requests } -\addcontentsline{toc}{subsection}{SD Append Requests} \begin{description} @@ -158,7 +153,6 @@ stored on that volume. \subsection{SD Read Requests} \index{SD Read Requests } \index{Requests!SD Read } -\addcontentsline{toc}{subsection}{SD Read Requests} \begin{description} @@ -205,12 +199,10 @@ at any time; you needn't read all its blocks before closing it. \end{description} {\it by -\elink{John Walker}{http://www.fourmilab.ch/} -January 30th, MM } +\elink{John Walker}{http://www.fourmilab.ch/}January 30th, MM } \section{SD Data Structures} \index{SD Data Structures} -\addcontentsline{toc}{section}{SD Data Structures} In the Storage daemon, there is a Device resource (i.e. from conf file) that describes each physical device. When the physical device is used it @@ -220,7 +212,7 @@ device must ultimately get a lock on the DEVICE structure -- this controls the device. However, multiple Jobs (defined by a JCR structure src/jcr.h) can be writing a physical DEVICE at the same time (of course they are sequenced by locking the DEVICE structure). There are a lot of job -dependent "device" variables that may be different for each Job such as +dependent ``device'' variables that may be different for each Job such as spooling (one job may spool and another may not, and when a job is spooling, it must have an i/o packet open, each job has its own record and block structures, ...), so there is a device control record or DCR that is diff --git a/docs/manuals/en/developers/tls-techdoc.tex b/docs/manuals/en/developers/tls-techdoc.tex index 8f36a154..a7d6a06e 100644 --- a/docs/manuals/en/developers/tls-techdoc.tex +++ b/docs/manuals/en/developers/tls-techdoc.tex @@ -13,7 +13,6 @@ Written by Landon Fuller \section{Introduction to TLS} \index{TLS Introduction} \index{Introduction!TLS} -\addcontentsline{toc}{section}{TLS Introduction} This patch includes all the back-end code necessary to add complete TLS data encryption support to Bacula. In addition, support for TLS in @@ -21,11 +20,11 @@ Console/Director communications has been added as a proof of concept. Adding support for the remaining daemons will be straight-forward. Supported features of this patchset include: -\begin{bsysitemize} -\item Client/Server TLS Requirement Negotiation +\begin{bsysitemize} +\item Client/Server TLS Requirement Negotiation \item TLSv1 Connections with Server and Client Certificate -Validation -\item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying +Validation +\item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying \end{bsysitemize} This document will refer to both ``server'' and ``client'' contexts. These @@ -47,7 +46,6 @@ implementations. \section{New Configuration Directives} \index{TLS Configuration Directives} \index{Directives!TLS Configuration} -\addcontentsline{toc}{section}{New Configuration Directives} Additional configuration directives have been added to both the Console and Director resources. These new directives are defined as follows: @@ -99,8 +97,8 @@ specified, DH ephemeral keying will be enabled, allowing for forward secrecy of communications. This directive is only valid within a server context. To generate the parameter file, you may use openssl: \footnotesize -\begin{lstlisting} -openssl dhparam -out dh1024.pem -5 1024 +\begin{lstlisting} +openssl dhparam -out dh1024.pem -5 1024 \end{lstlisting} \normalsize \end{bsysitemize} @@ -108,7 +106,6 @@ openssl dhparam -out dh1024.pem -5 1024 \section{TLS API Implementation} \index{TLS API Implimentation} \index{API Implimentation!TLS} -\addcontentsline{toc}{section}{TLS API Implementation} To facilitate the use of additional TLS libraries, all OpenSSL-specific code has been implemented within \emph{src/lib/tls.c}. In turn, a generic @@ -117,7 +114,6 @@ TLS API is exported. \subsection{Library Initialization and Cleanup} \index{Library Initialization and Cleanup} \index{Initialization and Cleanup!Library} -\addcontentsline{toc}{subsection}{Library Initialization and Cleanup} \footnotesize \begin{lstlisting} @@ -139,7 +135,6 @@ Performs TLS library cleanup. \subsection{Manipulating TLS Contexts} \index{TLS Context Manipulation} \index{Contexts!Manipulating TLS} -\addcontentsline{toc}{subsection}{Manipulating TLS Contexts} \footnotesize \begin{lstlisting} @@ -171,7 +166,6 @@ Deallocated a previously allocated \emph{TLS\_CONTEXT} structure. \subsection{Performing Post-Connection Verification} \index{TLS Post-Connection Verification} \index{Verification!TLS Post-Connection} -\addcontentsline{toc}{subsection}{Performing Post-Connection Verification} \footnotesize \begin{lstlisting} @@ -198,7 +192,6 @@ strings supplied via the \emph{verify\_list} parameter. Returns \subsection{Manipulating TLS Connections} \index{TLS Connection Manipulation} \index{Connections!Manipulating TLS} -\addcontentsline{toc}{subsection}{Manipulating TLS Connections} \footnotesize \begin{lstlisting} @@ -274,7 +267,6 @@ The actual number of bytes read will be returned. \section{Bnet API Changes} \index{Bnet API Changes} \index{API Changes!Bnet} -\addcontentsline{toc}{section}{Bnet API Changes} A minimal number of changes were required in the Bnet socket API. The BSOCK structure was expanded to include an associated TLS\_CONNECTION structure, @@ -285,7 +277,6 @@ possible to discern the current blocking state of a socket. \subsection{Negotiating a TLS Connection} \index{Negotiating a TLS Connection} \index{TLS Connection!Negotiating} -\addcontentsline{toc}{subsection}{Negotiating a TLS Connection} \emph{bnet\_tls\_server()} and \emph{bnet\_tls\_client()} were both implemented using the new TLS API as follows: @@ -313,7 +304,6 @@ Accepts a TLS client session via \emph{bsock} using the settings from \index{Manipulating Socket Blocking State} \index{Socket Blocking State!Manipulating} \index{Blocking State!Socket!Manipulating} -\addcontentsline{toc}{subsection}{Manipulating Socket Blocking State} Three functions were added for manipulating the blocking state of a socket on both Win32 and Unix-like systems. The Win32 code was written according @@ -354,7 +344,6 @@ Restores blocking or non-blocking IO setting on the socket associated with \section{Authentication Negotiation} \index{Authentication Negotiation} \index{Negotiation!TLS Authentication} -\addcontentsline{toc}{section}{Authentication Negotiation} Backwards compatibility with the existing SSL negotiation hooks implemented in src/lib/cram-md5.c have been maintained. The diff --git a/docs/manuals/en/main/configure.tex b/docs/manuals/en/main/configure.tex index d1cdf6e2..5c25ddf2 100644 --- a/docs/manuals/en/main/configure.tex +++ b/docs/manuals/en/main/configure.tex @@ -26,8 +26,6 @@ files for each daemon. Default configuration files will have been created by the installation process, but you will need to modify them to correspond to your system. An overall view of the resources can be seen in the following: -%% \addcontentsline{lof}{figure}{Bacula Objects} -%% \includegraphics{\idir bacula-objects} \bsysimageH{bacula-objects}{Bacula Objects}{figconfig:baculaobjects} \label{ResFormat} @@ -312,7 +310,6 @@ resources must be defined for each service (daemon). The default configuration files will already contain at least one example of each permitted resource, so you need not worry about creating all these kinds of resources from scratch. -%\addcontentsline{lot}{table}{Resource Types} \LTXtable{0.95\linewidth}{table_resources} \section{Names, Passwords and Authorization} \label{Names} @@ -333,7 +330,6 @@ will need to take care to keep them consistent. Here is sort of a picture of what names/passwords in which files/Resources must match up: -%\includegraphics{\idir Conf-Diagram} \bsysimageH{Conf-Diagram}{Configuration diagram}{figconfig:configdiagram} In the left column, you will find the Director, Storage, and Client resources, diff --git a/docs/manuals/en/main/dirdconf.tex b/docs/manuals/en/main/dirdconf.tex index 5000915f..db35de29 100644 --- a/docs/manuals/en/main/dirdconf.tex +++ b/docs/manuals/en/main/dirdconf.tex @@ -1064,12 +1064,6 @@ during working hours. We can see it like \texttt{Max Start Delay + Max Run scheduled). This directive works as expected since bacula 2.3.18. \bsysimageH{different_time}{Job time control directives}{fig:differenttime} -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=13cm]{\idir different_time} -%% \label{fig:differenttime} -%% \caption{Job time control directives} -%% \end{figure} \label{Director:Job:MaximumBandwidth} \item [Maximum Bandwidth = \lt{}speed\gt{}] @@ -1792,12 +1786,6 @@ RunScript { \item [Allow Duplicate Jobs = \lt{}yes\vb{}no\gt{}] \index[general]{Allow Duplicate Jobs} -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=13cm]{\idir duplicate-real} -% \label{fig:allowduplicatejobs} -% \caption{Allow Duplicate Jobs usage} -%\end{figure} \bsysimageH{duplicate-real}{Allow Duplicate Jobs usage}{fig:allowduplicatejobs} A duplicate job in the sense we use it here means a second or subsequent job @@ -2474,11 +2462,6 @@ k/s, Kb/s, m/s or Mb/s. % Client resolver is not possible. Note that using this directive will not allow % to use multiple Storage Daemon for Backup/Restore jobs. % -% \begin{figure}[htbp] -% \centering -% \includegraphics[width=10cm]{\idir BackupOverWan1} -% \caption{Backup over WAN using FD Storage Address} -% \end{figure} \label{Director:Client:Priority} \item [Priority = \lt{}number\gt{}] @@ -2550,11 +2533,6 @@ the Director. Client resolver is not possible. \bsysimageH{BackupOverWan1}{Backup over WAN using FD Storage Address}{figdirdconf:backupwan} -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=10cm]{\idir BackupOverWan1} -%% \caption{Backup over WAN using FD Storage Address} -%% \end{figure} \label{Director:Storage:SdPort} \item [SD Port = \lt{}port\gt{}] diff --git a/docs/manuals/en/main/general.tex b/docs/manuals/en/main/general.tex index 9b36dddf..227e361e 100644 --- a/docs/manuals/en/main/general.tex +++ b/docs/manuals/en/main/general.tex @@ -57,7 +57,6 @@ available under the GNU Version 2 software license. Director, Console, File, Storage, and Monitor services. -%\addcontentsline{lof}{figure}{Bacula Applications} \bsysimageH{bacula-applications}{Bacula Applications}{figgeneral:bacula-applications} (thanks to Aristedes Maniatis for this graphic and the one below) @@ -180,9 +179,7 @@ In order for Bacula to understand your system, what clients you want backed up and how, you must create a number of configuration files containing resources (or objects). The following presents an overall picture of this: -%\addcontentsline{lof}{figure}{Bacula Objects} \bsysimageH{bacula-objects}{Bacula Objects}{figgeneral:baculaojects} -%\includegraphics{\idir bacula-objects} \section{Conventions Used in this Document} \index[general]{Conventions used in this document} @@ -521,6 +518,4 @@ Services for a backup job. Each block represents in general a separate process (normally a daemon). In general, the Director oversees the flow of information. It also maintains the Catalog. -%\addcontentsline{lof}{figure}{Interactions between Bacula Services} \bsysimageH{flow}{Interactions between Bacula Services}{figgeneral:interactions} -%includegraphics{\idir flow} diff --git a/docs/manuals/en/main/install.tex b/docs/manuals/en/main/install.tex index 89a4c499..a28fb0b8 100644 --- a/docs/manuals/en/main/install.tex +++ b/docs/manuals/en/main/install.tex @@ -276,7 +276,6 @@ needed), you do the following: Although the exact composition of the dependency packages may change from time to time, the current makeup is the following: -%\addcontentsline{lot}{table}{Dependency Packages} \LTXtable{0.95\linewidth}{table_dependencies} Note, some of these packages are quite large, so that building them can be a bit time consuming. The above instructions will build all the packages diff --git a/docs/manuals/en/main/main.tex b/docs/manuals/en/main/main.tex index 27df18cb..3bc665fa 100644 --- a/docs/manuals/en/main/main.tex +++ b/docs/manuals/en/main/main.tex @@ -140,7 +140,7 @@ lscape,pdfpages,ifthen,setspace,colortbl,diagbox} % pull in the index %\clearpage %\backmatter -\part*{Indexes} +%\part*{Indexes} \printindex[general] \printindex[dir] \printindex[fd] diff --git a/docs/manuals/en/main/newbs4.0features.tex b/docs/manuals/en/main/newbs4.0features.tex index 88a780ef..4d29d7ec 100644 --- a/docs/manuals/en/main/newbs4.0features.tex +++ b/docs/manuals/en/main/newbs4.0features.tex @@ -697,12 +697,7 @@ Those new features were funded by Bacula Systems. By clicking on ``Media'', you can see the list of all your volumes. You will be able to filter by Pool, Media Type, Location,\dots And sort the result directly in the table. The old ``Media'' view is now known as ``Pool''. -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=13cm]{\idir \bsysimageH{bat-mediaview}{List volumes with BAT}{figbs4:mediaview} -% \label{fig:mediaview} -%\end{figure} \subsubsection{Media Information View} @@ -710,38 +705,24 @@ in the table. The old ``Media'' view is now known as ``Pool''. By double-clicking on a volume (on the Media list, in the Autochanger content or in the Job information panel), you can access a detailed overview of your Volume. (cf. figure \bsysref{figbs4:mediainfo}.) -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=13cm]{\idir + \bsysimageH{bat11}{Media information}{figbs4:mediainfo} -% \caption{Media information} -% \label{fig:mediainfo} -%\end{figure} + \subsubsection{Job Information View} By double-clicking on a Job record (on the Job run list or in the Media information panel), you can access a detailed overview of your Job. (cf. figure \bsysref{figbs4:jobinfo}.) -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=13cm]{\idir + \bsysimageH{bat12}{Job information}{figbs4:jobinfo} -% \caption{Job information} -% \label{fig:jobinfo} -%\end{figure} \subsubsection{Autochanger Content View} By double-clicking on a Storage record (on the Storage list panel), you can access a detailed overview of your Autochanger. (cf. figure \bsysref{figbs4:jobinfo}.) -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=13cm]{\idir + \bsysimageH{bat13}{Autochanger content}{figbs4:achcontent} -% \caption{Autochanger content} -% \label{fig:achcontent} -%\end{figure} To use this feature, you need to use the latest mtx-changer script version. (With new \texttt{listall} and \texttt{transfer} commands) @@ -2565,9 +2546,7 @@ These directives have been deprecated in favor of Using \textbf{Full/Diff/Incr Max Run Time}, it's now possible to specify the maximum allowed time that a job can run depending on the level. -%\addcontentsline{lof}{figure}{Job time control directives} -\bsysimageH{different_time}{Job time control directives}{} -%\includegraphics{\idir different_time} +\bsysimageH{different_time}{Job time control directives}{figbs4:jobtimecontroldirectives} \subsubsection{Statistics Enhancements} \index[general]{Statistics enhancements} diff --git a/docs/manuals/en/main/newbsfeatures.tex b/docs/manuals/en/main/newbsfeatures.tex index 0594236c..d5fcb88c 100644 --- a/docs/manuals/en/main/newbsfeatures.tex +++ b/docs/manuals/en/main/newbsfeatures.tex @@ -558,21 +558,10 @@ for both Linux and Windows. In addition to all the previous features, this new version allows you to run Backups from the tray monitor menu. -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=10cm]{\idir \bsysimageH{tray-monitor}{New tray monitor}{figbs6:traymonitor} -% \label{fig:traymonitor} -% \caption{New tray monitor} -%\end{figure} -%\begin{figure}[htbp] -% \centering \bsysimageH{tray-monitor1}{Run a Job through the new tray monitor}{figbs6:traymonitor1} -% \includegraphics[width=10cm]{\idir tray-monitor1} -% \label{fig:traymonitor1} -% \caption{Run a Job through the new tray monitor} -%\end{figure} + To be able to run a job from the tray monitor, you need to diff --git a/docs/manuals/en/main/newfeatures.tex b/docs/manuals/en/main/newfeatures.tex index b529594e..8a321f12 100644 --- a/docs/manuals/en/main/newfeatures.tex +++ b/docs/manuals/en/main/newfeatures.tex @@ -64,20 +64,8 @@ for both Linux and Windows. In addition to all the previous features, this new version allows you to run Backups from the tray monitor menu. -%\begin{figure}[htbp] -% \centering -% \includegraphics[width=10cm]{\idir tray-monitor} \bsysimageH{tray-monitor}{New tray monitor}{figcom:traymonitor} -% \label{figcom:traymonitor} -% \caption{New tray monitor} -%\end{figure} - -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=10cm]{\idir tray-monitor1} -%% \label{figcom:traymonitor1} -%% \caption{Run a Job through the new tray monitor} -%% \end{figure} + \bsysimageH{tray-monitor1}{Run a Job through the new tray monitor}{figcom:traymonitor1} To be able to run a job from the tray monitor, you need to @@ -137,12 +125,6 @@ by Bacula Systems. Bat has now a bRestore panel that uses Bvfs to display files and directories. -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=12cm]{\idir -%% \label{figcom:batbrestore} -%% \caption{Bat Brestore Panel} -%% \end{figure} \bsysimageH{bat-brestore}{Bat Brestore Panel}{figcom:batbrestore} the Bvfs module works correctly with BaseJobs, Copy and Migration jobs. @@ -1107,11 +1089,7 @@ Those new features were funded by Bacula Systems. By clicking on ``Media'', you can see the list of all your volumes. You will be able to filter by Pool, Media Type, Location,\dots And sort the result directly in the table. The old ``Media'' view is now known as ``Pool''. -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=13cm]{\idir bat-mediaview} -%% \label{figcom:mediaview} -%% \end{figure} + \bsysimageH{bat-mediaview}{List of all Volumes}{figcom:mediaview} \subsubsection{Media Information View} @@ -1119,36 +1097,21 @@ in the table. The old ``Media'' view is now known as ``Pool''. By double-clicking on a volume (on the Media list, in the Autochanger content or in the Job information panel), you can access a detailed overview of your Volume. (cf. figure \bsysref{figcom:mediainfo}.) -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=13cm]{\idir bat11} -%% \caption{Media information} -%% \label{figcom:mediainfo} -%% \end{figure} + \bsysimageH{bat11}{Media information}{figcom:mediainfo} \subsubsection{Job Information View} By double-clicking on a Job record (on the Job run list or in the Media information panel), you can access a detailed overview of your Job. (cf \bsysref{figcom:jobinfo}.) -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=13cm]{\idir bat12} -%% \caption{Job information} -%% \label{figcom:jobinfo} -%% \end{figure} + \bsysimageH{bat12}{Job information}{figcom:jobinfo} \subsubsection{Autochanger Content View} By double-clicking on a Storage record (on the Storage list panel), you can access a detailed overview of your Autochanger. (cf. figure \bsysref{figcom:jobinfo}.) -%% \begin{figure}[htbp] -%% \centering -%% \includegraphics[width=13cm]{\idir bat13} -%% \caption{Autochanger content} -%% \label{figcom:achcontent} -%% \end{figure} + \bsysimageH{bat13}{Autochanger content}{figcom:achcontent} To use this feature, you need to use the latest mtx-changer script @@ -2833,8 +2796,6 @@ These directives have been deprecated in favor of Using \textbf{Full/Diff/Incr Max Run Time}, it's now possible to specify the maximum allowed time that a job can run depending on the level. -%\addcontentsline{lof}{figure}{Job time control directives} -%\includegraphics{\idir different_time} \bsysimageH{different_time}{Job time control directives}{figcom:different_time} \subsubsection{Statistics Enhancements} diff --git a/docs/manuals/en/main/quickstart.tex b/docs/manuals/en/main/quickstart.tex index 6f9a20bb..1dcbbc59 100644 --- a/docs/manuals/en/main/quickstart.tex +++ b/docs/manuals/en/main/quickstart.tex @@ -149,8 +149,6 @@ icon is expanded into a full window, the administrator or user can obtain status information about the Director or the backup status on the local workstation or any other Bacula daemon that is configured. -%% \addcontentsline{lof}{figure}{Bacula Tray Monitor} -%% \includegraphics{\idir Bacula-tray-monitor} \bsysimageH{Bacula-tray-monitor}{Bacula Tray Monitor}{figstart:baculatray} % TODO: image may be too wide for 6" wide printed page. diff --git a/docs/manuals/en/main/supportedchangers.tex b/docs/manuals/en/main/supportedchangers.tex index 33be6dd4..fbbc01fe 100644 --- a/docs/manuals/en/main/supportedchangers.tex +++ b/docs/manuals/en/main/supportedchangers.tex @@ -25,7 +25,6 @@ The home page for the {\bf mtx} project can be found at: \elink{http://mtx.opensource-sw.net/}{http://mtx.opensource-sw.net/}. -%\addcontentsline{lot}{table}{Autochangers Known to Work with Bacula} \begin{landscape} \LTXtable{\linewidth}{table_supportedchangers} \end{landscape} diff --git a/docs/manuals/en/main/supporteddrives.tex b/docs/manuals/en/main/supporteddrives.tex index 3e33ed39..9e6fb6a2 100644 --- a/docs/manuals/en/main/supporteddrives.tex +++ b/docs/manuals/en/main/supporteddrives.tex @@ -44,7 +44,6 @@ following drives are known to work with Bacula. A dash in a column means unknown: \LTXtable{0.95\linewidth}{table_tapedrives} -%\addcontentsline{lot}{table}{Supported Tape Drives} There is a list of \ilink{supported autochangers}{Models} in the Supported Autochangers chapter of this document, where you will find other tape drives diff --git a/docs/manuals/en/main/supportedoses.tex b/docs/manuals/en/main/supportedoses.tex index 9696baee..ccb09b74 100644 --- a/docs/manuals/en/main/supportedoses.tex +++ b/docs/manuals/en/main/supportedoses.tex @@ -32,7 +32,7 @@ \item For MacOSX see \elink{http://fink.sourceforge.net/ for obtaining the packages}{http://fink.sourceforge.net/} \end{bsysitemize} -See the \bsysxrlinkdocument{Porting}{_PortingChapter}{developers}{chapter} of the \devman{} for +See the \bsysxrlink{Porting}{PortingChapter}{developers}{chapter} of the \devman{} for information on porting to other systems. If you have a older Red Hat Linux system running the 2.4.x kernel and you have diff --git a/docs/manuals/en/main/win32.tex b/docs/manuals/en/main/win32.tex index 958f07e2..4288bd96 100644 --- a/docs/manuals/en/main/win32.tex +++ b/docs/manuals/en/main/win32.tex @@ -75,14 +75,10 @@ Bacula, so we don't recommend that option. \item Once launched, the installer wizard will ask you if you want to install Bacula. -%\addcontentsline{lof}{figure}{Win32 Client Setup Wizard} -%\includegraphics{\idir win32-welcome} \bsysimageH{win32-welcome}{Win32 Client Setup Wizard}{fig:win32clientsetupwizard} \item Next you will be asked to select the installation type. -%\addcontentsline{lof}{figure}{Win32 Installation Type} -%\includegraphics{\idir win32-installation-type} \bsysimageH{win32-installation-type}{Win32 Installation Type}{fig:win32installationtype} \item If you proceed, you will be asked to select the components to be @@ -91,8 +87,6 @@ Bacula, so we don't recommend that option. location that you choose later. The components dialog looks like the following: -%\addcontentsline{lof}{figure}{Win32 Component Selection Dialog} -%\includegraphics{\idir win32-pkg} \bsysimageH{win32-pkg}{Win32 Component Selection Dialog}{fig:win32componentselectiondialog} \index[general]{Upgrading} @@ -107,21 +101,15 @@ Bacula, so we don't recommend that option. not be displayed. -%\addcontentsline{lof}{figure}{Win32 Configure} -%\includegraphics{\idir win32-config} \bsysimageH{win32-config}{Win32 Configure}{fig:win32configure} \item While the various files are being loaded, you will see the following dialog: -% \addcontentsline{lof}{figure}{Win32 Install Progress} -% \includegraphics{\idir win32-installing} \bsysimageH{win32-installing}{Win32 Install Progress}{fig:win32installing} \item Finally, the finish dialog will appear: -% \addcontentsline{lof}{figure}{Win32 Client Setup Completed} -% \includegraphics{\idir win32-finish} \bsysimageH{win32-finish}{Win32 Client Setup Completed}{fig:win32setupcompleted} \end{bsysitemize} @@ -130,7 +118,7 @@ That should complete the installation process. When the Bacula File Server is ready to serve files, an icon \raisebox{-1ex}{\includegraphics{k7-idle}} representing a cassette (or tape) will appear in the system tray \raisebox{-2ex}{\includegraphics{tray-icon}}; right click on it and a menu will appear.\\ -\bsysimageN{menu}{Menu on right click}{}\\ +\bsysimageN{menu}{Menu on right click}{fig:win32menuonrightclick}\\ The {\bf Events} item is currently unimplemented, by selecting the {\bf Status} item, you can verify whether any jobs are running or not. @@ -389,38 +377,7 @@ Windows specific security and ownership information will be lost. The following matrix will give you an idea of what you can expect. Thanks to Marc Brueckner for doing the tests: -\addcontentsline{lot}{table}{WinNT/2K/XP Restore Portability Status} -\begin{longtable}{|l|l|p{2.8in}|} - \hline -\multicolumn{1}{|c|}{\bf Backup OS} & \multicolumn{1}{c|}{\bf Restore OS} -& \multicolumn{1}{c|}{\bf Results } \\ - \hline {WinMe} & {WinMe} & {Works } \\ - \hline {WinMe} & {WinNT} & {Works (SYSTEM permissions) } \\ - \hline {WinMe} & {WinXP} & {Works (SYSTEM permissions) } \\ - \hline {WinMe} & {Linux} & {Works (SYSTEM permissions) } \\ - \hline {\ } & {\ } & {\ } \\ - \hline {WinXP} & {WinXP} & {Works } \\ - \hline {WinXP} & {WinNT} & {Works (all files OK, but got "The data is invalid" -message) } \\ - \hline {WinXP} & {WinMe} & {Error: Win32 data stream not supported. } \\ - \hline {WinXP} & {WinMe} & {Works if {\bf Portable=yes} specified during backup.} \\ - \hline {WinXP} & {Linux} & {Error: Win32 data stream not supported. } \\ - \hline {WinXP} & {Linux} & {Works if {\bf Portable=yes} specified during backup.}\\ - \hline {\ } & {\ } & {\ } \\ - \hline {WinNT} & {WinNT} & {Works } \\ - \hline {WinNT} & {WinXP} & {Works } \\ - \hline {WinNT} & {WinMe} & {Error: Win32 data stream not supported. } \\ - \hline {WinNT} & {WinMe} & {Works if {\bf Portable=yes} specified during backup.}\\ - \hline {WinNT} & {Linux} & {Error: Win32 data stream not supported. } \\ - \hline {WinNT} & {Linux} & {Works if {\bf Portable=yes} specified during backup. }\\ - \hline {\ } & {\ } & {\ } \\ - \hline {Linux} & {Linux} & {Works } \\ - \hline {Linux} & {WinNT} & {Works (SYSTEM permissions) } \\ - \hline {Linux} & {WinMe} & {Works } \\ - \hline {Linux} & {WinXP} & {Works (SYSTEM permissions)} -\\ \hline -\end{longtable} - +\LTXtable{\linewidth}{table_restoreportabilitystatus} Note: with Bacula versions 1.39.x and later, non-portable Windows data can be restore to any machine. @@ -698,19 +655,16 @@ to allow full access. OK}. \bsysimageH{view-only}{Message to ignore}{fig:messagetoignore} -%\includegraphics{\idir view-only} You should see something like this: \bsysimageH{properties-security}{Properties security}{fig:propertiessecurity} -%\includegraphics{\idir properties-security} \item click on Advanced \item click on the Owner tab \item Change the owner to something other than the current owner (which is {\bf SYSTEM} in this example as shown below). \bsysimageH{properties-security-advanced-owner}{Properties security advanced owner}{fig:propertiessecurityadvancedowner} -%\includegraphics{\idir properties-security-advanced-owner} \item ensure the ``Replace owner on subcontainers and objects'' box is checked \item click on OK @@ -720,7 +674,6 @@ You should see something like this: on Yes. \bsysimageH{confirm}{Confirm granting permissions}{fig:confirmgrantingpermissions} -%\includegraphics{\idir confirm} \item Click on OK to close the Properties tab \end{enumerate} diff --git a/docs/manuals/en/problems/tips.tex b/docs/manuals/en/problems/tips.tex index 2b805ca9..01543573 100644 --- a/docs/manuals/en/problems/tips.tex +++ b/docs/manuals/en/problems/tips.tex @@ -108,7 +108,7 @@ destinations. The form of the mailcommand is a bit complicated, but it allows you to distinguish whether the Job terminated in error or terminated normally. Please see the -\bsysxrlink{Mail}{mailcommand}{utility}{command} in the \utilityman{} for the +\bsysxrlink{Mail}{mailcommand}{main}{command} in the \mainman{} for the details of the substitution characters used above. Once you are totally comfortable with Bacula as I am, or if you have a large diff --git a/docs/manuals/en/utility/progs.tex b/docs/manuals/en/utility/progs.tex index 40e3230b..31d32df8 100644 --- a/docs/manuals/en/utility/progs.tex +++ b/docs/manuals/en/utility/progs.tex @@ -287,7 +287,7 @@ bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=MD5 len=16 p=8101841 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 +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 @@ -1005,9 +1005,8 @@ Where you replace {\bf /home/bacula/bin} with the path to your {\bf Bacula} binary directory, and you replace {\bf mail.domain.com} with the fully qualified name of your bsmtp (email) server, which normally listens on port 25. For more details on the substitution characters (e.g. \%r) used in the -above line, please see the documentation of the -\ilink{ MailCommand in the Messages Resource}{mailcommand} -chapter of this manual. +above line, please see the documentation of the \bsysxrlink{Mail Command in + the Messages Resource}{mailcommand}{main}{chapter} of the \mainman{}. It is HIGHLY recommended that you test one or two cases by hand to make sure that the {\bf mailhost} that you specified is correct and that it will accept -- 2.39.5