From 23f8030c3af3d489750778c22f2063886ff2b4bc Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Sat, 8 Dec 2007 12:47:09 +0000 Subject: [PATCH] Update Developers Guide --- docs/developers/catalog.tex | 23 +++++------ docs/developers/daemonprotocol.tex | 19 ++++----- docs/developers/developers.tex | 1 + docs/developers/director.tex | 2 +- docs/developers/fdl.tex | 2 +- docs/developers/file.tex | 6 +-- docs/developers/generaldevel.tex | 64 ++++++++++++++--------------- docs/developers/md5.tex | 26 ++++++------ docs/developers/mediaformat.tex | 30 +++++++------- docs/developers/mempool.tex | 10 ++--- docs/developers/netprotocol.tex | 26 ++++++------ docs/developers/platformsupport.tex | 6 +-- docs/developers/porting.tex | 10 ++--- docs/developers/smartall.tex | 47 +++++++++++---------- docs/developers/storage.tex | 28 ++++++------- docs/developers/tls-techdoc.tex | 47 +++++++++++---------- 16 files changed, 171 insertions(+), 176 deletions(-) diff --git a/docs/developers/catalog.tex b/docs/developers/catalog.tex index 74599151..f67866b5 100644 --- a/docs/developers/catalog.tex +++ b/docs/developers/catalog.tex @@ -1,13 +1,12 @@ %% %% -\section*{Catalog Services} +\chapter{Catalog Services} \label{_ChapterStart30} \index[general]{Services!Catalog } \index[general]{Catalog Services } -\addcontentsline{toc}{section}{Catalog Services} -\subsection*{General} +\section{General} \index[general]{General } \addcontentsline{toc}{subsection}{General} @@ -47,7 +46,7 @@ internal database. This database is kept for build reasons but is no longer supported. Bacula {\bf requires} one of the three databases (MySQL, PostgreSQL, or SQLite) to run. -\subsubsection*{Filenames and Maximum Filename Length} +\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} @@ -62,7 +61,7 @@ to list online the files saved during any job. All information received and stored by the Storage daemon (normally on tape) allows and handles arbitrarily long path and filenames. -\subsubsection*{Installing and Configuring MySQL} +\subsection{Installing and Configuring MySQL} \index[general]{MySQL!Installing and Configuring } \index[general]{Installing and Configuring MySQL } \addcontentsline{toc}{subsubsection}{Installing and Configuring MySQL} @@ -71,7 +70,7 @@ For the details of installing and configuring MySQL, please see the \ilink{Installing and Configuring MySQL}{_ChapterStart} chapter of this manual. -\subsubsection*{Installing and Configuring PostgreSQL} +\subsection{Installing and Configuring PostgreSQL} \index[general]{PostgreSQL!Installing and Configuring } \index[general]{Installing and Configuring PostgreSQL } \addcontentsline{toc}{subsubsection}{Installing and Configuring PostgreSQL} @@ -80,7 +79,7 @@ For the details of installing and configuring PostgreSQL, please see the \ilink{Installing and Configuring PostgreSQL}{_ChapterStart10} chapter of this manual. -\subsubsection*{Installing and Configuring SQLite} +\subsection{Installing and Configuring SQLite} \index[general]{Installing and Configuring SQLite } \index[general]{SQLite!Installing and Configuring } \addcontentsline{toc}{subsubsection}{Installing and Configuring SQLite} @@ -89,7 +88,7 @@ For the details of installing and configuring SQLite, please see the \ilink{Installing and Configuring SQLite}{_ChapterStart33} chapter of this manual. -\subsubsection*{Internal Bacula Catalog} +\subsection{Internal Bacula Catalog} \index[general]{Catalog!Internal Bacula } \index[general]{Internal Bacula Catalog } \addcontentsline{toc}{subsubsection}{Internal Bacula Catalog} @@ -98,7 +97,7 @@ Please see the \ilink{Internal Bacula Database}{_ChapterStart42} chapter of this manual for more details. -\subsubsection*{Database Table Design} +\subsection{Database Table Design} \index[general]{Design!Database Table } \index[general]{Database Table Design } \addcontentsline{toc}{subsubsection}{Database Table Design} @@ -131,7 +130,7 @@ restoring a file to the wrong machine as well as reducing the amount of data in a single database, thus increasing efficiency and reducing the impact of a lost or damaged database. -\subsection*{Sequence of Creation of Records for a Save Job} +\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 @@ -159,7 +158,7 @@ created, otherwise the existing RecordId should be used. \item Update Job record filling in EndDate and other Job statistics \end{enumerate} -\subsection*{Database Tables} +\section{Database Tables} \index[general]{Database Tables } \index[general]{Tables!Database } \addcontentsline{toc}{subsection}{Database Tables} @@ -761,7 +760,7 @@ This record is not yet implemented. \ -\subsubsection*{MySQL Table Definition} +\subsection{MySQL Table Definition} \index[general]{MySQL Table Definition } \index[general]{Definition!MySQL Table } \addcontentsline{toc}{subsubsection}{MySQL Table Definition} diff --git a/docs/developers/daemonprotocol.tex b/docs/developers/daemonprotocol.tex index 715b8ce8..0354bbd5 100644 --- a/docs/developers/daemonprotocol.tex +++ b/docs/developers/daemonprotocol.tex @@ -1,13 +1,12 @@ %% %% -\section*{Daemon Protocol} +\chapter{Daemon Protocol} \label{_ChapterStart2} \index{Protocol!Daemon } \index{Daemon Protocol } -\addcontentsline{toc}{section}{Daemon Protocol} -\subsection*{General} +\section{General} \index{General } \addcontentsline{toc}{subsection}{General} @@ -21,7 +20,7 @@ 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}. -\subsection*{Low Level Network Protocol} +\section{Low Level Network Protocol} \index{Protocol!Low Level Network } \index{Low Level Network Protocol } \addcontentsline{toc}{subsection}{Low Level Network Protocol} @@ -41,7 +40,7 @@ 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. -\subsection*{General Daemon Protocol} +\section{General Daemon Protocol} \index{General Daemon Protocol } \index{Protocol!General Daemon } \addcontentsline{toc}{subsection}{General Daemon Protocol} @@ -85,7 +84,7 @@ the range 0 to -999 will be standard daemon wide signals, while -1000 to -3000 to -3999 for the Storage daemon. \end{itemize} -\subsection*{The Protocol Used Between the Director and the Storage Daemon} +\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 @@ -121,7 +120,7 @@ For the Director to be authorized, the \lt{}Director-name\gt{} and the Director resources (there may be several Directors that can access a single Storage daemon). -\subsection*{The Protocol Used Between the Director and the File 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 @@ -172,7 +171,7 @@ FD: close socket \end{verbatim} \normalsize -\subsection*{The Save Protocol Between the File Daemon and the Storage Daemon} +\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 @@ -185,7 +184,7 @@ 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. -\subsubsection*{Command and Control Information} +\subsection{Command and Control Information} \index{Information!Command and Control } \index{Command and Control Information } \addcontentsline{toc}{subsubsection}{Command and Control Information} @@ -204,7 +203,7 @@ SD: 3000 OK data address = port = \end{verbatim} \normalsize -\subsubsection*{Data Information} +\subsection{Data Information} \index{Information!Data } \index{Data Information } \addcontentsline{toc}{subsubsection}{Data Information} diff --git a/docs/developers/developers.tex b/docs/developers/developers.tex index 2107344d..840b1a0a 100644 --- a/docs/developers/developers.tex +++ b/docs/developers/developers.tex @@ -27,6 +27,7 @@ \parindent 0pt \title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Developers' Guide} \begin{center} \large{It comes in the night and sucks the essence from your computers. } diff --git a/docs/developers/director.tex b/docs/developers/director.tex index 4cf04e8f..d8c4cd0f 100644 --- a/docs/developers/director.tex +++ b/docs/developers/director.tex @@ -1,7 +1,7 @@ %% %% -\section*{Director Services Daemon} +\chapter{Director Services Daemon} \label{_ChapterStart6} \index{Daemon!Director Services } \index{Director Services Daemon } diff --git a/docs/developers/fdl.tex b/docs/developers/fdl.tex index 6f173a4a..9304bb60 100644 --- a/docs/developers/fdl.tex +++ b/docs/developers/fdl.tex @@ -15,7 +15,7 @@ %--------------------------------------------------------------------- -\section*{GNU Free Documentation License} +\chapter{GNU Free Documentation License} \index[general]{GNU ree Documentation License} \index[general]{License!GNU ree Documentation} \addcontentsline{toc}{section}{GNU ree Documentation License} diff --git a/docs/developers/file.tex b/docs/developers/file.tex index bf56ac60..ee89577b 100644 --- a/docs/developers/file.tex +++ b/docs/developers/file.tex @@ -1,7 +1,7 @@ %% %% -\section*{File Services Daemon} +\chapter{File Services Daemon} \label{_ChapterStart11} \index{File Services Daemon } \index{Daemon!File Services } @@ -51,7 +51,7 @@ 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). -\subsection*{Commands Received from the Director for a Backup} +\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 @@ -59,7 +59,7 @@ Backup} To be written ... -\subsection*{Commands Received from the Director for a Restore} +\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 diff --git a/docs/developers/generaldevel.tex b/docs/developers/generaldevel.tex index 46f4dd5c..9404e57e 100644 --- a/docs/developers/generaldevel.tex +++ b/docs/developers/generaldevel.tex @@ -1,20 +1,20 @@ %% %% -\section*{Bacula Developer Notes} +\chapter{Bacula Developer Notes} \label{_ChapterStart10} \index{Bacula Developer Notes} \index{Notes!Bacula Developer} \addcontentsline{toc}{section}{Bacula Developer Notes} -\subsection*{General} +\section{General} \index{General} \addcontentsline{toc}{subsection}{General} This document is intended mostly for developers and describes the the general framework of making Bacula source changes. -\subsubsection*{Contributions} +\subsection{Contributions} \index{Contributions} \addcontentsline{toc}{subsubsection}{Contributions} @@ -31,7 +31,7 @@ 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. -\subsubsection*{Patches} +\subsection{Patches} \index{Patches} \addcontentsline{toc}{subsubsection}{Patches} @@ -52,7 +52,7 @@ for having developer SVN access so that you can commit your changes directly to the SVN repository. To do so, you will need a userid on Source Forge. -\subsubsection*{Copyrights} +\subsection{Copyrights} \index{Copyrights} \addcontentsline{toc}{subsubsection}{Copyrights} @@ -97,7 +97,7 @@ Items not needing a copyright assignment are: most small changes, enhancements, or bug fixes of 5-10 lines of code, which amount to less than 20% of any particular file. -\subsubsection*{Copyright Assignment -- Fiduciary License Agreement} +\subsection{Copyright Assignment -- Fiduciary License Agreement} \index{Copyright Assignment} \index{Assignment!Copyright} \addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement} @@ -146,7 +146,7 @@ complete document, please notify me: kern at sibbald dot com. -\subsection*{The Development Cycle} +\section{The Development Cycle} \index{Developement Cycle} \index{Cycle!Developement} \addcontentsline{toc}{subsubsection}{Development Cycle} @@ -275,7 +275,7 @@ Item 1: Implement a Migration job type that will move the job \end{verbatim} -\subsection*{Bacula Code Submissions and Projects} +\section{Bacula Code Submissions and Projects} \index{Submissions and Projects} \addcontentsline{toc}{subsection}{Code Submissions and Projects} @@ -318,7 +318,7 @@ Getting code implemented in Bacula works roughly as follows: debugging, documentation, and maintenance responsibilities. \end{itemize} -\subsection*{Patches for Released Versions} +\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 @@ -366,7 +366,7 @@ So, end the end, the patch file is: -\subsection*{SVN Usage} +\section{SVN Usage} \index{SVN Usage} \addcontentsline{toc}{subsection}{SVN Usage} @@ -721,7 +721,7 @@ doing your commits, your commit will effect only that directory. As long as you are careful only to change files that you want changed, you have little to worry about. -\subsection*{Subversion Resources} +\section{Subversion Resources} \index{Subversion (svn) Resources} \addcontentsline{toc}{subsection}{Subversion Resources} @@ -772,7 +772,7 @@ kdesvn -\subsection*{Developing Bacula} +\section{Developing Bacula} \index{Developing Bacula} \index{Bacula!Developing} \addcontentsline{toc}{subsubsection}{Developing Bacula} @@ -806,7 +806,7 @@ top source directory, stop the daemons by entering: ./stopit then repeat the process. -\subsubsection*{Debugging} +\subsection{Debugging} \index{Debugging} \addcontentsline{toc}{subsubsection}{Debugging} @@ -818,7 +818,7 @@ 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. -\subsubsection*{Using a Debugger} +\subsection{Using a Debugger} \index{Using a Debugger} \index{Debugger!Using a} \addcontentsline{toc}{subsubsection}{Using a Debugger} @@ -845,7 +845,7 @@ 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)''. -\subsubsection*{Memory Leaks} +\subsection{Memory Leaks} \index{Leaks!Memory} \index{Memory Leaks} \addcontentsline{toc}{subsubsection}{Memory Leaks} @@ -862,7 +862,7 @@ 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. -\subsubsection*{Special Files} +\subsection{Special Files} \index{Files!Special} \index{Special Files} \addcontentsline{toc}{subsubsection}{Special Files} @@ -870,7 +870,7 @@ daemons. 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. -\subsubsection*{When Implementing Incomplete Code} +\subsection{When Implementing Incomplete Code} \index{Code!When Implementing Incomplete} \index{When Implementing Incomplete Code} \addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code} @@ -885,7 +885,7 @@ 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. -\subsubsection*{Bacula Source File Structure} +\subsection{Bacula Source File Structure} \index{Structure!Bacula Source File} \index{Bacula Source File Structure} \addcontentsline{toc}{subsubsection}{Bacula Source File Structure} @@ -981,7 +981,7 @@ Project gui: \end{verbatim} \normalsize -\subsubsection*{Header Files} +\subsection{Header Files} \index{Header Files} \index{Files!Header} \addcontentsline{toc}{subsubsection}{Header Files} @@ -1009,7 +1009,7 @@ 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. -\subsubsection*{Programming Standards} +\subsection{Programming Standards} \index{Standards!Programming} \index{Programming Standards} \addcontentsline{toc}{subsubsection}{Programming Standards} @@ -1029,7 +1029,7 @@ 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. -\subsubsection*{Do Not Use} +\subsection{Do Not Use} \index{Use!Do Not} \index{Do Not Use} \addcontentsline{toc}{subsubsection}{Do Not Use} @@ -1038,7 +1038,7 @@ so be conservative in your use of C++ features. \item STL -- it is totally incomprehensible. \end{itemize} -\subsubsection*{Avoid if Possible} +\subsection{Avoid if Possible} \index{Possible!Avoid if} \index{Avoid if Possible} \addcontentsline{toc}{subsubsection}{Avoid if Possible} @@ -1076,7 +1076,7 @@ so be conservative in your use of C++ features. \end{itemize} -\subsubsection*{Do Use Whenever Possible} +\subsection{Do Use Whenever Possible} \index{Possible!Do Use Whenever} \index{Do Use Whenever Possible} \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible} @@ -1095,7 +1095,7 @@ so be conservative in your use of C++ features. \end{itemize} -\subsubsection*{Indenting Standards} +\subsection{Indenting Standards} \index{Standards!Indenting} \index{Indenting Standards} \addcontentsline{toc}{subsubsection}{Indenting Standards} @@ -1215,7 +1215,7 @@ re-indent it to Bacula standards. If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth to 3. -\subsubsection*{Tabbing} +\subsection{Tabbing} \index{Tabbing} \addcontentsline{toc}{subsubsection}{Tabbing} @@ -1226,7 +1226,7 @@ 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). -\subsubsection*{Don'ts} +\subsection{Don'ts} \index{Don'ts} \addcontentsline{toc}{subsubsection}{Don'ts} @@ -1280,7 +1280,7 @@ the appropriate string to be concatenated to the ``\%''. Also please don't use the STL or Templates or any complicated C++ code. -\subsubsection*{Message Classes} +\subsection{Message Classes} \index{Classes!Message} \index{Message Classes} \addcontentsline{toc}{subsubsection}{Message Classes} @@ -1288,7 +1288,7 @@ Also please don't use the STL or Templates or any complicated C++ code. Currently, there are five classes of messages: Debug, Error, Job, Memory, and Queued. -\subsubsection*{Debug Messages} +\subsection{Debug Messages} \index{Messages!Debug} \index{Debug Messages} \addcontentsline{toc}{subsubsection}{Debug Messages} @@ -1315,7 +1315,7 @@ Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf); Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name); -\subsubsection*{Error Messages} +\subsection{Error Messages} \index{Messages!Error} \index{Error Messages} \addcontentsline{toc}{subsubsection}{Error Messages} @@ -1359,7 +1359,7 @@ 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)); -\subsubsection*{Job Messages} +\subsection{Job Messages} \index{Job Messages} \index{Messages!Job} \addcontentsline{toc}{subsubsection}{Job Messages} @@ -1380,7 +1380,7 @@ 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. -\subsubsection*{Queued Job Messages} +\subsection{Queued Job Messages} \index{Queued Job Messages} \index{Messages!Job} \addcontentsline{toc}{subsubsection}{Queued Job Messages} @@ -1391,7 +1391,7 @@ recursive loops, and to ensure that messages can be delivered even in the event of a network error. -\subsubsection*{Memory Messages} +\subsection{Memory Messages} \index{Messages!Memory} \index{Memory Messages} \addcontentsline{toc}{subsubsection}{Memory Messages} diff --git a/docs/developers/md5.tex b/docs/developers/md5.tex index 1fa7a7ef..aed995b4 100644 --- a/docs/developers/md5.tex +++ b/docs/developers/md5.tex @@ -1,11 +1,11 @@ %% %% -\section*{Bacula MD5 Algorithm} +\chapter{Bacula MD5 Algorithm} \label{MD5Chapter} \addcontentsline{toc}{section}{} -\subsection*{Command Line Message Digest Utility } +\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} @@ -17,20 +17,20 @@ 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. -\subsubsection*{Name} +\subsection{Name} \index{Name} \addcontentsline{toc}{subsubsection}{Name} {\bf md5} - generate / check MD5 message digest -\subsubsection*{Synopsis} +\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} ] -\subsubsection*{Description} +\subsection{Description} \index{Description } \addcontentsline{toc}{subsubsection}{Description} @@ -83,7 +83,7 @@ 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. -\subsubsection*{Options} +\subsection{Options} \index{Options } \addcontentsline{toc}{subsubsection}{Options} @@ -109,7 +109,7 @@ infile} should be specified. Print how-to-call information. \end{description} -\subsubsection*{Files} +\subsection{Files} \index{Files } \addcontentsline{toc}{subsubsection}{Files} @@ -119,7 +119,7 @@ If no {\it infile} or {\bf -d} option is specified or {\it infile} is a single output are processed strictly serially; consequently {\bf md5} may be used in pipelines. -\subsubsection*{Bugs} +\subsection{Bugs} \index{Bugs } \addcontentsline{toc}{subsubsection}{Bugs} @@ -131,7 +131,7 @@ 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. -\subsection*{ +\section{ \elink{Download md5.zip}{http://www.fourmilab.ch/md5/md5.zip} (Zipped archive)} \index{Archive!Download md5.zip Zipped } @@ -145,14 +145,14 @@ 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. -\subsubsection*{See Also} +\subsection{See Also} \index{ALSO!SEE } \index{See Also } \addcontentsline{toc}{subsubsection}{SEE ALSO} {\bf sum}(1) -\subsubsection*{Exit Status} +\subsection{Exit Status} \index{Status!Exit } \index{Exit Status } \addcontentsline{toc}{subsubsection}{Exit Status} @@ -162,7 +162,7 @@ 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. -\subsubsection*{Copying} +\subsection{Copying} \index{Copying } \addcontentsline{toc}{subsubsection}{Copying} @@ -173,7 +173,7 @@ fee is hereby granted, without any conditions or restrictions. This software is provided ``as is'' without express or implied warranty. \end{quote} -\subsubsection*{Acknowledgements} +\subsection{Acknowledgements} \index{Acknowledgements } \addcontentsline{toc}{subsubsection}{Acknowledgements} diff --git a/docs/developers/mediaformat.tex b/docs/developers/mediaformat.tex index e498502b..cc824f78 100644 --- a/docs/developers/mediaformat.tex +++ b/docs/developers/mediaformat.tex @@ -1,13 +1,13 @@ %% %% -\section*{Storage Media Output Format} +\chapter{Storage Media Output Format} \label{_ChapterStart9} \index{Format!Storage Media Output} \index{Storage Media Output Format} \addcontentsline{toc}{section}{Storage Media Output Format} -\subsection*{General} +\section{General} \index{General} \addcontentsline{toc}{subsection}{General} @@ -21,7 +21,7 @@ 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}. -\subsection*{Definitions} +\section{Definitions} \index{Definitions} \addcontentsline{toc}{subsection}{Definitions} @@ -161,7 +161,7 @@ Label except that it contains additional information pertaining to the Session. \end{description} -\subsection*{Storage Daemon File Output Format} +\section{Storage Daemon File Output Format} \index{Format!Storage Daemon File Output} \index{Storage Daemon File Output Format} \addcontentsline{toc}{subsection}{Storage Daemon File Output Format} @@ -175,7 +175,7 @@ older tape drives only support block sizes of 32K). Each Session written to tape is terminated with an End of File mark (this will be removed later). Sessions written to file are simply appended to the end of the file. -\subsection*{Overall Format} +\section{Overall Format} \index{Format!Overall} \index{Overall Format} \addcontentsline{toc}{subsection}{Overall Format} @@ -208,7 +208,7 @@ written, thus ensuring that there is no duplication of data. In addition, since Bacula blocks are sequentially numbered within a Job, it is easy to ensure that no block is missing or duplicated. -\subsection*{Serialization} +\section{Serialization} \index{Serialization} \addcontentsline{toc}{subsection}{Serialization} @@ -216,7 +216,7 @@ All Block Headers, Record Headers, and Label Records are written using Bacula's serialization routines. These routines guarantee that the data is written to the output volume in a machine independent format. -\subsection*{Block Header} +\section{Block Header} \index{Header!Block} \index{Block Header} \addcontentsline{toc}{subsection}{Block Header} @@ -244,7 +244,7 @@ is written using the Bacula serialization routines and thus is guaranteed to be in machine independent format. See below for version 2 of the block header. -\subsection*{Record Header} +\section{Record Header} \index{Header!Record} \index{Record Header} \addcontentsline{toc}{subsection}{Record Header} @@ -349,7 +349,7 @@ Bacula finds only part of the data in the first record, it will automatically read the next record and concatenate the data record to form a full data record. -\subsection*{Version BB02 Block Header} +\section{Version BB02 Block Header} \index{Version BB02 Block Header} \index{Header!Version BB02 Block} \addcontentsline{toc}{subsection}{Version BB02 Block Header} @@ -378,7 +378,7 @@ recover as much information as possible from the tape by recovering blocks which are valid. The Block header is written using the Bacula serialization routines and thus is guaranteed to be in machine independent format. -\subsection*{Version 2 Record Header} +\section{Version 2 Record Header} \index{Version 2 Record Header} \index{Header!Version 2 Record} \addcontentsline{toc}{subsection}{Version 2 Record Header} @@ -393,7 +393,7 @@ VolSessionId and VolSessionTime. On reading each record from the Block, the VolSessionId and VolSessionTime is filled in the Record Header from the Block Header. -\subsection*{Volume Label Format} +\section{Volume Label Format} \index{Volume Label Format} \index{Format!Volume Label} \addcontentsline{toc}{subsection}{Volume Label Format} @@ -432,7 +432,7 @@ Note, the LabelType (Volume Label, Volume PreLabel, Session Start Label, ...) is stored in the record FileIndex field of the Record Header and does not appear in the data part of the record. -\subsection*{Session Label} +\section{Session Label} \index{Label!Session} \index{Session Label} \addcontentsline{toc}{subsection}{Session Label} @@ -495,7 +495,7 @@ part of the record. Also, the Stream field of the Record Header contains the JobId. This permits quick filtering without actually reading all the session data in many cases. -\subsection*{Overall Storage Format} +\section{Overall Storage Format} \index{Format!Overall Storage} \index{Overall Storage Format} \addcontentsline{toc}{subsection}{Overall Storage Format} @@ -729,7 +729,7 @@ data in many cases. \end{verbatim} \normalsize -\subsection*{Unix File Attributes} +\section{Unix File Attributes} \index{Unix File Attributes} \index{Attributes!Unix File} \addcontentsline{toc}{subsection}{Unix File Attributes} @@ -853,7 +853,7 @@ size in bytes } & {Data fork file size in bytes } \\ \end{longtable} -\subsection*{Old Depreciated Tape Format} +\section{Old Depreciated Tape Format} \index{Old Depreciated Tape Format} \index{Format!Old Depreciated Tape} \addcontentsline{toc}{subsection}{Old Depreciated Tape Format} diff --git a/docs/developers/mempool.tex b/docs/developers/mempool.tex index 84c7273d..a8130200 100644 --- a/docs/developers/mempool.tex +++ b/docs/developers/mempool.tex @@ -1,13 +1,13 @@ %% %% -\section*{Bacula Memory Management} +\chapter{Bacula Memory Management} \label{_ChapterStart7} \index{Management!Bacula Memory} \index{Bacula Memory Management} \addcontentsline{toc}{section}{Bacula Memory Management} -\subsection*{General} +\section{General} \index{General} \addcontentsline{toc}{subsection}{General} @@ -28,7 +28,7 @@ turn. They are: \item Pooled memory. \end{itemize} -\subsubsection*{Statically Allocated Memory} +\subsection{Statically Allocated Memory} \index{Statically Allocated Memory} \index{Memory!Statically Allocated} \addcontentsline{toc}{subsubsection}{Statically Allocated Memory} @@ -48,7 +48,7 @@ limited to 127 characters (MAX\_NAME\_LENGTH). Although this maximum size may change, particularly to accommodate Unicode, it will remain a relatively small value. -\subsubsection*{Dynamically Allocated Memory} +\subsection{Dynamically Allocated Memory} \index{Dynamically Allocated Memory} \index{Memory!Dynamically Allocated} \addcontentsline{toc}{subsubsection}{Dynamically Allocated Memory} @@ -80,7 +80,7 @@ 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. -\subsubsection*{Pooled and Non-pooled 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} diff --git a/docs/developers/netprotocol.tex b/docs/developers/netprotocol.tex index 34b325e9..45c2a8ed 100644 --- a/docs/developers/netprotocol.tex +++ b/docs/developers/netprotocol.tex @@ -1,13 +1,13 @@ %% %% -\section*{TCP/IP Network Protocol} +\chapter{TCP/IP Network Protocol} \label{_ChapterStart5} \index{TCP/IP Network Protocol} \index{Protocol!TCP/IP Network} \addcontentsline{toc}{section}{TCP/IP Network Protocol} -\subsection*{General} +\section{General} \index{General} \addcontentsline{toc}{subsection}{General} @@ -28,7 +28,7 @@ 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. -\subsection*{bnet and Threads} +\section{bnet and Threads} \index{Threads!bnet and} \index{Bnet and Threads} \addcontentsline{toc}{subsection}{bnet and Threads} @@ -44,7 +44,7 @@ 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. -\subsection*{bnet\_open} +\section{bnet\_open} \index{Bnet\_open} \addcontentsline{toc}{subsection}{bnet\_open} @@ -57,7 +57,7 @@ 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. -\subsection*{bnet\_send} +\section{bnet\_send} \index{Bnet\_send} \addcontentsline{toc}{subsection}{bnet\_send} @@ -79,7 +79,7 @@ following data packet. It returns: In the case of a failure, an error message will be sent to the JCR contained within the bsock packet. -\subsection*{bnet\_fsend} +\section{bnet\_fsend} \index{Bnet\_fsend} \addcontentsline{toc}{subsection}{bnet\_fsend} @@ -89,7 +89,7 @@ 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. -\subsection*{Additional Error information} +\section{Additional Error information} \index{Information!Additional Error} \index{Additional Error information} \addcontentsline{toc}{subsection}{Additional Error information} @@ -101,7 +101,7 @@ 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). -\subsection*{bnet\_recv} +\section{bnet\_recv} \index{Bnet\_recv} \addcontentsline{toc}{subsection}{bnet\_recv} @@ -125,7 +125,7 @@ maxbytes is less than the record size sent. It returns: It should be noted that bnet\_recv() is a blocking read. -\subsection*{bnet\_sig} +\section{bnet\_sig} \index{Bnet\_sig} \addcontentsline{toc}{subsection}{bnet\_sig} @@ -145,13 +145,13 @@ int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following: \item BNET\_PROMPT - Prompt for UA \end{enumerate} -\subsection*{bnet\_strerror} +\section{bnet\_strerror} \index{Bnet\_strerror} \addcontentsline{toc}{subsection}{bnet\_strerror} Returns a formated string corresponding to the last error that occurred. -\subsection*{bnet\_close} +\section{bnet\_close} \index{Bnet\_close} \addcontentsline{toc}{subsection}{bnet\_close} @@ -159,7 +159,7 @@ The connection with the server remains open until closed by the subroutine: void bnet\_close(BSOCK *sock) -\subsection*{Becoming a Server} +\section{Becoming a Server} \index{Server!Becoming a} \index{Becoming a Server} \addcontentsline{toc}{subsection}{Becoming a Server} @@ -171,7 +171,7 @@ 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. -\subsection*{Higher Level Conventions} +\section{Higher Level Conventions} \index{Conventions!Higher Level} \index{Higher Level Conventions} \addcontentsline{toc}{subsection}{Higher Level Conventions} diff --git a/docs/developers/platformsupport.tex b/docs/developers/platformsupport.tex index 7e7f8f51..a04e56f7 100644 --- a/docs/developers/platformsupport.tex +++ b/docs/developers/platformsupport.tex @@ -1,13 +1,13 @@ %% %% -\section*{Platform Support} +\chapter{Platform Support} \label{_PlatformChapter} \index{Support!Platform} \index{Platform Support} \addcontentsline{toc}{section}{Platform Support} -\subsection*{General} +\section{General} \index{General } \addcontentsline{toc}{subsection}{General} @@ -29,7 +29,7 @@ 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, ... -\subsection*{Requirements to become a Supported Platform} +\section{Requirements to become a Supported Platform} \index{Requirements!Platform} \index{Platform Requirements} \addcontentsline{toc}{subsection}{Platform Requirements} diff --git a/docs/developers/porting.tex b/docs/developers/porting.tex index 60561eb0..278f0e5d 100644 --- a/docs/developers/porting.tex +++ b/docs/developers/porting.tex @@ -1,7 +1,7 @@ %% %% -\section*{Bacula Porting Notes} +\chapter{Bacula Porting Notes} \label{_ChapterStart1} \index{Notes!Bacula Porting} \index{Bacula Porting Notes} @@ -15,10 +15,10 @@ 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. -\subsection*{Porting Requirements} +\section{Porting Requirements} \index{Requirements!Porting} \index{Porting Requirements} -\addcontentsline{toc}{subsection}{Porting Requirements} +\addcontentsline{toc}{section}{Porting Requirements} In General, the following holds true: @@ -53,10 +53,10 @@ distribution. should be relatively easy. \end{itemize} -\subsection*{Steps to Take for Porting} +\section{Steps to Take for Porting} \index{Porting!Steps to Take for} \index{Steps to Take for Porting} -\addcontentsline{toc}{subsection}{Steps to Take for Porting} +\addcontentsline{toc}{section}{Steps to Take for Porting} \begin{itemize} \item The first step is to ensure that you have version 2.13 or later of the diff --git a/docs/developers/smartall.tex b/docs/developers/smartall.tex index b76826ff..41f66f08 100644 --- a/docs/developers/smartall.tex +++ b/docs/developers/smartall.tex @@ -5,14 +5,13 @@ Detection} \includegraphics{./smartall.eps} -\section*{Smart Memory Allocation With Orphaned Buffer Detection } +\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} - Few things are as embarrassing as a program that leaks, yet few errors are so easy to commit or as difficult to track down in a large, complicated program as failure to release allocated memory. SMARTALLOC replaces the standard C @@ -41,10 +40,10 @@ 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. -\subsubsection*{ Installing SMARTALLOC} +\subsection{ Installing SMARTALLOC} \index{SMARTALLOC!Installing } \index{Installing SMARTALLOC } -\addcontentsline{toc}{subsubsection}{Installing SMARTALLOC} +\addcontentsline{toc}{subsection}{Installing SMARTALLOC} SMARTALLOC is provided as a Zipped archive, \elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}; see the @@ -91,10 +90,10 @@ Orphaned buffer: 120 bytes allocated at line 50 of gutshot.c \end{verbatim} \normalsize -\subsubsection*{ Squelching a SMARTALLOC} +\subsection{ Squelching a SMARTALLOC} \index{SMARTALLOC!Squelching a } \index{Squelching a SMARTALLOC } -\addcontentsline{toc}{subsubsection}{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 @@ -134,10 +133,10 @@ to resume normal monitoring of buffer allocations. Buffers allocated while all the other safeguards provided by SMARTALLOC remain in effect. You may release such buffers, if you like; but you don't have to. -\subsubsection*{ Living with Libraries} +\subsection{ Living with Libraries} \index{Libraries!Living with } \index{Living with Libraries } -\addcontentsline{toc}{subsubsection}{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 @@ -210,10 +209,10 @@ 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()}. -\subsubsection*{ SMARTALLOC Details} +\subsection{ SMARTALLOC Details} \index{SMARTALLOC Details } \index{Details!SMARTALLOC } -\addcontentsline{toc}{subsubsection}{SMARTALLOC Details} +\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 @@ -292,10 +291,10 @@ 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. -\subsubsection*{ When SMARTALLOC is Disabled} +\subsection{ When SMARTALLOC is Disabled} \index{When SMARTALLOC is Disabled } \index{Disabled!When SMARTALLOC is } -\addcontentsline{toc}{subsubsection}{When SMARTALLOC is Disabled} +\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 @@ -312,10 +311,10 @@ 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. -\subsubsection*{ The {\tt alloc()} Function} +\subsection{ The {\tt alloc()} Function} \index{Function!alloc } \index{Alloc() Function } -\addcontentsline{toc}{subsubsection}{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 @@ -331,10 +330,10 @@ 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. -\subsubsection*{ Overlays and Underhandedness} +\subsection{ Overlays and Underhandedness} \index{Underhandedness!Overlays and } \index{Overlays and Underhandedness } -\addcontentsline{toc}{subsubsection}{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 @@ -371,10 +370,10 @@ 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. -\subsubsection*{ Test and Demonstration Program} +\subsection{ Test and Demonstration Program} \index{Test and Demonstration Program } \index{Program!Test and Demonstration } -\addcontentsline{toc}{subsubsection}{Test and Demonstration Program} +\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 @@ -382,10 +381,10 @@ 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. -\subsubsection*{ Invitation to the Hack} +\subsection{ Invitation to the Hack} \index{Hack!Invitation to the } \index{Invitation to the Hack } -\addcontentsline{toc}{subsubsection}{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 @@ -404,22 +403,22 @@ 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. -\subsection*{ +\section{ \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}{subsection}{ 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 \elink{Zipped}{http://www.pkware.com/} archive containing source code, documentation, and a {\tt Makefile} to build the software under Unix. -\subsubsection*{ Copying} +\subsection{ Copying} \index{Copying } -\addcontentsline{toc}{subsubsection}{Copying} +\addcontentsline{toc}{subsection}{Copying} \begin{quote} SMARTALLOC is in the public domain. Permission to use, copy, modify, and diff --git a/docs/developers/storage.tex b/docs/developers/storage.tex index 83394d0a..e46f228c 100644 --- a/docs/developers/storage.tex +++ b/docs/developers/storage.tex @@ -1,7 +1,7 @@ %% %% -\section*{Storage Daemon Design} +\chapter{Storage Daemon Design} \label{_ChapterStart3} \index{Storage Daemon Design } \index{Design!Storage Daemon } @@ -14,10 +14,10 @@ system administrators that want or need to know more of the working details of This document is somewhat out of date. -\subsection*{SD Design Introduction} +\section{SD Design Introduction} \index{Introduction!SD Design } \index{SD Design Introduction } -\addcontentsline{toc}{subsection}{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 @@ -33,10 +33,10 @@ remote. The ability to employ remote storage daemons (with appropriate security measures) permits automatic off-site backup, possibly to publicly available backup repositories. -\subsection*{SD Development Outline} +\section{SD Development Outline} \index{Outline!SD Development } \index{SD Development Outline } -\addcontentsline{toc}{subsection}{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 @@ -55,10 +55,10 @@ techniques such as POSIX threads, shared memory, asynchronous I/O, buffering to high-speed intermediate media, and support for tape changers and jukeboxes. -\subsection*{SD Connections and Sessions} +\section{SD Connections and Sessions} \index{Sessions!SD Connections and } \index{SD Connections and Sessions } -\addcontentsline{toc}{subsection}{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 @@ -83,10 +83,10 @@ restarting of the storage daemon, etc. These details will be filled in, along with a comprehensive list of status codes along with which requests can produce them in an update to this document. -\subsubsection*{SD Append Requests} +\subsection{SD Append Requests} \index{Requests!SD Append } \index{SD Append Requests } -\addcontentsline{toc}{subsubsection}{SD Append Requests} +\addcontentsline{toc}{subsection}{SD Append Requests} \begin{description} @@ -155,10 +155,10 @@ volume-session-id} is the volume session ID for blocks from the session stored on that volume. \end{description} -\subsubsection*{SD Read Requests} +\subsection{SD Read Requests} \index{SD Read Requests } \index{Requests!SD Read } -\addcontentsline{toc}{subsubsection}{SD Read Requests} +\addcontentsline{toc}{subsection}{SD Read Requests} \begin{description} @@ -208,9 +208,9 @@ at any time; you needn't read all its blocks before closing it. \elink{John Walker}{http://www.fourmilab.ch/} January 30th, MM } -\subsection*{SD Data Structures} +\section{SD Data Structures} \index{SD Data Structures} -\addcontentsline{toc}{subsection}{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 @@ -256,5 +256,3 @@ To be implemented three jobs, three physical devices, but DEVICE = Device only control data \end{verbatim} - - diff --git a/docs/developers/tls-techdoc.tex b/docs/developers/tls-techdoc.tex index 3b9c8145..565869f1 100644 --- a/docs/developers/tls-techdoc.tex +++ b/docs/developers/tls-techdoc.tex @@ -4,17 +4,16 @@ %\author{Landon Fuller} %\title{Bacula TLS Additions} -\section{TLS} +\chapter{TLS} \label{_Chapter_TLS} \index{TLS} -\addcontentsline{toc}{section}{TLS} Written by Landon Fuller -\subsection{Introduction to TLS} +\section{Introduction to TLS} \index{TLS Introduction} \index{Introduction!TLS} -\addcontentsline{toc}{subsection}{TLS Introduction} +\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 @@ -45,10 +44,10 @@ additional preprocessor defines have been added: \emph{HAVE\_TLS} and \emph{src/lib/tls.c} to facilitate the support of alternative TLS implementations. -\subsection{New Configuration Directives} +\section{New Configuration Directives} \index{TLS Configuration Directives} \index{Directives!TLS Configuration} -\addcontentsline{toc}{subsection}{New Configuration Directives} +\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: @@ -106,19 +105,19 @@ openssl dhparam -out dh1024.pem -5 1024 \normalsize \end{itemize} -\subsection{TLS API Implementation} +\section{TLS API Implementation} \index{TLS API Implimentation} \index{API Implimentation!TLS} -\addcontentsline{toc}{subsection}{TLS API Implementation} +\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 TLS API is exported. -\subsubsection{Library Initialization and Cleanup} +\subsection{Library Initialization and Cleanup} \index{Library Initialization and Cleanup} \index{Initialization and Cleanup!Library} -\addcontentsline{toc}{subsubsection}{Library Initialization and Cleanup} +\addcontentsline{toc}{subsection}{Library Initialization and Cleanup} \footnotesize \begin{verbatim} @@ -137,10 +136,10 @@ int cleanup_tls (void); Performs TLS library cleanup. -\subsubsection{Manipulating TLS Contexts} +\subsection{Manipulating TLS Contexts} \index{TLS Context Manipulation} \index{Contexts!Manipulating TLS} -\addcontentsline{toc}{subsubsection}{Manipulating TLS Contexts} +\addcontentsline{toc}{subsection}{Manipulating TLS Contexts} \footnotesize \begin{verbatim} @@ -169,10 +168,10 @@ void free_tls_context (TLS_CONTEXT *ctx); Deallocated a previously allocated \emph{TLS\_CONTEXT} structure. -\subsubsection{Performing Post-Connection Verification} +\subsection{Performing Post-Connection Verification} \index{TLS Post-Connection Verification} \index{Verification!TLS Post-Connection} -\addcontentsline{toc}{subsubsection}{Performing Post-Connection Verification} +\addcontentsline{toc}{subsection}{Performing Post-Connection Verification} \footnotesize \begin{verbatim} @@ -196,10 +195,10 @@ certificate. Checks whether the \emph{commonName} attribute matches any strings supplied via the \emph{verify\_list} parameter. Returns \emph{true} if there is a match, \emph{false} otherwise. -\subsubsection{Manipulating TLS Connections} +\subsection{Manipulating TLS Connections} \index{TLS Connection Manipulation} \index{Connections!Manipulating TLS} -\addcontentsline{toc}{subsubsection}{Manipulating TLS Connections} +\addcontentsline{toc}{subsection}{Manipulating TLS Connections} \footnotesize \begin{verbatim} @@ -272,10 +271,10 @@ the function, and restored to its original blocking state before the function returns. Less than \emph{nbytes} may be read if an error occurs. The actual number of bytes read will be returned. -\subsection{Bnet API Changes} +\section{Bnet API Changes} \index{Bnet API Changes} \index{API Changes!Bnet} -\addcontentsline{toc}{subsection}{Bnet API Changes} +\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, @@ -283,10 +282,10 @@ as well as a flag to designate the current blocking state of the socket. The blocking state flag is required for win32, where it does not appear possible to discern the current blocking state of a socket. -\subsubsection{Negotiating a TLS Connection} +\subsection{Negotiating a TLS Connection} \index{Negotiating a TLS Connection} \index{TLS Connection!Negotiating} -\addcontentsline{toc}{subsubsection}{Negotiating a TLS Connection} +\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: @@ -310,11 +309,11 @@ Accepts a TLS client session via \emph{bsock} using the settings from \emph{ctx}. If \emph{verify\_list} is non-NULL, it is passed to \emph{tls\_postconnect\_verify\_cn()} for client certificate verification. -\subsubsection{Manipulating Socket Blocking State} +\subsection{Manipulating Socket Blocking State} \index{Manipulating Socket Blocking State} \index{Socket Blocking State!Manipulating} \index{Blocking State!Socket!Manipulating} -\addcontentsline{toc}{subsubsection}{Manipulating Socket Blocking State} +\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 @@ -352,10 +351,10 @@ Restores blocking or non-blocking IO setting on the socket associated with \pagebreak -\subsection{Authentication Negotiation} +\section{Authentication Negotiation} \index{Authentication Negotiation} \index{Negotiation!TLS Authentication} -\addcontentsline{toc}{subsection}{Authentication Negotiation} +\addcontentsline{toc}{section}{Authentication Negotiation} Backwards compatibility with the existing SSL negotiation hooks implemented in src/lib/cram-md5.c have been maintained. The -- 2.39.5