From: Philippe Chauvat Date: Thu, 11 Oct 2012 15:38:34 +0000 (+0200) Subject: developer s guide should be ok: make tex and make pdflatex X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=29ebd504c7b9cd72d1acd56e3c1668490dcc4d46;p=bacula%2Fdocs developer s guide should be ok: make tex and make pdflatex --- diff --git a/docs/manuals/en/developers/Makefile.in b/docs/manuals/en/developers/Makefile.in index 3994aa8a..2d822884 100644 --- a/docs/manuals/en/developers/Makefile.in +++ b/docs/manuals/en/developers/Makefile.in @@ -12,10 +12,45 @@ # # make # +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# IMAGES=../../../images +MANUALSDIR=../.. DOC=developers +BSYSMANUALDIR=../../../bsysmanual +COVERSDIR=../../../covers +PDFCOVERSDIR=$(COVERSDIR)/pdf +SVGCOVERSDIR=$(COVERSDIR)/svg +EPSCOVERSDIR=$(COVERSDIR)/eps +LICENSESDIR=$(MANUALSDIR)/licences +COVERNAME=coverpage-developers +BSYSMANNAME=bsysmanual-coverpagebackground +LICENCES=$(wildcard $(LICENSESDIR)/*.tex) +BSYSCOMPILERFILE=bsys-compiler-mode.tex +PDFCOMPILERFILE=$(MANUALSDIR)/bsys-pdflatex-mode.tex +TEXCOMPILERFILE=$(MANUALSDIR)/bsys-latex-mode.tex +WEBCOMPILERFILE=$(MANUALSDIR)/bsys-web-mode.tex first_rule: all @@ -26,28 +61,64 @@ all: tex web pdf mini-clean .DONTCARE: -tex: +pdfcovers: + @echo -n "Linking coverpage and background PDF format..." + @(cd $(SVGCOVERSDIR) ; make pdf) + @ln -sf `pwd`/${PDFCOVERSDIR}/${COVERNAME}.pdf `pwd`/${BSYSMANUALDIR}/${BSYSMANNAME}.pdf + @echo "Done." + +pdfimages: + @echo "Generating PDF images..." + @(cd ${IMAGES}/svg ; make pdf) + @echo "Done." + +pngimages: + @echo "Generating PNG images..." + @(cd ${IMAGES}/svg ; make png) + @echo "Done." + +epsimages: + @echo "Generating EPS images..." + @(cd ${IMAGES}/svg ; make eps) + @rm -rf ${IMAGES}/png + @rm -rf ${IMAGES}/pdf + @echo "Done." + +epscovers: + @echo -n "Linking coverpage and background EPS format..." + @(cd $(SVGCOVERSDIR) ; make eps) + @ln -sf `pwd`/${EPSCOVERSDIR}/${COVERNAME}.eps `pwd`/${BSYSMANUALDIR}/${BSYSMANNAME}.eps + @rm -f `pwd`/${BSYSMANUALDIR}/${BSYSMANNAME}.pdf + @echo "Done." + +commonfiles: + @echo -n "Linking shared files..." + @(for L in $(LICENCES); do ln -sf $$L .; done) + @echo "Done" + +tex: epscovers epsimages commonfiles @../../update_version - @cp -fp ${IMAGES}/hires/*.eps . + @ln -sf $(TEXCOMPILERFILE) $(BSYSCOMPILERFILE) +# @cp -fp ${IMAGES}/hires/*.eps . touch ${DOC}.idx ${DOC}i-general.tex -latex -interaction=batchmode ${DOC}.tex makeindex ${DOC}.idx >/dev/null 2>/dev/null -latex -interaction=batchmode ${DOC}.tex -pdf: - @echo "Making ${DOC} pdf" - @cp -fp ${IMAGES}/hires/*.eps . - dvipdf ${DOC}.dvi ${DOC}.pdf - @rm -f *.eps *.old - -dvipdf: - @echo "Making ${DOC} pdfm" - @cp -fp ${IMAGES}/hires/*.eps . - dvipdfm -p a4 ${DOC}.dvi >tex.out 2>&1 +pdflatex: pdfcovers pdfimages commonfiles + @ln -sf $(PDFCOMPILERFILE) $(BSYSCOMPILERFILE) + pdflatex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null + makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null + makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null + makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null + pdflatex -interaction=batchmode ${DOC}.tex + pdflatex -interaction=batchmode ${DOC}.tex html: @echo "Making ${DOC} html" - @cp -fp ${IMAGES}/*.eps . +# @cp -fp ${IMAGES}/*.eps . @rm -f next.eps next.png prev.eps prev.png up.eps up.png @touch ${DOC}.html @(if [ -f imagename_translations ] ; then \ @@ -66,7 +137,7 @@ web: @rm -rf ${DOC} @mkdir -p ${DOC} @rm -f ${DOC}/* - @cp -fp ${IMAGES}/*.eps . +# @cp -fp ${IMAGES}/*.eps . @rm -f next.eps next.png prev.eps prev.png up.eps up.png @(if [ -f ${DOC}/imagename_translations ] ; then \ ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html; \ diff --git a/docs/manuals/en/developers/catalog.tex b/docs/manuals/en/developers/catalog.tex index bcdedfbd..b3500236 100644 --- a/docs/manuals/en/developers/catalog.tex +++ b/docs/manuals/en/developers/catalog.tex @@ -13,11 +13,11 @@ 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 administrators that want or need to know more of the working details of {\bf -Bacula}. +Bacula}. The {\bf Bacula Catalog} services consist of the programs that provide the SQL database engine for storage and retrieval of all information concerning files -that were backed up and their locations on the storage media. +that were backed up and their locations on the storage media. We have investigated the possibility of using the following SQL engines for Bacula: Beagle, mSQL, GNU SQL, PostgreSQL, SQLite, Oracle, and MySQL. Each @@ -38,13 +38,13 @@ serious production use. The Bacula SQL code has been written in a manner that will allow it to be easily modified to support any of the current SQL database systems on the market (for example: mSQL, iODBC, unixODBC, Solid, OpenLink ODBC, EasySoft -ODBC, InterBase, Oracle8, Oracle7, and DB2). +ODBC, InterBase, Oracle8, Oracle7, and DB2). -If you do not specify either {\bf \verb{--{with-mysql} or {\bf \verb{--{with-postgresql} or -{\bf \verb{--{with-sqlite} on the ./configure line, Bacula will use its minimalist +If you do not specify either \lstinline+--with-mysql+ or \lstinline+--with-postgresq+ or +\lstinline+--with-sqlite+ on the ./configure line, Bacula will use its minimalist 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. +PostgreSQL, or SQLite) to run. \subsection{Filenames and Maximum Filename Length} \index[general]{Filenames and Maximum Filename Length } @@ -59,59 +59,58 @@ characters. These restrictions are believed to have been removed. Please note, these restrictions apply only to the Catalog database and thus to your ability 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. +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} +%\addcontentsline{toc}{subsubsection}{Installing and Configuring MySQL} -For the details of installing and configuring MySQL, please see the -\ilink{Installing and Configuring MySQL}{_ChapterStart} chapter of -this manual. +For the details of installing and configuring MySQL, please see the +\bsysxrlink{Installing and Configuring MySQL}{MySqlChapter}{main}{chapter} of +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} +%\addcontentsline{toc}{subsubsection}{Installing and Configuring PostgreSQL} -For the details of installing and configuring PostgreSQL, please see the -\ilink{Installing and Configuring PostgreSQL}{_ChapterStart10} -chapter of this manual. +For the details of installing and configuring PostgreSQL, please see the +\bsysxrlink{Installing and Configuring PostgreSQL}{PostgreSqlChapter}{main}{chapter} + of the \mainman{}. \subsection{Installing and Configuring SQLite} \index[general]{Installing and Configuring SQLite } \index[general]{SQLite!Installing and Configuring } -\addcontentsline{toc}{subsubsection}{Installing and Configuring SQLite} +%\addcontentsline{toc}{subsubsection}{Installing and Configuring SQLite} -For the details of installing and configuring SQLite, please see the -\ilink{Installing and Configuring SQLite}{_ChapterStart33} chapter of -this manual. +For the details of installing and configuring SQLite, please see the +\bsysxrlink{Installing and Configuring SQLite}{SqlLiteChapter}{main}{chapter} of +the \mainman{}. \subsection{Internal Bacula Catalog} \index[general]{Catalog!Internal Bacula } \index[general]{Internal Bacula Catalog } -\addcontentsline{toc}{subsubsection}{Internal Bacula Catalog} +%\addcontentsline{toc}{subsubsection}{Internal Bacula Catalog} -Please see the -\ilink{Internal Bacula Database}{_ChapterStart42} chapter of this -manual for more details. +Please see the \bsysxrlink{Internal Bacula Database} +{chap:InternalBaculaDatabase}{misc}{chapter} of the \miscman{} for more details. \subsection{Database Table Design} \index[general]{Design!Database Table } \index[general]{Database Table Design } -\addcontentsline{toc}{subsubsection}{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 fields in the SQLite database are stored as ASCII text and some of the database creation statements are a bit different. The details of the internal -Bacula catalog are not discussed here. +Bacula catalog are not discussed here. Because the Catalog database may contain very large amounts of data for large sites, we have made a modest attempt to normalize the data tables to reduce redundant information. While reducing the size of the database significantly, -it does, unfortunately, add some complications to the structures. +it does, unfortunately, add some complications to the structures. In simple terms, the Catalog database must contain a record of all Jobs run by Bacula, and for each Job, it must maintain a list of all files saved, with @@ -121,14 +120,14 @@ represents a huge amount interlinked data. Note: the list of files and their attributes is not maintained when using the internal Bacula database. The data stored in the File records, which allows the user or administrator to obtain a list of all files backed up during a job, is by far the largest volume of -information put into the Catalog database. +information put into the Catalog database. Although the Catalog database has been designed to handle backup data for multiple clients, some users may want to maintain multiple databases, one for each machine to be backed up. This reduces the risk of confusion of accidental 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. +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 } @@ -141,207 +140,93 @@ MediaCoordinates. (PartNumber, NumParts). In the steps below, ``Create new'' means to create a new record whether or not it is unique. ``Create unique'' means each record in the database should be unique. Thus, one must first search to see if the record exists, and only if not should a new one be -created, otherwise the existing RecordId should be used. +created, otherwise the existing RecordId should be used. \begin{enumerate} -\item Create new Job record with StartDate; save JobId -\item Create unique Media record; save MediaId -\item Create unique Client record; save ClientId -\item Create unique Filename record; save FilenameId -\item Create unique Path record; save PathId -\item Create unique Attribute record; save AttributeId - store ClientId, FilenameId, PathId, and Attributes -\item Create new File record - store JobId, AttributeId, MediaCoordinates, etc -\item Repeat steps 4 through 8 for each file -\item Create a JobMedia record; save MediaId -\item Update Job record filling in EndDate and other Job statistics +\item Create new Job record with StartDate; save JobId +\item Create unique Media record; save MediaId +\item Create unique Client record; save ClientId +\item Create unique Filename record; save FilenameId +\item Create unique Path record; save PathId +\item Create unique Attribute record; save AttributeId + store ClientId, FilenameId, PathId, and Attributes +\item Create new File record + store JobId, AttributeId, MediaCoordinates, etc +\item Repeat steps 4 through 8 for each file +\item Create a JobMedia record; save MediaId +\item Update Job record filling in EndDate and other Job statistics \end{enumerate} \section{Database Tables} \index[general]{Database Tables } \index[general]{Tables!Database } -\addcontentsline{toc}{subsection}{Database Tables} - -\addcontentsline{lot}{table}{Filename Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Filename } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{l| }{\bf Data Type } -& \multicolumn{1}{l| }{\bf Remark } \\ - \hline -{FilenameId } & {integer } & {Primary Key } \\ - \hline -{Name } & {Blob } & {Filename } -\\ \hline - -\end{longtable} - -The {\bf Filename} table shown above contains the name of each file backed up +%\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} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Path } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{PathId } & {integer } & {Primary Key } \\ - \hline -{Path } & {Blob } & {Full Path } -\\ \hline - -\end{longtable} - -The {\bf Path} table contains shown above the path or directory names of all +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 directories on the system or systems. The filename and any MSDOS disk name are stripped off. As with the filename, only one copy of each directory name is kept regardless of how many machines or drives have the same directory. These -path names should be stored in Unix path name format. +path names should be stored in Unix path name format. Some simple testing on a Linux file system indicates that separating the filename and the path may be more complication than is warranted by the space savings. For example, this system has a total of 89,097 files, 60,467 of which -have unique filenames, and there are 4,374 unique paths. +have unique filenames, and there are 4,374 unique paths. Finding all those files and doing two stats() per file takes an average wall -clock time of 1 min 35 seconds on a 400MHz machine running RedHat 6.1 Linux. +clock time of 1 min 35 seconds on a 400MHz machine running RedHat 6.1 Linux. Finding all those files and putting them directly into a MySQL database with the path and filename defined as TEXT, which is variable length up to 65,535 -characters takes 19 mins 31 seconds and creates a 27.6 MByte database. +characters takes 19 mins 31 seconds and creates a 27.6 MByte database. Doing the same thing, but inserting them into Blob fields with the filename indexed on the first 30 characters and the path name indexed on the 255 (max) characters takes 5 mins 18 seconds and creates a 5.24 MB database. Rerunning -the job (with the database already created) takes about 2 mins 50 seconds. +the job (with the database already created) takes about 2 mins 50 seconds. Running the same as the last one (Path and Filename Blob), but Filename indexed on the first 30 characters and the Path on the first 50 characters (linear search done there after) takes 5 mins on the average and creates a 3.4 MB database. Rerunning with the data already in the DB takes 3 mins 35 -seconds. +seconds. Finally, saving only the full path name rather than splitting the path and the file, and indexing it on the first 50 characters takes 6 mins 43 seconds and -creates a 7.35 MB database. - -\ - -\addcontentsline{lot}{table}{File Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf File } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{FileId } & {integer } & {Primary Key } \\ - \hline -{FileIndex } & {integer } & {The sequential file number in the Job } \\ - \hline -{JobId } & {integer } & {Link to Job Record } \\ - \hline -{PathId } & {integer } & {Link to Path Record } \\ - \hline -{FilenameId } & {integer } & {Link to Filename Record } \\ - \hline -{MarkId } & {integer } & {Used to mark files during Verify Jobs } \\ - \hline -{LStat } & {tinyblob } & {File attributes in base64 encoding } \\ - \hline -{MD5 } & {tinyblob } & {MD5/SHA1 signature in base64 encoding } -\\ \hline - -\end{longtable} - -The {\bf File} table shown above contains one entry for each file backed up by +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 Bacula. Thus a file that is backed up multiple times (as is normal) will have multiple entries in the File table. This will probably be the table with the most number of records. Consequently, it is essential to keep the size of this record to an absolute minimum. At the same time, this table must contain all the information (or pointers to the information) about the file and where it is backed up. Since a file may be backed up many times without having changed, -the path and filename are stored in separate tables. +the path and filename are stored in separate tables. This table contains by far the largest amount of information in the Catalog database, both from the stand point of number of records, and the stand point 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} -\begin{longtable}{|l|l|p{2.5in}|} - \hline -\multicolumn{3}{|l| }{\bf Job } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{JobId } & {integer } & {Primary Key } \\ - \hline -{Job } & {tinyblob } & {Unique Job Name } \\ - \hline -{Name } & {tinyblob } & {Job Name } \\ - \hline -{PurgedFiles } & {tinyint } & {Used by Bacula for purging/retention periods -} \\ - \hline -{Type } & {binary(1) } & {Job Type: Backup, Copy, Clone, Archive, Migration -} \\ - \hline -{Level } & {binary(1) } & {Job Level } \\ - \hline -{ClientId } & {integer } & {Client index } \\ - \hline -{JobStatus } & {binary(1) } & {Job Termination Status } \\ - \hline -{SchedTime } & {datetime } & {Time/date when Job scheduled } \\ - \hline -{StartTime } & {datetime } & {Time/date when Job started } \\ - \hline -{EndTime } & {datetime } & {Time/date when Job ended } \\ - \hline -{RealEndTime } & {datetime } & {Time/date when original Job ended } \\ - \hline -{JobTDate } & {bigint } & {Start day in Unix format but 64 bits; used for -Retention period. } \\ - \hline -{VolSessionId } & {integer } & {Unique Volume Session ID } \\ - \hline -{VolSessionTime } & {integer } & {Unique Volume Session Time } \\ - \hline -{JobFiles } & {integer } & {Number of files saved in Job } \\ - \hline -{JobBytes } & {bigint } & {Number of bytes saved in Job } \\ - \hline -{JobErrors } & {integer } & {Number of errors during Job } \\ - \hline -{JobMissingFiles } & {integer } & {Number of files not saved (not yet used) } -\\ - \hline -{PoolId } & {integer } & {Link to Pool Record } \\ - \hline -{FileSetId } & {integer } & {Link to FileSet Record } \\ - \hline -{PrioJobId } & {integer } & {Link to prior Job Record when migrated } \\ - \hline -{PurgedFiles } & {tiny integer } & {Set when all File records purged } \\ - \hline -{HasBase } & {tiny integer } & {Set when Base Job run } -\\ \hline - -\end{longtable} - -The {\bf Job} table contains one record for each Job run by Bacula. Thus +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 normally, there will be one per day per machine added to the database. Note, the JobId is used to index Job records in the database, and it often is shown to the user in the Console program. However, care must be taken with its use @@ -349,635 +234,153 @@ as it is not unique from database to database. For example, the user may have a database for Client data saved on machine Rufus and another database for Client data saved on machine Roxie. In this case, the two database will each have JobIds that match those in another database. For a unique reference to a -Job, see Job below. +Job, see Job below. The Name field of the Job record corresponds to the Name resource record given in the Director's configuration file. Thus it is a generic name, and it will -be normal to find many Jobs (or even all Jobs) with the same Name. +be normal to find many Jobs (or even all Jobs) with the same Name. The Job field contains a combination of the Name and the schedule time of the Job by the Director. Thus for a given Director, even with multiple Catalog -databases, the Job will contain a unique name that represents the Job. +databases, the Job will contain a unique name that represents the Job. For a given Storage daemon, the VolSessionId and VolSessionTime form a unique identification of the Job. This will be the case even if multiple Directors -are using the same Storage daemon. - -The Job Type (or simply Type) can have one of the following values: - -\addcontentsline{lot}{table}{Job Types} -\begin{longtable}{|l|l|} - \hline -\multicolumn{1}{|c| }{\bf Value } & \multicolumn{1}{c| }{\bf Meaning } \\ - \hline -{B } & {Backup Job } \\ - \hline -{M } & {Migrated Job } \\ - \hline -{V } & {Verify Job } \\ - \hline -{R } & {Restore Job } \\ - \hline -{C } & {Console program (not in database) } \\ - \hline -{I } & {Internal or system Job } \\ - \hline -{D } & {Admin Job } \\ - \hline -{A } & {Archive Job (not implemented) } -\\ \hline -{C } & {Copy Job } \\ - \hline -{g } & {Migration Job } \\ - \hline - -\end{longtable} -Note, the Job Type values noted above are not kept in an SQL table. +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. The JobStatus field specifies how the job terminated, and can be one of the -following: - -\addcontentsline{lot}{table}{Job Statuses} -\begin{longtable}{|l|l|} - \hline -\multicolumn{1}{|c| }{\bf Value } & \multicolumn{1}{c| }{\bf Meaning } \\ - \hline -{C } & {Created but not yet running } \\ - \hline -{R } & {Running } \\ - \hline -{B } & {Blocked } \\ - \hline -{T } & {Terminated normally } \\ - \hline -{W } & {Terminated normally with warnings } -\\ \hline -{E } & {Terminated in Error } \\ - \hline -{e } & {Non-fatal error } \\ - \hline -{f } & {Fatal error } \\ - \hline -{D } & {Verify Differences } \\ - \hline -{A } & {Canceled by the user } \\ - \hline -{I } & {Incomplete Job } -\\ \hline -{F } & {Waiting on the File daemon } \\ - \hline -{S } & {Waiting on the Storage daemon } \\ - \hline -{m } & {Waiting for a new Volume to be mounted } \\ - \hline -{M } & {Waiting for a Mount } \\ - \hline -{s } & {Waiting for Storage resource } \\ - \hline -{j } & {Waiting for Job resource } \\ - \hline -{c } & {Waiting for Client resource } \\ - \hline -{d } & {Wating for Maximum jobs } \\ - \hline -{t } & {Waiting for Start Time } \\ - \hline -{p } & {Waiting for higher priority job to finish } -\\ \hline -{i } & {Doing batch insert file records } -\\ \hline -{a } & {SD despooling attributes } -\\ \hline -{l } & {Doing data despooling } -\\ \hline -{L } & {Committing data (last despool) } -\\ \hline - - - -\end{longtable} - -\addcontentsline{lot}{table}{File Sets Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf FileSet } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\ -\ \ } & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{FileSetId } & {integer } & {Primary Key } \\ - \hline -{FileSet } & {tinyblob } & {FileSet name } \\ - \hline -{MD5 } & {tinyblob } & {MD5 checksum of FileSet } \\ - \hline -{CreateTime } & {datetime } & {Time and date Fileset created } -\\ \hline - -\end{longtable} - -The {\bf FileSet} table contains one entry for each FileSet that is used. The +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 MD5 signature is kept to ensure that if the user changes anything inside the FileSet, it will be detected and the new FileSet will be used. This is particularly important when doing an incremental update. If the user deletes a file or adds a file, we need to ensure that a Full backup is done prior to the -next incremental. - - -\addcontentsline{lot}{table}{JobMedia Table Layout} -\begin{longtable}{|l|l|p{2.5in}|} - \hline -\multicolumn{3}{|l| }{\bf JobMedia } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\ -\ \ } & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{JobMediaId } & {integer } & {Primary Key } \\ - \hline -{JobId } & {integer } & {Link to Job Record } \\ - \hline -{MediaId } & {integer } & {Link to Media Record } \\ - \hline -{FirstIndex } & {integer } & {The index (sequence number) of the first file -written for this Job to the Media } \\ - \hline -{LastIndex } & {integer } & {The index of the last file written for this -Job to the Media } \\ - \hline -{StartFile } & {integer } & {The physical media (tape) file number of the -first block written for this Job } \\ - \hline -{EndFile } & {integer } & {The physical media (tape) file number of the -last block written for this Job } \\ - \hline -{StartBlock } & {integer } & {The number of the first block written for -this Job } \\ - \hline -{EndBlock } & {integer } & {The number of the last block written for this -Job } \\ - \hline -{VolIndex } & {integer } & {The Volume use sequence number within the Job } -\\ \hline - -\end{longtable} - -The {\bf JobMedia} table contains one entry at the following: start of +next incremental. + + +%\addcontentsline{lot}{table} +\LTXtable{\linewidth}{table_dbjobmedia} + +The {\bf JobMedia} table \bsysref{table:dbjobmedia} contains one entry at the following: start of the job, start of each new tape file, start of each new tape, end of the job. Since by default, a new tape file is written every 2GB, in general, you will have more than 2 JobMedia records per Job. The number can be -varied by changing the "Maximum File Size" specified in the Device +varied by changing the "Maximum File Size" specified in the Device resource. This record allows Bacula to efficiently position close to (within 2GB) any given file in a backup. For restoring a full Job, these records are not very important, but if you want to retrieve -a single file that was written near the end of a 100GB backup, the +a single file that was written near the end of a 100GB backup, the JobMedia records can speed it up by orders of magnitude by permitting forward spacing files and blocks rather than reading the whole 100GB backup. - - - - -\addcontentsline{lot}{table}{Media Table Layout} -\begin{longtable}{|l|l|p{2.4in}|} - \hline -\multicolumn{3}{|l| }{\bf Media } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\ -\ \ } & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{MediaId } & {integer } & {Primary Key } \\ - \hline -{VolumeName } & {tinyblob } & {Volume name } \\ - \hline -{Slot } & {integer } & {Autochanger Slot number or zero } \\ - \hline -{PoolId } & {integer } & {Link to Pool Record } \\ - \hline -{MediaType } & {tinyblob } & {The MediaType supplied by the user } \\ - \hline -{MediaTypeId } & {integer } & {The MediaTypeId } \\ - \hline -{LabelType } & {tinyint } & {The type of label on the Volume } \\ - \hline -{FirstWritten } & {datetime } & {Time/date when first written } \\ - \hline -{LastWritten } & {datetime } & {Time/date when last written } \\ - \hline -{LabelDate } & {datetime } & {Time/date when tape labeled } \\ - \hline -{VolJobs } & {integer } & {Number of jobs written to this media } \\ - \hline -{VolFiles } & {integer } & {Number of files written to this media } \\ - \hline -{VolBlocks } & {integer } & {Number of blocks written to this media } \\ - \hline -{VolMounts } & {integer } & {Number of time media mounted } \\ - \hline -{VolBytes } & {bigint } & {Number of bytes saved in Job } \\ - \hline -{VolParts } & {integer } & {The number of parts for a Volume (DVD) } \\ - \hline -{VolErrors } & {integer } & {Number of errors during Job } \\ - \hline -{VolWrites } & {integer } & {Number of writes to media } \\ - \hline -{MaxVolBytes } & {bigint } & {Maximum bytes to put on this media } \\ - \hline -{VolCapacityBytes } & {bigint } & {Capacity estimate for this volume } \\ - \hline -{VolStatus } & {enum } & {Status of media: Full, Archive, Append, Recycle, -Read-Only, Disabled, Error, Busy } \\ - \hline -{Enabled } {tinyint } & {Whether or not Volume can be written } \\ - \hline -{Recycle } & {tinyint } & {Whether or not Bacula can recycle the Volumes: -Yes, No } \\ - \hline -{ActionOnPurge } & {tinyint } & {What happens to a Volume after purging } \\ - \hline -{VolRetention } & {bigint } & {64 bit seconds until expiration } \\ - \hline -{VolUseDuration } & {bigint } & {64 bit seconds volume can be used } \\ - \hline -{MaxVolJobs } & {integer } & {maximum jobs to put on Volume } \\ - \hline -{MaxVolFiles } & {integer } & {maximume EOF marks to put on Volume } -\\ \hline -{InChanger } & {tinyint } & {Whether or not Volume in autochanger } \\ - \hline -{StorageId } & {integer } & {Storage record ID } \\ - \hline -{DeviceId } & {integer } & {Device record ID } \\ - \hline -{MediaAddressing } & {integer } & {Method of addressing media } \\ - \hline -{VolReadTime } & {bigint } & {Time Reading Volume } \\ - \hline -{VolWriteTime } & {bigint } & {Time Writing Volume } \\ - \hline -{EndFile } & {integer } & {End File number of Volume } \\ - \hline -{EndBlock } & {integer } & {End block number of Volume } \\ - \hline -{LocationId } & {integer } & {Location record ID } \\ - \hline -{RecycleCount } & {integer } & {Number of times recycled } \\ - \hline -{InitialWrite } & {datetime } & {When Volume first written } \\ - \hline -{ScratchPoolId } & {integer } & {Id of Scratch Pool } \\ - \hline -{RecyclePoolId } & {integer } & {Pool ID where to recycle Volume } \\ - \hline -{Comment } & {blob } & {User text field } \\ - \hline - - -\end{longtable} - -The {\bf Volume} table (internally referred to as the Media table) contains + + + + +%\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 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} -\begin{longtable}{|l|l|p{2.4in}|} - \hline -\multicolumn{3}{|l| }{\bf Pool } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{PoolId } & {integer } & {Primary Key } \\ - \hline -{Name } & {Tinyblob } & {Pool Name } \\ - \hline -{NumVols } & {Integer } & {Number of Volumes in the Pool } \\ - \hline -{MaxVols } & {Integer } & {Maximum Volumes in the Pool } \\ - \hline -{UseOnce } & {tinyint } & {Use volume once } \\ - \hline -{UseCatalog } & {tinyint } & {Set to use catalog } \\ - \hline -{AcceptAnyVolume } & {tinyint } & {Accept any volume from Pool } \\ - \hline -{VolRetention } & {bigint } & {64 bit seconds to retain volume } \\ - \hline -{VolUseDuration } & {bigint } & {64 bit seconds volume can be used } \\ - \hline -{MaxVolJobs } & {integer } & {max jobs on volume } \\ - \hline -{MaxVolFiles } & {integer } & {max EOF marks to put on Volume } \\ - \hline -{MaxVolBytes } & {bigint } & {max bytes to write on Volume } \\ - \hline -{AutoPrune } & {tinyint } & {yes|no for autopruning } \\ - \hline -{Recycle } & {tinyint } & {yes|no for allowing auto recycling of Volume } \\ - \hline -{ActionOnPurge } & {tinyint } & {Default Volume ActionOnPurge } \\ - \hline -{PoolType } & {enum } & {Backup, Copy, Cloned, Archive, Migration } \\ - \hline -{LabelType } & {tinyint } & {Type of label ANSI/Bacula } \\ - \hline -{LabelFormat } & {Tinyblob } & {Label format } -\\ \hline -{Enabled } {tinyint } & {Whether or not Volume can be written } \\ - \hline -{ScratchPoolId } & {integer } & {Id of Scratch Pool } \\ - \hline -{RecyclePoolId } & {integer } & {Pool ID where to recycle Volume } \\ - \hline -{NextPoolId } & {integer } & {Pool ID of next Pool } \\ - \hline -{MigrationHighBytes } & {bigint } & {High water mark for migration } \\ - \hline -{MigrationLowBytes } & {bigint } & {Low water mark for migration } \\ - \hline -{MigrationTime } & {bigint } & {Time before migration } \\ - \hline - - - -\end{longtable} - -The {\bf Pool} table contains one entry for each media pool controlled by +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 Bacula in this database. One media record exists for each of the NumVols contained in the Pool. The PoolType is a Bacula defined keyword. The MediaType is defined by the administrator, and corresponds to the MediaType specified in 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} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Client } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{ClientId } & {integer } & {Primary Key } \\ - \hline -{Name } & {TinyBlob } & {File Services Name } \\ - \hline -{UName } & {TinyBlob } & {uname -a from Client (not yet used) } \\ - \hline -{AutoPrune } & {tinyint } & {yes|no for autopruning } \\ - \hline -{FileRetention } & {bigint } & {64 bit seconds to retain Files } \\ - \hline -{JobRetention } & {bigint } & {64 bit seconds to retain Job } -\\ \hline - -\end{longtable} - -The {\bf Client} table 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} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Storage } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{StorageId } & {integer } & {Unique Id } \\ - \hline -{Name } & {tinyblob } & {Resource name of Storage device } \\ - \hline -{AutoChanger } & {tinyint } & {Set if it is an autochanger } \\ - \hline - -\end{longtable} - -The {\bf Storage} table contains one entry for each Storage used. - - -\addcontentsline{lot}{table}{Counter Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Counter } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{Counter } & {tinyblob } & {Counter name } \\ - \hline -{MinValue } & {integer } & {Start/Min value for counter } \\ - \hline -{MaxValue } & {integer } & {Max value for counter } \\ - \hline -{CurrentValue } & {integer } & {Current counter value } \\ - \hline -{WrapCounter } & {tinyblob } & {Name of another counter } -\\ \hline - -\end{longtable} - -The {\bf Counter} table contains one entry for each permanent counter defined -by the user. - -\addcontentsline{lot}{table}{Job History Table Layout} -\begin{longtable}{|l|l|p{2.5in}|} - \hline -\multicolumn{3}{|l| }{\bf JobHisto } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{JobId } & {integer } & {Primary Key } \\ - \hline -{Job } & {tinyblob } & {Unique Job Name } \\ - \hline -{Name } & {tinyblob } & {Job Name } \\ - \hline -{Type } & {binary(1) } & {Job Type: Backup, Copy, Clone, Archive, Migration -} \\ - \hline -{Level } & {binary(1) } & {Job Level } \\ - \hline -{ClientId } & {integer } & {Client index } \\ - \hline -{JobStatus } & {binary(1) } & {Job Termination Status } \\ - \hline -{SchedTime } & {datetime } & {Time/date when Job scheduled } \\ - \hline -{StartTime } & {datetime } & {Time/date when Job started } \\ - \hline -{EndTime } & {datetime } & {Time/date when Job ended } \\ - \hline -{RealEndTime } & {datetime } & {Time/date when original Job ended } \\ - \hline -{JobTDate } & {bigint } & {Start day in Unix format but 64 bits; used for -Retention period. } \\ - \hline -{VolSessionId } & {integer } & {Unique Volume Session ID } \\ - \hline -{VolSessionTime } & {integer } & {Unique Volume Session Time } \\ - \hline -{JobFiles } & {integer } & {Number of files saved in Job } \\ - \hline -{JobBytes } & {bigint } & {Number of bytes saved in Job } \\ - \hline -{JobErrors } & {integer } & {Number of errors during Job } \\ - \hline -{JobMissingFiles } & {integer } & {Number of files not saved (not yet used) } -\\ - \hline -{PoolId } & {integer } & {Link to Pool Record } \\ - \hline -{FileSetId } & {integer } & {Link to FileSet Record } \\ - \hline -{PrioJobId } & {integer } & {Link to prior Job Record when migrated } \\ - \hline -{PurgedFiles } & {tiny integer } & {Set when all File records purged } \\ - \hline -{HasBase } & {tiny integer } & {Set when Base Job run } -\\ \hline - -\end{longtable} - -The {bf JobHisto} table is the same as the Job table, but it keeps +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} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Version } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{LogIdId } & {integer } & {Primary Key } -\\ \hline -{JobId } & {integer } & {Points to Job record } -\\ \hline -{Time } & {datetime } & {Time/date log record created } -\\ \hline -{LogText } & {blob } & {Log text } -\\ \hline - -\end{longtable} - -The {\bf Log} table contains a log of all Job output. - -\addcontentsline{lot}{table}{Location Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Location } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{LocationId } & {integer } & {Primary Key } -\\ \hline -{Location } & {tinyblob } & {Text defining location } -\\ \hline -{Cost } & {integer } & {Relative cost of obtaining Volume } -\\ \hline -{Enabled } & {tinyint } & {Whether or not Volume is enabled } -\\ \hline - -\end{longtable} - -The {\bf Location} table defines where a Volume is physically. - - -\addcontentsline{lot}{table}{Location Log Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf LocationLog } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{locLogIdId } & {integer } & {Primary Key } -\\ \hline -{Date } & {datetime } & {Time/date log record created } -\\ \hline -{MediaId } & {integer } & {Points to Media record } -\\ \hline -{LocationId } & {integer } & {Points to Location record } -\\ \hline -{NewVolStatus } & {integer } & {enum: Full, Archive, Append, Recycle, Purged - Read-only, Disabled, Error, Busy, Used, Cleaning } -\\ \hline -{Enabled } & {tinyint } & {Whether or not Volume is enabled } -\\ \hline - - -\end{longtable} - -The {\bf Log} table contains a log of all Job output. - - -\addcontentsline{lot}{table}{Version Table Layout} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf Version } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{VersionId } & {integer } & {Primary Key } -\\ \hline - -\end{longtable} - -The {\bf Version} table defines the Bacula database version number. Bacula +%\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 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} -\begin{longtable}{|l|l|l|} - \hline -\multicolumn{3}{|l| }{\bf BaseFiles } \\ - \hline -\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type -} & \multicolumn{1}{c| }{\bf Remark } \\ - \hline -{BaseId } & {integer } & {Primary Key } \\ - \hline -{BaseJobId } & {integer } & {JobId of Base Job } \\ - \hline -{JobId } & {integer } & {Reference to Job } \\ - \hline -{FileId } & {integer } & {Reference to File } \\ - \hline -{FileIndex } & {integer } & {File Index number } -\\ \hline - -\end{longtable} - -The {\bf BaseFiles} table contains all the File references for a particular +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 JobId that point to a Base file -- i.e. they were previously saved and hence were not saved in the current JobId but in BaseJobId under FileId. FileIndex is the index of the file, and is used for optimization of Restore jobs to prevent the need to read the FileId record when creating the in memory tree. -This record is not yet implemented. +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: +The commands used to create the MySQL tables are as follows: \footnotesize -\begin{verbatim} +\begin{lstlisting} USE bacula; CREATE TABLE Filename ( FilenameId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, @@ -1144,5 +547,5 @@ CREATE TABLE Counters ( WrapCounter TINYBLOB NOT NULL, PRIMARY KEY (Counter(128)) ); -\end{verbatim} +\end{lstlisting} \normalsize diff --git a/docs/manuals/en/developers/daemonprotocol.tex b/docs/manuals/en/developers/daemonprotocol.tex index 0354bbd5..93feb295 100644 --- a/docs/manuals/en/developers/daemonprotocol.tex +++ b/docs/manuals/en/developers/daemonprotocol.tex @@ -50,7 +50,7 @@ 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). -\begin{itemize} +\begin{bsysitemize} \item Commands are always ASCII commands that are upper/lower case dependent as well as space sensitive. \item All binary data is converted into ASCII (either with printf statements @@ -82,7 +82,7 @@ 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. -\end{itemize} +\end{bsysitemize} \section{The Protocol Used Between the Director and the Storage Daemon} \index{Daemon!Protocol Used Between the Director and the Storage } @@ -101,7 +101,7 @@ this process is complete, the Storage daemon is not available for use by File daemons. \footnotesize -\begin{verbatim} +\begin{lstlisting} SD: listens DR: makes connection DR: Hello calling @@ -112,7 +112,7 @@ SD: 3000 OK Job Authorization= DR: use device= media_type= pool_name= pool_type= SD: 3000 OK use device -\end{verbatim} +\end{lstlisting} \normalsize For the Director to be authorized, the \lt{}Director-name\gt{} and the @@ -129,7 +129,7 @@ File Daemon} A typical conversation might look like the following: \footnotesize -\begin{verbatim} +\begin{lstlisting} FD: listens DR: makes connection DR: Hello calling @@ -168,7 +168,7 @@ FD: ... additional Volume / Volume data pairs for volumes 2 .. n FD: Null packet FD: close socket -\end{verbatim} +\end{lstlisting} \normalsize \section{The Save Protocol Between the File Daemon and the Storage Daemon} @@ -193,14 +193,14 @@ Command and control information is exchanged in human readable ASCII commands. \footnotesize -\begin{verbatim} +\begin{lstlisting} FD: listens SD: makes connection FD: append open session = [] SD: 3000 OK ticket = FD: append data SD: 3000 OK data address = port = -\end{verbatim} +\end{lstlisting} \normalsize \subsection{Data Information} @@ -251,7 +251,7 @@ reply to the File daemon. Thus an actual conversation might contain the following exchanges: \footnotesize -\begin{verbatim} +\begin{lstlisting} FD: <1 1 0> (header packet) FD: FD: Null packet @@ -277,7 +277,7 @@ SD: 3002 Volume data = SD: ... additional Volume / Volume data pairs for volumes 2 .. n FD: close socket -\end{verbatim} +\end{lstlisting} \normalsize The information returned to the File daemon by the Storage daemon in response diff --git a/docs/manuals/en/developers/developers.tex b/docs/manuals/en/developers/developers.tex index 902fa8c8..38c5e686 100644 --- a/docs/manuals/en/developers/developers.tex +++ b/docs/manuals/en/developers/developers.tex @@ -5,17 +5,30 @@ %% %% # $ % & ~ _ ^ \ { } %% +\documentclass[10pt,bsyspaper,english,logo,titlepage]{bsysmanual} -\documentclass[10pt,a4paper]{book} +\renewcommand{\familydefault}{\sfdefault} +\usepackage[utf8]{inputenc} +\usepackage[toc,title,header,page]{appendix} +\usepackage[T1]{fontenc} +\usepackage{longtable,graphicx,fancyhdr,lastpage,eurosym,dcolumn,ltxtable} +\usepackage{textcomp,varioref,lscape,pdfpages,ifthen,setspace,colortbl,diagbox} +\usepackage{lmodern,minitoc} +\usepackage{MnSymbol} +\usepackage{bbding,multirow} +\usepackage[hyphens]{url} +\usepackage[plainpages=true,bookmarks=false,bookmarksopen=false,filecolor=black,linkcolor=black,urlcolor=bsysredtwo,filebordercolor={0. 0. 0.},menubordercolor={0. 0. 0.},urlbordercolor={0. 0. 0.},linkbordercolor={0. 0. 0.},hyperindex=false,colorlinks=true]{hyperref} +\usepackage{babel,xr,xr-hyper} +\usepackage[font={sf,bf},textfont=md]{caption} +\usepackage[printonlyused]{acronym} +\setlength\arrayrulewidth{0.4pt} +\include{bsyscommondefs} +\usepackage[left=4cm,right=3cm,bottom=2cm,top=2.5cm]{geometry} +\usepackage{moreverb,fancyvrb} +\usepackage{listings} +\input{external-references} +\pdfminorversion=4 -\topmargin -0.5in -\oddsidemargin 0.0in -\evensidemargin 0.0in -\textheight 10in -\textwidth 6.5in - - -\usepackage{html} \usepackage{float} \usepackage{graphicx} \usepackage{bacula} @@ -23,8 +36,6 @@ \usepackage{makeidx} \usepackage{index} \usepackage{setspace} -\usepackage{hyperref} -% \usepackage[linkcolor=black,colorlinks=true]{hyperref} \usepackage{url} \makeindex @@ -35,20 +46,20 @@ \newindex{general}{idx}{ind}{General Index} \sloppy - +\def\bsystitle{Developer's Guide} \begin{document} +\lstset{escapechar=,breaklines=true,basicstyle=\ttfamily\scriptsize,backgroundcolor=\color{lightbsysgrey}} \sloppy -\include{coverpage} - -\clearpage -\pagenumbering{roman} +\input{coverpage} +\frontmatter \tableofcontents -\clearpage +\listoftables +\listoffigures -\pagestyle{myheadings} -\markboth{Bacula Version \version}{Bacula Version \version} -\pagenumbering{arabic} +\mainmatter +%\markboth{Bacula Version \version}{Bacula Version \version} +%\pagenumbering{arabic} \include{generaldevel} \include{git} \include{pluginAPI} @@ -67,14 +78,17 @@ \include{mempool} \include{netprotocol} \include{smartall} -\include{fdl} % The following line tells link_resolver.pl to not include these files: % nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main % pull in the index -\clearpage +\begin{appendices} +\begin{small} +\include{fdl} +\end{small} +\end{appendices} \printindex \end{document} diff --git a/docs/manuals/en/developers/generaldevel.tex b/docs/manuals/en/developers/generaldevel.tex index b7c5bfea..587ce6bf 100644 --- a/docs/manuals/en/developers/generaldevel.tex +++ b/docs/manuals/en/developers/generaldevel.tex @@ -47,10 +47,10 @@ in the patch. Please be sure to use the Bacula indenting standard (see below) for source code. If you have checked out the source with Git, you can get a diff using. -\begin{verbatim} +\begin{lstlisting} git pull git format-patch -M -\end{verbatim} +\end{lstlisting} If you plan on doing significant development work over a period of time, after having your first patch reviewed and approved, you will be eligible @@ -140,12 +140,12 @@ The instructions for filling out this agreement are also at: It should be filled out, then sent to: -\begin{verbatim} +\begin{lstlisting} Kern Sibbald Cotes-de-Montmoiret 9 1012 Lausanne Switzerland -\end{verbatim} +\end{lstlisting} Please note that the above address is different from the officially registered office mentioned in the document. When you send in such a @@ -240,7 +240,7 @@ hoping that the Bacula community will take more responsibility for assuring the implementation of accepted Feature Requests. Feature Request format: -\begin{verbatim} +\begin{lstlisting} ============= Empty Feature Request form =========== Item n: One line summary ... Date: Date submitted @@ -253,9 +253,9 @@ Item n: One line summary ... Notes: Additional notes or features (omit if not used) ============== End Feature Request form ============== -\end{verbatim} +\end{lstlisting} -\begin{verbatim} +\begin{lstlisting} ============= Example Completed Feature Request form =========== Item 1: Implement a Migration job type that will move the job data from one device to another. @@ -284,7 +284,7 @@ Item 1: Implement a Migration job type that will move the job Highwater size (keep total size) Lowwater mark ================================================= -\end{verbatim} +\end{lstlisting} \section{Bacula Code Submissions and Projects} @@ -293,7 +293,7 @@ Item 1: Implement a Migration job type that will move the job Getting code implemented in Bacula works roughly as follows: -\begin{itemize} +\begin{bsysitemize} \item Kern is the project manager, but prefers not to be a "gate keeper". This means that the developers are expected to be self-motivated, @@ -330,7 +330,7 @@ Getting code implemented in Bacula works roughly as follows: to avoid this, and ensure a continuation of the code and a sharing of the development, debugging, documentation, and maintenance responsibilities. -\end{itemize} +\end{bsysitemize} \section{Patches for Released Versions} \index{Patches for Released Versions} @@ -349,14 +349,14 @@ 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: -\begin{verbatim} +\begin{lstlisting} (edit) 2.2.4-restore.patch (input description) (end edit) git format-patch -M mv 0001-xxx 2.2.4-restore.patch -\end{verbatim} +\end{lstlisting} check to make sure no extra junk got put into the patch file (i.e. it should have the patch for that bug only). @@ -367,7 +367,7 @@ patch to the bug report. Then upload it to the 2.2.x release of bacula-patches. So, end the end, the patch file is: -\begin{itemize} +\begin{bsysitemize} \item Attached to the bug report \item In Branch-2.2/bacula/patches/... @@ -377,7 +377,7 @@ So, end the end, the patch file is: \item Loaded on Source Forge bacula-patches 2.2.x release. When you add it, click on the check box to send an Email so that all the users that are monitoring SF patches get notified. -\end{itemize} +\end{bsysitemize} \section{Developing Bacula} @@ -485,9 +485,9 @@ any files with these names are subject to being rudely deleted at any time. Please identify all incomplete code with a comment that contains -\begin{verbatim} +\begin{lstlisting} ***FIXME*** -\end{verbatim} +\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 @@ -505,7 +505,7 @@ numbers respectively. Once you detar this file, you will have a directory structure as follows: \footnotesize -\begin{verbatim} +\begin{lstlisting} | Tar file: |- depkgs @@ -586,7 +586,7 @@ Project gui: |- bimagemgr (Web application for burning CDROMs) -\end{verbatim} +\end{lstlisting} \normalsize \subsection{Header Files} @@ -642,16 +642,16 @@ so be conservative in your use of C++ features. \index{Do Not Use} \addcontentsline{toc}{subsubsection}{Do Not Use} -\begin{itemize} +\begin{bsysitemize} \item STL -- it is totally incomprehensible. -\end{itemize} +\end{bsysitemize} \subsection{Avoid if Possible} \index{Possible!Avoid if} \index{Avoid if Possible} \addcontentsline{toc}{subsubsection}{Avoid if Possible} -\begin{itemize} +\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 @@ -682,14 +682,14 @@ so be conservative in your use of C++ features. \item Too much inheritance -- it can complicate the code, and make reading it difficult (unless you are in love with colons) -\end{itemize} +\end{bsysitemize} \subsection{Do Use Whenever Possible} \index{Possible!Do Use Whenever} \index{Do Use Whenever Possible} \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible} -\begin{itemize} +\begin{bsysitemize} \item Locking and unlocking within a single subroutine. \item A single point of exit from all subroutines. A goto is @@ -704,9 +704,9 @@ so be conservative in your use of C++ features. \item When committing a fix for a bug, make the comment of the following form: -\begin{verbatim} +\begin{lstlisting} Reason for bug fix or other message. Fixes bug #1234 -\end{verbatim} +\end{lstlisting} It is important to write the {\bf bug \#1234} like that because our program that automatically pulls messages @@ -717,7 +717,7 @@ the number of the bug you actually fixed. Providing the commit comment line has one of the following keywords (or phrases), it will be ignored: -\begin{verbatim} +\begin{lstlisting} tweak typo cleanup @@ -738,13 +738,13 @@ keywords (or phrases), it will be ignored: update todo update notes update changelog -\end{verbatim} +\end{lstlisting} \item Use the following keywords at the beginning of a git commit message -\end{itemize} +\end{bsysitemize} \subsection{Indenting Standards} \index{Standards!Indenting} @@ -761,11 +761,11 @@ The closest set of parameters for the Linux {\bf indent} program that will produce reasonably indented code are: \footnotesize -\begin{verbatim} +\begin{lstlisting} -nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0 -cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs -nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda -\end{verbatim} +\end{lstlisting} \normalsize You can put the above in your .indent.pro file, and then just invoke indent on @@ -777,17 +777,17 @@ 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. \footnotesize -\begin{verbatim} +\begin{lstlisting} if (abc) { some_code; } -\end{verbatim} +\end{lstlisting} \normalsize Just follow the convention in the code. For example we I prefer non-indented cases. \footnotesize -\begin{verbatim} +\begin{lstlisting} switch (code) { case 'A': do something @@ -798,7 +798,7 @@ Just follow the convention in the code. For example we I prefer non-indented cas default: break; } -\end{verbatim} +\end{lstlisting} \normalsize Avoid using // style comments except for temporary code or turning off debug @@ -823,33 +823,33 @@ in {\bf protos.h} in each directory. Always put space around assignment and comparison operators. \footnotesize -\begin{verbatim} +\begin{lstlisting} a = 1; if (b >= 2) { cleanup(); } -\end{verbatim} +\end{lstlisting} \normalsize but your can compress things in a {\bf for} statement: \footnotesize -\begin{verbatim} +\begin{lstlisting} for (i=0; i < del.num_ids; i++) { ... -\end{verbatim} +\end{lstlisting} \normalsize Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a print statement, e.g.: \footnotesize -\begin{verbatim} +\begin{lstlisting} if (ua->verbose \&& del.num_del != 0) { bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del, del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName); } -\end{verbatim} +\end{lstlisting} \normalsize Leave a certain amount of debug code (Dmsg) in code you submit, so that future @@ -883,26 +883,26 @@ characters) with indenting (visual alignment of the code). Please don't use: \footnotesize -\begin{verbatim} +\begin{lstlisting} strcpy() strcat() strncpy() strncat(); sprintf() snprintf() -\end{verbatim} +\end{lstlisting} \normalsize They are system dependent and un-safe. These should be replaced by the Bacula safe equivalents: \footnotesize -\begin{verbatim} +\begin{lstlisting} char *bstrncpy(char *dest, char *source, int dest_size); char *bstrncat(char *dest, char *source, int dest_size); int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...); int bvsnprintf(char *str, int32_t size, const char *format, va_list ap); -\end{verbatim} +\end{lstlisting} \normalsize See src/lib/bsys.c for more details on these routines. @@ -912,12 +912,12 @@ Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit edit\_uint64()}. For example: \footnotesize -\begin{verbatim} +\begin{lstlisting} char buf[100]; uint64_t num = something; char ed1[50]; bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1)); -\end{verbatim} +\end{lstlisting} \normalsize Note: {\bf \%lld} is now permitted in Bacula code -- we have our @@ -1022,9 +1022,9 @@ Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command: Job messages are messages that pertain to a particular job such as a file that could not be saved, or the number of files and bytes that were saved. They Are coded as: -\begin{verbatim} +\begin{lstlisting} Jmsg(jcr, M\_FATAL, 0, "Text of message"); -\end{verbatim} +\end{lstlisting} A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can have any number of arguments for substituted in a printf like format. Output from the Jmsg() will go to the Job report. diff --git a/docs/manuals/en/developers/git.tex b/docs/manuals/en/developers/git.tex index 2a0f992f..e97f736d 100644 --- a/docs/manuals/en/developers/git.tex +++ b/docs/manuals/en/developers/git.tex @@ -55,9 +55,9 @@ project. You can get a full copy of the Source Forge Bacula Git repository with the following command: -\begin{verbatim} +\begin{lstlisting} git clone http://git.bacula.org/bacula trunk -\end{verbatim} +\end{lstlisting} This will put a read-only copy into the directory {\bf trunk} in your current directory, and {\bf trunk} will contain @@ -69,10 +69,10 @@ git repository. The above command needs to be done only once. Thereafter, you can: -\begin{verbatim} +\begin{lstlisting} cd trunk git pull # refresh my repo with the latest code -\end{verbatim} +\end{lstlisting} As of August 2009, the size of the repository ({\bf trunk} in the above example) will be approximately 55 Megabytes. However, if you build @@ -85,7 +85,7 @@ If you want to learn more about Git, we recommend that you visit:\\ \elink{http://book.git-scm.com/}{http://book.git-scm.com/}. Some of the differences between Git and SVN are: -\begin{itemize} +\begin{bsysitemize} \item Your main Git directory is a full Git repository to which you can and must commit. In fact, we suggest you commit frequently. \item When you commit, the commit goes into your local Git @@ -127,12 +127,12 @@ Some of the differences between Git and SVN are: apply to an older version of the repository you will probably get an error message such as: -\begin{verbatim} +\begin{lstlisting} git push To git@github.com:bacula/bacula.git ! [rejected] master -> master (non-fast forward) error: failed to push some refs to 'git@github.com:bacula/bacula.git' -\end{verbatim} +\end{lstlisting} which is Git's way of telling you that the main repository has changed and that if you push your changes, they will not be integrated properly. @@ -146,47 +146,47 @@ Some of the differences between Git and SVN are: will tell you and you must do conflict resolution, which is much easier in Git than in SVN. \item Resolving conflicts is described below in the {\bf github} section. -\end{itemize} +\end{bsysitemize} \section{Step by Step Modifying Bacula Code} Suppose you want to download Bacula source code, build it, make a change, then submit your change to the Bacula developers. What would you do? -\begin{itemize} +\begin{bsysitemize} \item Tell git who you are:\\ -\begin{verbatim} +\begin{lstlisting} git config --global user.name "First-name Last-name" git config --global user.email "email@address.com" -\end{verbatim} +\end{lstlisting} Where you put your real name and your email address. Since this is global, you only need to do it once on any given machine regardless of how many git repos you work with. \item Download the Source code:\\ -\begin{verbatim} +\begin{lstlisting} git clone http://git.bacula.org/bacula trunk -\end{verbatim} +\end{lstlisting} \item Configure and Build Bacula:\\ -\begin{verbatim} +\begin{lstlisting} ./configure (all-your-normal-options) make -\end{verbatim} +\end{lstlisting} \item Create a branch to work on: -\begin{verbatim} +\begin{lstlisting} cd trunk/bacula git checkout -b bugfix master -\end{verbatim} +\end{lstlisting} \item Edit, build, Test, ...\\ -\begin{verbatim} +\begin{lstlisting} edit file jcr.h make test -\end{verbatim} +\end{lstlisting} Note: if you forget to create a working branch prior to making changes, and you make them on master, this is no problem providing @@ -194,48 +194,48 @@ that you create the working branch before your first commit. So assuming that you have edited master instead of your bugfix branch, you can simply: -\begin{verbatim} +\begin{lstlisting} git checkout -b bugfix master -\end{verbatim} +\end{lstlisting} and a new bugfix branch will be created and checked out. You can then proceed to committing to your bugfix branch as described in the next step. \item commit your work: -\begin{verbatim} +\begin{lstlisting} git commit -am "Short comment on what I did" -\end{verbatim} +\end{lstlisting} \item Possibly repeat the above two items \item Switch back to the master branch:\\ -\begin{verbatim} +\begin{lstlisting} git checkout master -\end{verbatim} +\end{lstlisting} \item Pull the latest changes:\\ -\begin{verbatim} +\begin{lstlisting} git pull -\end{verbatim} +\end{lstlisting} \item Get back on your bugfix branch:\\ -\begin{verbatim} +\begin{lstlisting} git checkout bugfix -\end{verbatim} +\end{lstlisting} \item Merge your changes and correct any conflicts:\\ -\begin{verbatim} +\begin{lstlisting} git rebase master bugfix -\end{verbatim} +\end{lstlisting} \item Fix any conflicts:\\ You will be notified if there are conflicts. The first thing to do is: -\begin{verbatim} +\begin{lstlisting} git diff -\end{verbatim} +\end{lstlisting} This will produce a diff of only the files having a conflict. Fix each file in turn. When it is fixed, the diff for that file @@ -243,36 +243,36 @@ will go away. For each file fixed, you must do the same as SVN, inform git with: -\begin{verbatim} +\begin{lstlisting} git add (name-of-file-no-longer-in-conflict) -\end{verbatim} +\end{lstlisting} \item When all files are fixed do: -\begin{verbatim} +\begin{lstlisting} git rebase --continue -\end{verbatim} +\end{lstlisting} \item If you find that it is impossible to reconcile the two branches or you made a mistake in correcting and adding files, before you enter the: -\begin{verbatim} +\begin{lstlisting} git rebase --continue -\end{verbatim} +\end{lstlisting} you can instead enter: -\begin{verbatim} +\begin{lstlisting} git rebase --abort -\end{verbatim} +\end{lstlisting} which will essentially cancel the the original git rebase and reset everything to the beginning with no changes to your bugfix branch. \item When you have completed the rebase and are ready to send a patch, do the following:\\ -\begin{verbatim} +\begin{lstlisting} git checkout bugfix git format-patch -M master -\end{verbatim} +\end{lstlisting} Look at the files produced. They should be numbered 0001-xxx.patch where there is one file for each commit you did, number sequentially, and the xxx is what you put in the commit comment. @@ -291,7 +291,7 @@ git format-patch -M master to the developers. -\end{itemize} +\end{bsysitemize} @@ -303,7 +303,7 @@ create format-patch patches or push it to the Source Forge repo. Assuming you call the Bacula repository {\bf trunk}, you might use the following commands: -\begin{verbatim} +\begin{lstlisting} cd trunk git checkout master git pull @@ -312,16 +312,16 @@ git checkout -b newbranch master git add git commit -m "" ... -\end{verbatim} +\end{lstlisting} When you have completed working on your branch, you will do: -\begin{verbatim} +\begin{lstlisting} cd trunk git checkout newbranch # ensure I am on my branch git pull # get latest source code git rebase master # merge my code -\end{verbatim} +\end{lstlisting} If you have completed your edits before anyone has modified the repository, the {\bf git rebase master} will report that there was nothing to do. Otherwise, @@ -329,20 +329,20 @@ it will merge the changes that were made in the repository before your changes. If there are any conflicts, Git will tell you. Typically resolving conflicts with Git is relatively easy. You simply make a diff: -\begin{verbatim} +\begin{lstlisting} git diff -\end{verbatim} +\end{lstlisting} Then edit each file that was listed in the {\bf git diff} to remove the conflict, which will be indicated by lines of: -\begin{verbatim} +\begin{lstlisting} <<<<<<< HEAD text >>>>>>>> other text ===== -\end{verbatim} +\end{lstlisting} where {\bf text} is what is in the Bacula repository, and {\bf other text} is what you have changed. @@ -350,44 +350,44 @@ is what you have changed. Once you have eliminated the conflict, the {\bf git diff} will show nothing, and you must do a: -\begin{verbatim} +\begin{lstlisting} git add -\end{verbatim} +\end{lstlisting} Once you have fixed all the files with conflicts in the above manner, you enter: -\begin{verbatim} +\begin{lstlisting} git rebase --continue -\end{verbatim} +\end{lstlisting} and your rebase will be complete. If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter: -\begin{verbatim} +\begin{lstlisting} git rebase --abort -\end{verbatim} +\end{lstlisting} Finally to make a set of patch files -\begin{verbatim} +\begin{lstlisting} git format-patch -M master -\end{verbatim} +\end{lstlisting} When you see your changes have been integrated and pushed to the main repo, you can delete your branch with: -\begin{verbatim} +\begin{lstlisting} git checkout master git branch -D newbranch -\end{verbatim} +\end{lstlisting} \section{Forcing Changes} If you want to understand why it is not a good idea to force a push to the repository, look at the following picture: -\includegraphics[width=0.85\textwidth]{\idir git-edit-commit.eps} +\bsysimageH{git-edit-commit}{Git Edit Commit}{} The above graphic has three lines of circles. Each circle represents a commit, and time runs from the left to the right. The top line diff --git a/docs/manuals/en/developers/gui-interface.tex b/docs/manuals/en/developers/gui-interface.tex index 9bb2a135..e3a86524 100644 --- a/docs/manuals/en/developers/gui-interface.tex +++ b/docs/manuals/en/developers/gui-interface.tex @@ -37,7 +37,7 @@ 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: -\begin{itemize} +\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. @@ -51,7 +51,7 @@ 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} -\end{itemize} +\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 @@ -59,7 +59,7 @@ easier to use the Bacula subroutines. The following code is used by the Console program to begin a conversation. \footnotesize -\begin{verbatim} +\begin{lstlisting} static BSOCK *UA_sock = NULL; static JCR *jcr; ... @@ -82,18 +82,18 @@ static JCR *jcr; bnet_close(UA_sock); } exit 0; -\end{verbatim} +\end{lstlisting} \normalsize Then the read\_and\_process\_input routine looks like the following: \footnotesize -\begin{verbatim} +\begin{lstlisting} get-input-to-send-to-the-Director; bnet_fsend(UA_sock, "%s", input); stat = bnet_recv(UA_sock); process-output-from-the-Director; -\end{verbatim} +\end{lstlisting} \normalsize For a GUI program things will be a bit more complicated. Basically in the very @@ -111,12 +111,13 @@ To help developers of restore GUI interfaces, we have added new \textsl{dot Bat has now a bRestore panel that uses Bvfs to display files and directories. -\begin{figure}[htbp] - \centering - \includegraphics[width=12cm]{\idir bat-brestore} - \label{fig:batbrestore} - \caption{Bat Brestore Panel} -\end{figure} +\bsysimageH{bat-brestore}{Bat Brestore Panel}{fig:batbrestore} +%% \begin{figure}[htbp] +%% \centering +%% \includegraphics[width=12cm]{\idir bat-brestore} +%% \label{fig:batbrestore} +%% \caption{Bat Brestore Panel} +%% \end{figure} The Bvfs module works correctly with BaseJobs, Copy and Migration jobs. @@ -125,7 +126,7 @@ This project was funded by Bacula Systems. \subsection*{General notes} -\begin{itemize} +\begin{bsysitemize} \item All fields are separated by a tab \item You can specify \texttt{limit=} and \texttt{offset=} to list smoothly records in very big directories @@ -138,7 +139,7 @@ This project was funded by Bacula Systems. \item All fields are separated by a tab \item Due to potential encoding problem, it's advised to allways use pathid in queries. -\end{itemize} +\end{bsysitemize} \subsection*{Get dependent jobs from a given JobId} @@ -148,16 +149,16 @@ can combine all Jobs and all FileSet for a Client in a single session. To get all JobId needed to restore a particular job, you can use the \texttt{.bvfs\_get\_jobids} command. -\begin{verbatim} +\begin{lstlisting} .bvfs_get_jobids jobid=num [all] -\end{verbatim} +\end{lstlisting} -\begin{verbatim} +\begin{lstlisting} .bvfs_get_jobids jobid=10 1,2,5,10 .bvfs_get_jobids jobid=10 all 1,2,3,5,10 -\end{verbatim} +\end{lstlisting} In this example, a normal restore will need to use JobIds 1,2,5,10 to compute a complete restore of the system. @@ -170,14 +171,14 @@ this client. The \texttt{.bvfs\_update} command computes the directory cache for jobs specified in argument, or for all jobs if unspecified. -\begin{verbatim} +\begin{lstlisting} .bvfs_update [jobid=numlist] -\end{verbatim} +\end{lstlisting} Example: -\begin{verbatim} +\begin{lstlisting} .bvfs_update jobid=1,2,3 -\end{verbatim} +\end{lstlisting} You can run the cache update process in a RunScript after the catalog backup. @@ -188,92 +189,92 @@ the \texttt{.bvfs\_version} command. To avoid problems with encoding, this function uses only PathId and FilenameId. The jobid argument is mandatory but unused. -\begin{verbatim} +\begin{lstlisting} .bvfs_versions client=filedaemon pathid=num filenameid=num jobid=1 PathId FilenameId FileId JobId LStat Md5 VolName Inchanger PathId FilenameId FileId JobId LStat Md5 VolName Inchanger ... -\end{verbatim} +\end{lstlisting} Example: -\begin{verbatim} +\begin{lstlisting} .bvfs_versions client=localhost-fd pathid=1 fnid=47 jobid=1 1 47 52 12 gD HRid IGk D Po Po A P BAA I A /uPgWaxMgKZlnMti7LChyA Vol1 1 -\end{verbatim} +\end{lstlisting} \subsection*{List directories} Bvfs allows you to list directories in a specific path. -\begin{verbatim} +\begin{lstlisting} .bvfs_lsdirs pathid=num path=/apath jobid=numlist limit=num offset=num PathId FilenameId FileId JobId LStat Path PathId FilenameId FileId JobId LStat Path PathId FilenameId FileId JobId LStat Path ... -\end{verbatim} +\end{lstlisting} You need to \texttt{pathid} or \texttt{path}. Using \texttt{path=""} will list ``/'' on Unix and all drives on Windows. If FilenameId is 0, the record listed is a directory. -\begin{verbatim} +\begin{lstlisting} .bvfs_lsdirs pathid=4 jobid=1,11,12 4 0 0 0 A A A A A A A A A A A A A A . 5 0 0 0 A A A A A A A A A A A A A A .. 3 0 0 0 A A A A A A A A A A A A A A regress/ -\end{verbatim} +\end{lstlisting} In this example, to list directories present in \texttt{regress/}, you can use -\begin{verbatim} +\begin{lstlisting} .bvfs_lsdirs pathid=3 jobid=1,11,12 3 0 0 0 A A A A A A A A A A A A A A . 4 0 0 0 A A A A A A A A A A A A A A .. 2 0 0 0 A A A A A A A A A A A A A A tmp/ -\end{verbatim} +\end{lstlisting} \subsection*{List files} Bvfs allows you to list files in a specific path. -\begin{verbatim} +\begin{lstlisting} .bvfs_lsfiles pathid=num path=/apath jobid=numlist limit=num offset=num PathId FilenameId FileId JobId LStat Path PathId FilenameId FileId JobId LStat Path PathId FilenameId FileId JobId LStat Path ... -\end{verbatim} +\end{lstlisting} You need to \texttt{pathid} or \texttt{path}. Using \texttt{path=""} will list ``/'' on Unix and all drives on Windows. If FilenameId is 0, the record listed is a directory. -\begin{verbatim} +\begin{lstlisting} .bvfs_lsfiles pathid=4 jobid=1,11,12 4 0 0 0 A A A A A A A A A A A A A A . 5 0 0 0 A A A A A A A A A A A A A A .. 1 0 0 0 A A A A A A A A A A A A A A regress/ -\end{verbatim} +\end{lstlisting} In this example, to list files present in \texttt{regress/}, you can use -\begin{verbatim} +\begin{lstlisting} .bvfs_lsfiles pathid=1 jobid=1,11,12 1 47 52 12 gD HRid IGk BAA I BMqcPH BMqcPE BMqe+t A titi 1 49 53 12 gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B toto 1 48 54 12 gD HRie IGk BAA I BMqcPH BMqcPE BMqe+3 A tutu 1 45 55 12 gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B ficheriro1.txt 1 46 56 12 gD HRie IGk BAA I BMqe/K BMqcPE BMqe+3 D ficheriro2.txt -\end{verbatim} +\end{lstlisting} \subsection*{Restore set of files} Bvfs allows you to create a SQL table that contains files that you want to restore. This table can be provided to a restore command with the file option. -\begin{verbatim} +\begin{lstlisting} .bvfs_restore fileid=numlist dirid=numlist hardlink=numlist path=b2num OK restore file=?b2num ... -\end{verbatim} +\end{lstlisting} To include a directory (with \texttt{dirid}), Bvfs needs to run a query to select all files. This query could be time consuming. @@ -288,25 +289,25 @@ b2 and followed by digits). Example: -\begin{verbatim} +\begin{lstlisting} .bvfs_restore fileid=1,2,3,4 hardlink=10,15,10,20 jobid=10 path=b20001 OK -\end{verbatim} +\end{lstlisting} \subsection*{Cleanup after Restore} To drop the table used by the restore command, you can use the \texttt{.bvfs\_cleanup} command. -\begin{verbatim} +\begin{lstlisting} .bvfs_cleanup path=b20001 -\end{verbatim} +\end{lstlisting} \subsection*{Clearing the BVFS Cache} To clear the BVFS cache, you can use the \texttt{.bvfs\_clear\_cache} command. -\begin{verbatim} +\begin{lstlisting} .bvfs_clear_cache yes OK -\end{verbatim} +\end{lstlisting} diff --git a/docs/manuals/en/developers/mediaformat.tex b/docs/manuals/en/developers/mediaformat.tex index cc824f78..27611c47 100644 --- a/docs/manuals/en/developers/mediaformat.tex +++ b/docs/manuals/en/developers/mediaformat.tex @@ -5,25 +5,22 @@ \label{_ChapterStart9} \index{Format!Storage Media Output} \index{Storage Media Output Format} -\addcontentsline{toc}{section}{Storage Media Output Format} \section{General} \index{General} -\addcontentsline{toc}{subsection}{General} This document describes the media format written by the Storage daemon. The Storage daemon reads and writes in units of blocks. Blocks contain records. Each block has a block header followed by records, and each record has a -record header followed by record data. +record header followed by record data. This chapter is intended to be a technical discussion of the Media Format 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{Definitions} \index{Definitions} -\addcontentsline{toc}{subsection}{Definitions} \begin{description} @@ -31,7 +28,7 @@ Bacula}. \index{Block} A block represents the primitive unit of information that the Storage daemon reads and writes to a physical device. Normally, for a tape device, it will -be the same as a tape block. The Storage daemon always reads and writes +be the same as a tape block. The Storage daemon always reads and writes blocks. A block consists of block header information followed by records. Clients of the Storage daemon (the File daemon) normally never see blocks. However, some of the Storage tools (bls, bscan, bextract, ...) may be use @@ -40,40 +37,40 @@ contain records (see record definition below) from multiple jobs. However, all blocks currently written by Bacula are block level BB02, and a given block contains records for only a single job. Different jobs simply have their own private blocks that are intermingled with the other blocks from -other jobs on the Volume (previously the records were intermingled within +other jobs on the Volume (previously the records were intermingled within the blocks). Having only records from a single job in any give block permitted moving the VolumeSessionId and VolumeSessionTime (see below) from each record heading to the Block header. This has two advantages: 1. a block can be quickly rejected based on the contents of the header without reading all the records. 2. because there is on the average more than one record per -block, less data is written to the Volume for each job. +block, less data is written to the Volume for each job. \item [Record] \index{Record} A record consists of a Record Header, which is managed by the Storage daemon and Record Data, which is the data received from the Client. A record is the -primitive unit of information sent to and from the Storage daemon by the -Client (File daemon) programs. The details are described below. +primitive unit of information sent to and from the Storage daemon by the +Client (File daemon) programs. The details are described below. \item [JobId] \index{JobId} A number assigned by the Director daemon for a particular job. This number -will be unique for that particular Director (Catalog). The daemons use this +will be unique for that particular Director (Catalog). The daemons use this number to keep track of individual jobs. Within the Storage daemon, the JobId may not be unique if several Directors are accessing the Storage daemon -simultaneously. +simultaneously. \item [Session] \index{Session} A Session is a concept used in the Storage daemon corresponds one to one to a Job with the exception that each session is uniquely identified within the -Storage daemon by a unique SessionId/SessionTime pair (see below). +Storage daemon by a unique SessionId/SessionTime pair (see below). \item [VolSessionId] \index{VolSessionId} A unique number assigned by the Storage daemon to a particular session (Job) -it is having with a File daemon. This number by itself is not unique to the -given Volume, but with the VolSessionTime, it is unique. +it is having with a File daemon. This number by itself is not unique to the +given Volume, but with the VolSessionTime, it is unique. \item [VolSessionTime] \index{VolSessionTime} @@ -81,7 +78,7 @@ given Volume, but with the VolSessionTime, it is unique. execution. It is actually the Unix time\_t value of when the Storage daemon began execution cast to a 32 bit unsigned integer. The combination of the {\bf VolSessionId} and the {\bf VolSessionTime} for a given Storage daemon is -guaranteed to be unique for each Job (or session). +guaranteed to be unique for each Job (or session). \item [FileIndex] \index{FileIndex} @@ -91,7 +88,7 @@ daemon ensures that this number is greater than zero and sequential. Note, the Storage daemon uses negative FileIndexes to flag Session Start and End Labels as well as End of Volume Labels. Thus, the combination of VolSessionId, VolSessionTime, and FileIndex uniquely identifies the records -for a single file written to a Volume. +for a single file written to a Volume. \item [Stream] \index{Stream} @@ -100,10 +97,10 @@ can be any number of distinct pieces of information about that file, e.g. the attributes, the file data, ... The Stream indicates what piece of data it is, and it is an arbitrary number assigned by the File daemon to the parts (Unix attributes, Win32 attributes, data, compressed data,\ ...) of a file -that are sent to the Storage daemon. The Storage daemon has no knowledge of +that are sent to the Storage daemon. The Storage daemon has no knowledge of the details of a Stream; it simply represents a numbered stream of bytes. The data for a given stream may be passed to the Storage daemon in single record, -or in multiple records. +or in multiple records. \item [Block Header] \index{Block Header} @@ -111,7 +108,7 @@ or in multiple records. in bytes (typically 64,512) a checksum, and sequential block number. Each block starts with a Block Header and is followed by Records. Current block headers also contain the VolSessionId and VolSessionTime for the records -written to that block. +written to that block. \item [Record Header] \index{Record Header} @@ -120,23 +117,23 @@ FileIndex, the Stream, and the size of the data record which follows. The Record Header is always immediately followed by a Data Record if the size given in the Header is greater than zero. Note, for Block headers of level BB02 (version 1.27 and later), the Record header as written to tape does not -contain the Volume Session Id and the Volume Session Time as these two +contain the Volume Session Id and the Volume Session Time as these two fields are stored in the BB02 Block header. The in-memory record header does -have those fields for convenience. +have those fields for convenience. \item [Data Record] \index{Data Record} A data record consists of a binary stream of bytes and is always preceded by a Record Header. The details of the meaning of the binary stream of bytes are unknown to the Storage daemon, but the Client programs (File daemon) defines -and thus knows the details of each record type. +and thus knows the details of each record type. \item [Volume Label] \index{Volume Label} A label placed by the Storage daemon at the beginning of each storage volume. It contains general information about the volume. It is written in Record format. The Storage daemon manages Volume Labels, and if the client wants, he -may also read them. +may also read them. \item [Begin Session Label] \index{Begin Session Label} @@ -146,25 +143,24 @@ daemon. This record is useful for finding the beginning of a particular session (Job), since no records with the same VolSessionId and VolSessionTime will precede this record. This record is not normally visible outside of the Storage daemon. The Begin Session Label is similar to the Volume Label except -that it contains additional information pertaining to the Session. +that it contains additional information pertaining to the Session. \item [End Session Label] \index{End Session Label} The End Session Label is a special record placed by the Storage daemon on the storage medium as the last record of an append session job with a File daemon. The End Session Record is distinguished by a FileIndex with a value -of minus two (-2). This record is useful for detecting the end of a -particular session since no records with the same VolSessionId and +of minus two (-2). This record is useful for detecting the end of a +particular session since no records with the same VolSessionId and VolSessionTime will follow this record. This record is not normally visible outside of the Storage daemon. The End Session Label is similar to the Volume Label except that it contains additional information pertaining to the -Session. +Session. \end{description} \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} The file storage and tape storage formats are identical except that tape records are by default blocked into blocks of 64,512 bytes, except for the @@ -173,65 +169,62 @@ multiple of 1024 whereas the last record of file storage is not rounded up. The default block size of 64,512 bytes may be overridden by the user (some 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. +Sessions written to file are simply appended to the end of the file. \section{Overall Format} \index{Format!Overall} \index{Overall Format} -\addcontentsline{toc}{subsection}{Overall Format} A Bacula output file consists of Blocks of data. Each block contains a block header followed by records. Each record consists of a record header followed by the record data. The first record on a tape will always be the Volume Label -Record. +Record. No Record Header will be split across Bacula blocks. However, Record Data may be split across any number of Bacula blocks. Obviously this will not be the case for the Volume Label which will always be smaller than the Bacula Block -size. +size. To simplify reading tapes, the Start of Session (SOS) and End of Session (EOS) records are never split across blocks. If this is about to happen, Bacula will write a short block before writing the session record (actually, the SOS record should always be the first record in a block, excepting perhaps the -Volume label). +Volume label). Due to hardware limitations, the last block written to the tape may not be fully written. If your drive permits backspace record, Bacula will backup over the last record written on the tape, re-read it and verify that it was -correctly written. +correctly written. When a new tape is mounted Bacula will write the full contents of the partially written block to the new tape ensuring that there is no loss of data. When reading a tape, Bacula will discard any block that is not totally 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. +ensure that no block is missing or duplicated. \section{Serialization} \index{Serialization} -\addcontentsline{toc}{subsection}{Serialization} 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. +written to the output volume in a machine independent format. \section{Block Header} \index{Header!Block} \index{Block Header} -\addcontentsline{toc}{subsection}{Block Header} -The format of the Block Header (version 1.27 and later) is: +The format of the Block Header (version 1.27 and later) is: \footnotesize -\begin{verbatim} +\begin{lstlisting} uint32_t CheckSum; /* Block check sum */ uint32_t BlockSize; /* Block byte size including the header */ uint32_t BlockNumber; /* Block number */ char ID[4] = "BB02"; /* Identification and block level */ uint32_t VolSessionId; /* Session Id for Job */ uint32_t VolSessionTime; /* Session Time for Job */ -\end{verbatim} +\end{lstlisting} \normalsize The Block header is a fixed length and fixed format and is followed by Record @@ -247,28 +240,27 @@ be in machine independent format. See below for version 2 of the block header. \section{Record Header} \index{Header!Record} \index{Record Header} -\addcontentsline{toc}{subsection}{Record Header} Each binary data record is preceded by a Record Header. The Record Header is fixed length and fixed format, whereas the binary data record is of variable length. The Record Header is written using the Bacula serialization routines -and thus is guaranteed to be in machine independent format. +and thus is guaranteed to be in machine independent format. -The format of the Record Header (version 1.27 or later) is: +The format of the Record Header (version 1.27 or later) is: \footnotesize -\begin{verbatim} +\begin{lstlisting} int32_t FileIndex; /* File index supplied by File daemon */ int32_t Stream; /* Stream number supplied by File daemon */ uint32_t DataSize; /* size of following data record in bytes */ -\end{verbatim} +\end{lstlisting} \normalsize This record is followed by the binary Stream data of DataSize bytes, followed by another Record Header record and the binary stream data. For the definitive -definition of this record, see record.h in the src/stored directory. +definition of this record, see record.h in the src/stored directory. -Additional notes on the above: +Additional notes on the above: \begin{description} @@ -276,14 +268,14 @@ Additional notes on the above: \index{VolSessionId} is a unique sequential number that is assigned by the Storage Daemon to a particular Job. This number is sequential since the start of execution of the -daemon. +daemon. \item [The {\bf VolSessionTime} ] \index{VolSessionTime} is the time/date that the current execution of the Storage Daemon started. It assures that the combination of VolSessionId and VolSessionTime is unique for every jobs written to the tape, even if there was a machine crash between two -writes. +writes. \item [The {\bf FileIndex} ] \index{FileIndex} @@ -291,24 +283,24 @@ writes. index to be greater than zero and sequential. Note, however, that the File daemon may send multiple Streams for the same FileIndex. In addition, the Storage daemon uses negative FileIndices to hold the Begin Session Label, the -End Session Label, and the End of Volume Label. +End Session Label, and the End of Volume Label. \item [The {\bf Stream} ] \index{Stream} is defined by the File daemon and is used to identify separate parts of the data saved for each file (Unix attributes, Win32 attributes, file data, -compressed file data, sparse file data, ...). The Storage Daemon has no idea +compressed file data, sparse file data, ...). The Storage Daemon has no idea of what a Stream is or what it contains except that the Stream is required to be a positive integer. Negative Stream numbers are used internally by the Storage daemon to indicate that the record is a continuation of the previous -record (the previous record would not entirely fit in the block). +record (the previous record would not entirely fit in the block). -For Start Session and End Session Labels (where the FileIndex is negative), +For Start Session and End Session Labels (where the FileIndex is negative), the Storage daemon uses the Stream field to contain the JobId. The current -stream definitions are: +stream definitions are: \footnotesize -\begin{verbatim} +\begin{lstlisting} #define STREAM_UNIX_ATTRIBUTES 1 /* Generic Unix attributes */ #define STREAM_FILE_DATA 2 /* Standard uncompressed data */ #define STREAM_MD5_SIGNATURE 3 /* MD5 signature for the file */ @@ -326,7 +318,7 @@ stream definitions are: #define STREAM_HFSPLUS_ATTRIBUTES 14 /* Mac OS extra attributes */ #define STREAM_UNIX_ATTRIBUTES_ACCESS_ACL 15 /* Standard ACL attributes on UNIX */ #define STREAM_UNIX_ATTRIBUTES_DEFAULT_ACL 16 /* Default ACL attributes on UNIX */ -\end{verbatim} +\end{lstlisting} \normalsize \item [The {\bf DataSize} ] @@ -335,7 +327,7 @@ stream definitions are: Record header. The Storage Daemon has no idea of the actual contents of the binary data record. For standard Unix files, the data record typically contains the file attributes or the file data. For a sparse file the first -64 bits of the file data contains the storage address for the data block. +64 bits of the file data contains the storage address for the data block. \end{description} The Record Header is never split across two blocks. If there is not enough @@ -347,26 +339,25 @@ piece of the data is preceded by a new Record Header. Thus each piece of data is always immediately preceded by a Record Header. When reading a record, if 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. +record. \section{Version BB02 Block Header} \index{Version BB02 Block Header} \index{Header!Version BB02 Block} -\addcontentsline{toc}{subsection}{Version BB02 Block Header} Each session or Job has its own private block. As a consequence, the SessionId and SessionTime are written once in each Block Header and not in the Record -Header. So, the second and current version of the Block Header BB02 is: +Header. So, the second and current version of the Block Header BB02 is: \footnotesize -\begin{verbatim} +\begin{lstlisting} uint32_t CheckSum; /* Block check sum */ uint32_t BlockSize; /* Block byte size including the header */ uint32_t BlockNumber; /* Block number */ char ID[4] = "BB02"; /* Identification and block level */ uint32_t VolSessionId; /* Applies to all records */ uint32_t VolSessionTime; /* contained in this block */ -\end{verbatim} +\end{lstlisting} \normalsize As with the previous version, the BB02 Block header is a fixed length and @@ -376,12 +367,11 @@ including the CheckSum field. The Block Header is always immediately followed by a Record Header. If the tape is damaged, a Bacula utility will be able to 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. +routines and thus is guaranteed to be in machine independent format. \section{Version 2 Record Header} \index{Version 2 Record Header} \index{Header!Version 2 Record} -\addcontentsline{toc}{subsection}{Version 2 Record Header} Version 2 Record Header is written to the medium when using Version BB02 Block Headers. The memory representation of the record is identical to the old BB01 @@ -391,23 +381,22 @@ with these values when the First user record is written (i.e. non label record) so that when the block is written, it will have the current and unique VolSessionId and VolSessionTime. On reading each record from the Block, the VolSessionId and VolSessionTime is filled in the Record Header from the Block -Header. +Header. \section{Volume Label Format} \index{Volume Label Format} \index{Format!Volume Label} -\addcontentsline{toc}{subsection}{Volume Label Format} Tape volume labels are created by the Storage daemon in response to a {\bf label} command given to the Console program, or alternatively by the {\bf btape} program. created. Each volume is labeled with the following information using the Bacula serialization routines, which guarantee machine byte order -independence. +independence. -For Bacula versions 1.27 and later, the Volume Label Format is: +For Bacula versions 1.27 and later, the Volume Label Format is: \footnotesize -\begin{verbatim} +\begin{lstlisting} char Id[32]; /* Bacula 1.0 Immortal\n */ uint32_t VerNum; /* Label version number */ /* VerNum 11 and greater Bacula 1.27 and later */ @@ -425,24 +414,23 @@ For Bacula versions 1.27 and later, the Volume Label Format is: char LabelProg[32]; /* Label program name */ char ProgVersion[32]; /* Program version */ char ProgDate[32]; /* Program build date/time */ -\end{verbatim} +\end{lstlisting} \normalsize 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. +appear in the data part of the record. \section{Session Label} \index{Label!Session} \index{Session Label} -\addcontentsline{toc}{subsection}{Session Label} The Session Label is written at the beginning and end of each session as well as the last record on the physical medium. It has the following binary format: \footnotesize -\begin{verbatim} +\begin{lstlisting} char Id[32]; /* Bacula Immortal ... */ uint32_t VerNum; /* Label version number */ uint32_t JobId; /* Job id */ @@ -462,13 +450,13 @@ as the last record on the physical medium. It has the following binary format: char FileSetName[128]; /* FileSet name */ uint32_t JobType; uint32_t JobLevel; -\end{verbatim} +\end{lstlisting} \normalsize -In addition, the EOS label contains: +In addition, the EOS label contains: \footnotesize -\begin{verbatim} +\begin{lstlisting} /* The remainder are part of EOS label only */ uint32_t JobFiles; uint64_t JobBytes; @@ -477,31 +465,30 @@ In addition, the EOS label contains: uint32_t start_file; uint32_t end_file; uint32_t JobErrors; -\end{verbatim} +\end{lstlisting} \normalsize In addition, for VerNum greater than 10, the EOS label contains (in addition -to the above): +to the above): \footnotesize -\begin{verbatim} +\begin{lstlisting} uint32_t JobStatus /* Job termination code */ -\end{verbatim} +\end{lstlisting} \normalsize : Note, the LabelType (Volume Label, Volume PreLabel, Session Start Label, ...) is stored in the record FileIndex field and does not appear in the data 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. +data in many cases. \section{Overall Storage Format} \index{Format!Overall Storage} \index{Overall Storage Format} -\addcontentsline{toc}{subsection}{Overall Storage Format} \footnotesize -\begin{verbatim} +\begin{lstlisting} Current Bacula Tape Format 6 June 2001 Version BB02 added 28 September 2002 @@ -637,7 +624,7 @@ data in many cases. | ProgDate (32 bytes) | |-------------------------------------------------------| :=======================================================: - + Id: 32 byte Bacula identifier "Bacula 1.0 immortal\n" (old version also recognized:) Id: 32 byte Bacula identifier "Bacula 0.9 mortal\n" @@ -726,35 +713,34 @@ data in many cases. MediaType: Media Type ClientName: Name of File daemon or Client writing this session Not used for EOM_LABEL. -\end{verbatim} +\end{lstlisting} \normalsize \section{Unix File Attributes} \index{Unix File Attributes} \index{Attributes!Unix File} -\addcontentsline{toc}{subsection}{Unix File Attributes} -The Unix File Attributes packet consists of the following: +The Unix File Attributes packet consists of the following: \lt{}File-Index\gt{} \lt{}Type\gt{} \lt{}Filename\gt{}@\lt{}File-Attributes\gt{}@\lt{}Link\gt{} -@\lt{}Extended-Attributes@\gt{} where +@\lt{}Extended-Attributes@\gt{} where \begin{description} \item [@] - represents a byte containing a binary zero. + represents a byte containing a binary zero. \item [FileIndex] \index{FileIndex} - is the sequential file index starting from one assigned by the File daemon. + is the sequential file index starting from one assigned by the File daemon. \item [Type] \index{Type} - is one of the following: + is one of the following: \footnotesize -\begin{verbatim} +\begin{lstlisting} #define FT_LNKSAVED 1 /* hard link to file already saved */ #define FT_REGE 2 /* Regular file but empty */ #define FT_REG 3 /* Regular file */ @@ -772,117 +758,70 @@ The Unix File Attributes packet consists of the following: #define FT_NOOPEN 15 /* Could not open directory */ #define FT_RAW 16 /* Raw block device */ #define FT_FIFO 17 /* Raw fifo device */ -\end{verbatim} +\end{lstlisting} \normalsize \item [Filename] \index{Filename} - is the fully qualified filename. + is the fully qualified filename. \item [File-Attributes] \index{File-Attributes} consists of the 13 fields of the stat() buffer in ASCII base64 format separated by spaces. These fields and their meanings are shown below. This stat() packet is in Unix format, and MUST be provided (constructed) for ALL -systems. +systems. \item [Link] \index{Link} when the FT code is FT\_LNK or FT\_LNKSAVED, the item in question is a Unix link, and this field contains the fully qualified link name. When the FT code -is not FT\_LNK or FT\_LNKSAVED, this field is null. +is not FT\_LNK or FT\_LNKSAVED, this field is null. \item [Extended-Attributes] \index{Extended-Attributes} The exact format of this field is operating system dependent. It contains additional or extended attributes of a system dependent nature. Currently, -this field is used only on WIN32 systems where it contains a ASCII base64 +this field is used only on WIN32 systems where it contains a ASCII base64 representation of the WIN32\_FILE\_ATTRIBUTE\_DATA structure as defined by Windows. The fields in the base64 representation of this structure are like -the File-Attributes separated by spaces. +the File-Attributes separated by spaces. \end{description} -The File-attributes consist of the following: - -\addcontentsline{lot}{table}{File Attributes} -\begin{longtable}{|p{0.6in}|p{0.7in}|p{1in}|p{1in}|p{1.4in}|} - \hline -\multicolumn{1}{|c|}{\bf Field No. } & \multicolumn{1}{c|}{\bf Stat Name } -& \multicolumn{1}{c|}{\bf Unix } & \multicolumn{1}{c|}{\bf Win98/NT } & -\multicolumn{1}{c|}{\bf MacOS } \\ - \hline -\multicolumn{1}{|c|}{1 } & {st\_dev } & {Device number of filesystem } & -{Drive number } & {vRefNum } \\ - \hline -\multicolumn{1}{|c|}{2 } & {st\_ino } & {Inode number } & {Always 0 } & -{fileID/dirID } \\ - \hline -\multicolumn{1}{|c|}{3 } & {st\_mode } & {File mode } & {File mode } & -{777 dirs/apps; 666 docs; 444 locked docs } \\ - \hline -\multicolumn{1}{|c|}{4 } & {st\_nlink } & {Number of links to the file } & -{Number of link (only on NTFS) } & {Always 1 } \\ - \hline -\multicolumn{1}{|c|}{5 } & {st\_uid } & {Owner ID } & {Always 0 } & -{Always 0 } \\ - \hline -\multicolumn{1}{|c|}{6 } & {st\_gid } & {Group ID } & {Always 0 } & -{Always 0 } \\ - \hline -\multicolumn{1}{|c|}{7 } & {st\_rdev } & {Device ID for special files } & -{Drive No. } & {Always 0 } \\ - \hline -\multicolumn{1}{|c|}{8 } & {st\_size } & {File size in bytes } & {File -size in bytes } & {Data fork file size in bytes } \\ - \hline -\multicolumn{1}{|c|}{9 } & {st\_blksize } & {Preferred block size } & -{Always 0 } & {Preferred block size } \\ - \hline -\multicolumn{1}{|c|}{10 } & {st\_blocks } & {Number of blocks allocated } -& {Always 0 } & {Number of blocks allocated } \\ - \hline -\multicolumn{1}{|c|}{11 } & {st\_atime } & {Last access time since epoch } -& {Last access time since epoch } & {Last access time -66 years } \\ - \hline -\multicolumn{1}{|c|}{12 } & {st\_mtime } & {Last modify time since epoch } -& {Last modify time since epoch } & {Last access time -66 years } \\ - \hline -\multicolumn{1}{|c|}{13 } & {st\_ctime } & {Inode change time since epoch -} & {File create time since epoch } & {File create time -66 years} -\\ \hline - -\end{longtable} +The File-attributes consist of the following: + +%\addcontentsline{lot}{table}{File Attributes} +\LTXtable{\linewidth}{table_fileattributes} \section{Old Depreciated Tape Format} \index{Old Depreciated Tape Format} \index{Format!Old Depreciated Tape} -\addcontentsline{toc}{subsection}{Old Depreciated Tape Format} -The format of the Block Header (version 1.26 and earlier) is: +The format of the Block Header (version 1.26 and earlier) is: \footnotesize -\begin{verbatim} +\begin{lstlisting} uint32_t CheckSum; /* Block check sum */ uint32_t BlockSize; /* Block byte size including the header */ uint32_t BlockNumber; /* Block number */ char ID[4] = "BB01"; /* Identification and block level */ -\end{verbatim} +\end{lstlisting} \normalsize -The format of the Record Header (version 1.26 or earlier) is: +The format of the Record Header (version 1.26 or earlier) is: \footnotesize -\begin{verbatim} +\begin{lstlisting} uint32_t VolSessionId; /* Unique ID for this session */ uint32_t VolSessionTime; /* Start time/date of session */ int32_t FileIndex; /* File index supplied by File daemon */ int32_t Stream; /* Stream number supplied by File daemon */ uint32_t DataSize; /* size of following data record in bytes */ -\end{verbatim} +\end{lstlisting} \normalsize \footnotesize -\begin{verbatim} +\begin{lstlisting} Current Bacula Tape Format 6 June 2001 Version BB01 is the old deprecated format. @@ -1023,7 +962,7 @@ The format of the Record Header (version 1.26 or earlier) is: | ProgDate (32 bytes) | |-------------------------------------------------------| :=======================================================: - + Id: 32 byte Bacula identifier "Bacula 1.0 immortal\n" (old version also recognized:) Id: 32 byte Bacula identifier "Bacula 0.9 mortal\n" @@ -1111,5 +1050,5 @@ The format of the Record Header (version 1.26 or earlier) is: MediaType: Media Type ClientName: Name of File daemon or Client writing this session Not used for EOM_LABEL. -\end{verbatim} +\end{lstlisting} \normalsize diff --git a/docs/manuals/en/developers/mempool.tex b/docs/manuals/en/developers/mempool.tex index a8130200..08b2d13d 100644 --- a/docs/manuals/en/developers/mempool.tex +++ b/docs/manuals/en/developers/mempool.tex @@ -21,12 +21,12 @@ 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: -\begin{itemize} +\begin{bsysitemize} \item Statically allocated memory. \item Dynamically allocated memory using malloc() and free(). \item Non-pooled memory. \item Pooled memory. - \end{itemize} + \end{bsysitemize} \subsection{Statically Allocated Memory} \index{Statically Allocated Memory} @@ -36,9 +36,9 @@ turn. They are: Statically allocated memory is of the form: \footnotesize -\begin{verbatim} +\begin{lstlisting} char buffer[MAXSTRING]; -\end{verbatim} +\end{lstlisting} \normalsize The use of this kind of memory is discouraged except when you are 100\% sure @@ -57,18 +57,18 @@ Dynamically allocated memory is obtained using the standard malloc() routines. As in: \footnotesize -\begin{verbatim} +\begin{lstlisting} char *buf; buf = malloc(256); -\end{verbatim} +\end{lstlisting} \normalsize This kind of memory can be released with: \footnotesize -\begin{verbatim} +\begin{lstlisting} free(buf); -\end{verbatim} +\end{lstlisting} \normalsize It is recommended to use this kind of memory only when you are sure that you @@ -108,21 +108,21 @@ frequently. Currently there are three memory pool types: -\begin{itemize} +\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. - \end{itemize} + \end{bsysitemize} \paragraph*{Getting Memory:} To get memory, one uses: \footnotesize -\begin{verbatim} +\begin{lstlisting} void *get_pool_memory(pool); -\end{verbatim} +\end{lstlisting} \normalsize where {\bf pool} is one of the above mentioned pool names. The size of the @@ -132,9 +132,9 @@ the application. If you wish non-pooled memory, you may alternatively call: \footnotesize -\begin{verbatim} +\begin{lstlisting} void *get_memory(size_t size); -\end{verbatim} +\end{lstlisting} \normalsize The buffer length will be set to the size specified, and it will be assigned @@ -145,9 +145,9 @@ to the PM\_NOPOOL pool (no pooling). To free memory acquired by either of the above two calls, use: \footnotesize -\begin{verbatim} +\begin{lstlisting} void free_pool_memory(void *buffer); -\end{verbatim} +\end{lstlisting} \normalsize where buffer is the memory buffer returned when the memory was acquired. If @@ -160,9 +160,9 @@ free chain to be used in a subsequent call for memory from that pool. To determine the memory buffer size, use: \footnotesize -\begin{verbatim} +\begin{lstlisting} size_t sizeof_pool_memory(void *buffer); -\end{verbatim} +\end{lstlisting} \normalsize \paragraph*{Resizing Pool Memory:} @@ -170,9 +170,9 @@ size_t sizeof_pool_memory(void *buffer); To resize pool memory, use: \footnotesize -\begin{verbatim} +\begin{lstlisting} void *realloc_pool_memory(void *buffer); -\end{verbatim} +\end{lstlisting} \normalsize The buffer will be reallocated, and the contents of the original buffer will @@ -184,9 +184,9 @@ To have the system check and if necessary adjust the size of your pooled memory buffer, use: \footnotesize -\begin{verbatim} +\begin{lstlisting} void *check_pool_memory_size(void *buffer, size_t new-size); -\end{verbatim} +\end{lstlisting} \normalsize where {\bf new-size} is the buffer length needed. Note, if the buffer is @@ -202,9 +202,9 @@ In order to avoid orphaned buffer error messages when terminating the program, use: \footnotesize -\begin{verbatim} +\begin{lstlisting} void close_memory_pool(); -\end{verbatim} +\end{lstlisting} \normalsize to free all unused memory retained in the Bacula memory pool. Note, any memory @@ -217,18 +217,18 @@ For debugging purposes and performance tuning, the following call will print the current memory pool statistics: \footnotesize -\begin{verbatim} +\begin{lstlisting} void print_memory_pool_stats(); -\end{verbatim} +\end{lstlisting} \normalsize an example output is: \footnotesize -\begin{verbatim} +\begin{lstlisting} Pool Maxsize Maxused Inuse 0 256 0 0 1 256 1 0 2 256 1 0 -\end{verbatim} +\end{lstlisting} \normalsize diff --git a/docs/manuals/en/developers/netprotocol.tex b/docs/manuals/en/developers/netprotocol.tex index 45c2a8ed..4e9dc326 100644 --- a/docs/manuals/en/developers/netprotocol.tex +++ b/docs/manuals/en/developers/netprotocol.tex @@ -70,10 +70,10 @@ first writes four bytes in network byte order than indicate the size of the following data packet. It returns: \footnotesize -\begin{verbatim} +\begin{lstlisting} Returns 0 on failure Returns 1 on success -\end{verbatim} +\end{lstlisting} \normalsize In the case of a failure, an error message will be sent to the JCR contained @@ -115,12 +115,12 @@ enough, bnet\_recv() realloc() the buffer. It will return an error (-2) if maxbytes is less than the record size sent. It returns: \footnotesize -\begin{verbatim} +\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{verbatim} +\end{lstlisting} \normalsize It should be noted that bnet\_recv() is a blocking read. @@ -181,13 +181,13 @@ 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: \footnotesize -\begin{verbatim} +\begin{lstlisting} S: wait for connection C: attempt connection S: accept connection C: bnet_send() send request S: bnet_recv() wait for request S: act on request S: bnet_send() send ack C: bnet_recv() wait for ack -\end{verbatim} +\end{lstlisting} \normalsize Thus a single command is sent, acted upon by the server, and then @@ -200,24 +200,24 @@ that more than one packet will be returned. In this case, the server will enter a loop: \footnotesize -\begin{verbatim} +\begin{lstlisting} while ((n=bnet_recv(bsock)) > 0) { act on request } if (n < 0) error -\end{verbatim} +\end{lstlisting} \normalsize The client will perform the following: \footnotesize -\begin{verbatim} +\begin{lstlisting} bnet_send(bsock); bnet_send(bsock); ... bnet_sig(bsock, BNET_EOD); -\end{verbatim} +\end{lstlisting} \normalsize Thus the client will send multiple packets and signal to the server when all diff --git a/docs/manuals/en/developers/platformsupport.tex b/docs/manuals/en/developers/platformsupport.tex index a04e56f7..0ad65716 100644 --- a/docs/manuals/en/developers/platformsupport.tex +++ b/docs/manuals/en/developers/platformsupport.tex @@ -38,7 +38,7 @@ As mentioned above, in order to become a fully supported platform, it must support POSIX Unix system calls. In addition, the following requirements must be met: -\begin{itemize} +\begin{bsysitemize} \item The principal developer (currently Kern) must have non-root ssh access to a test machine running the platform. \item The ideal requirements and minimum requirements @@ -59,10 +59,10 @@ requirements must be met: each Bacula release. \item Ideally there are one or more developers who can respond to and fix platform specific bugs. -\end{itemize} +\end{bsysitemize} Ideal requirements for a test machine: -\begin{itemize} +\begin{bsysitemize} \item The principal developer will have non-root ssh access to the test machine at all times. \item The pricipal developer will have a root password. @@ -77,10 +77,10 @@ Ideal requirements for a test machine: access for account "bacula" available. \item The test machine will have sftp access. \item The test machine will provide an smtp server. -\end{itemize} +\end{bsysitemize} Minimum requirements for a test machine: -\begin{itemize} +\begin{bsysitemize} \item The principal developer will have non-root ssh access to the test machine when requested approximately once a month. \item The pricipal developer not have root access. @@ -95,13 +95,13 @@ Minimum requirements for a test machine: access. \item The test machine will have no sftp access. \item The test machine will provide no email access. -\end{itemize} +\end{bsysitemize} Bare bones test machine requirements: -\begin{itemize} +\begin{bsysitemize} \item The test machine is available only to a designated test person (your own machine). \item The designated test person runs the regession tests on demand. \item The test machine has a tape drive available. -\end{itemize} +\end{bsysitemize} diff --git a/docs/manuals/en/developers/pluginAPI.tex b/docs/manuals/en/developers/pluginAPI.tex index 2a36b7a8..109fcd0a 100644 --- a/docs/manuals/en/developers/pluginAPI.tex +++ b/docs/manuals/en/developers/pluginAPI.tex @@ -27,9 +27,9 @@ current version is what we call a command plugin. As with all plugins, it gets notified of important events as noted above (details described below), but in addition, this kind of plugin can accept a command line, which is a: -\begin{verbatim} +\begin{lstlisting} Plugin = -\end{verbatim} +\end{lstlisting} directive that is placed in the Include section of a FileSet and is very similar to the "File = " directive. When this Plugin directive is encountered @@ -41,12 +41,12 @@ to be restored but do not necessarily correspond to actual files on the filesystem. The important features of the command plugin entry points are: -\begin{itemize} +\begin{bsysitemize} \item It is triggered by a "Plugin =" directive in the FileSet \item Only a single plugin is called that is named on the "Plugin =" directive. \item The full command string after the "Plugin =" is passed to the plugin so that it can be told what to backup/restore. -\end{itemize} +\end{bsysitemize} The third type of plugin is the Options Plugin, this kind of plugin is useful to implement some custom filter on data. For example, you can implement a @@ -56,7 +56,7 @@ Wild/Regex/Exclude/Include rules). As with all plugins, it gets notified of important events as noted above (details described below), but in addition, this kind of plugin can be placed in a Options group, which is a: -\begin{verbatim} +\begin{lstlisting} FileSet { Name = TestFS Include { @@ -69,7 +69,7 @@ this kind of plugin can be placed in a Options group, which is a: File = / } } -\end{verbatim} +\end{lstlisting} \section{Loading Plugins} Once the File daemon loads the plugins, it asks the OS for the @@ -87,13 +87,13 @@ entry point. The two entry points are: -\begin{verbatim} +\begin{lstlisting} bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs) and bRC unloadPlugin() -\end{verbatim} +\end{lstlisting} both these external entry points to the shared object are defined as C entry points to avoid name mangling complications with C++. However, the shared @@ -106,13 +106,13 @@ your plugin. It along with {\bf src/lib/plugins.h} define basically the whole plugin interface. Within this header file, it includes the following files: -\begin{verbatim} +\begin{lstlisting} #include #include "config.h" #include "bc_types.h" #include "lib/plugins.h" #include -\end{verbatim} +\end{lstlisting} Aside from the {\bf bc\_types.h} and {\bf confit.h} headers, the plugin definition uses the minimum code from Bacula. The bc\_types.h file is required @@ -120,7 +120,7 @@ to ensure that the data type definitions in arguments correspond to the Bacula core code. The return codes are defined as: -\begin{verbatim} +\begin{lstlisting} typedef enum { bRC_OK = 0, /* OK */ bRC_Stop = 1, /* Stop calling other plugins */ @@ -131,7 +131,7 @@ typedef enum { bRC_Core = 6, /* Let Bacula core handles this file */ bRC_Skip = 7, /* Skip the proposed file */ } bRC; -\end{verbatim} +\end{lstlisting} At a future point in time, we hope to make the Bacula libbac.a into a @@ -148,9 +148,9 @@ plugin, the first two arguments are information from Bacula that is passed to the plugin, and the last two arguments are information about the plugin that the plugin must return to Bacula. The call is: -\begin{verbatim} +\begin{lstlisting} bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs) -\end{verbatim} +\end{lstlisting} and the arguments are: @@ -162,12 +162,12 @@ interface version, currently defined as 1. The {\bf size} is set to the byte size of the structure. The exact definition of the bInfo structure as of this writing is: -\begin{verbatim} +\begin{lstlisting} typedef struct s_baculaInfo { uint32_t size; uint32_t version; } bInfo; -\end{verbatim} +\end{lstlisting} \item [lbfuncs] The bFuncs structure defines the callback entry points within Bacula @@ -175,7 +175,7 @@ that the plugin can use register events, get Bacula values, set Bacula values, and send messages to the Job output or debug output. The exact definition as of this writing is: -\begin{verbatim} +\begin{lstlisting} typedef struct s_baculaFuncs { uint32_t size; uint32_t version; @@ -190,7 +190,7 @@ typedef struct s_baculaFuncs { size_t size); void (*baculaFree)(bpContext *ctx, const char *file, int line, void *mem); } bFuncs; -\end{verbatim} +\end{lstlisting} We will discuss these entry points and how to use them a bit later when describing the plugin code. @@ -203,7 +203,7 @@ this structure to Bacula. The exact definition as of this writing is: -\begin{verbatim} +\begin{lstlisting} typedef struct s_pluginInfo { uint32_t size; uint32_t version; @@ -214,7 +214,7 @@ typedef struct s_pluginInfo { const char *plugin_version; const char *plugin_description; } pInfo; -\end{verbatim} +\end{lstlisting} Where: \begin{description} @@ -258,7 +258,7 @@ loaded. The exact definition as of this writing is: -\begin{verbatim} +\begin{lstlisting} typedef struct s_pluginFuncs { uint32_t size; uint32_t version; @@ -276,7 +276,7 @@ typedef struct s_pluginFuncs { bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp); bRC (*checkFile)(bpContext *ctx, char *fname); } pFuncs; -\end{verbatim} +\end{lstlisting} The details of the entry points will be presented in separate sections below. @@ -288,14 +288,14 @@ Where: \end{description} Sample code for loadPlugin: -\begin{verbatim} +\begin{lstlisting} bfuncs = lbfuncs; /* set Bacula funct pointers */ binfo = lbinfo; *pinfo = &pluginInfo; /* return pointer to our info */ *pfuncs = &pluginFuncs; /* return pointer to our functions */ return bRC_OK; -\end{verbatim} +\end{lstlisting} where pluginInfo and pluginFuncs are statically defined structures. See bpipe-fd.c for details. @@ -334,13 +334,13 @@ loadPlugin() externally defined entry point. same throughout the Job thus you can keep your private Job specific data in it ({\bf bContext}). -\begin{verbatim} +\begin{lstlisting} typedef struct s_bpContext { void *pContext; /* Plugin private context */ void *bContext; /* Bacula private context */ } bpContext; -\end{verbatim} +\end{lstlisting} This context pointer will be passed as the first argument to all the entry points that Bacula calls within the plugin. Needless @@ -377,11 +377,11 @@ and is very similar to the Bacula Python interface. When the plugin is called, Bacula passes it the pointer to an event structure (bEvent), which currently has one item, the eventType: -\begin{verbatim} +\begin{lstlisting} typedef struct s_bEvent { uint32_t eventType; } bEvent; -\end{verbatim} +\end{lstlisting} which defines what event has been triggered, and for each event, Bacula will pass a pointer to a value associated with that event. @@ -391,7 +391,7 @@ typedef struct s_bEvent { The current list of events are: -\begin{verbatim} +\begin{lstlisting} typedef enum { bEventJobStart = 1, bEventJobEnd = 2, @@ -428,7 +428,7 @@ typedef enum { } bEventType; -\end{verbatim} +\end{lstlisting} Most of the above are self-explanatory. @@ -515,7 +515,7 @@ Called when beginning the backup of a file. Here Bacula provides you with a pointer to the {\bf save\_pkt} structure and you must fill in this packet with the "attribute" data of the file. -\begin{verbatim} +\begin{lstlisting} struct save_pkt { int32_t pkt_size; /* size of this packet */ char *fname; /* Full path and filename */ @@ -532,7 +532,7 @@ struct save_pkt { int32_t index; /* restore object index */ int32_t pkt_end; /* end packet sentinel */ }; -\end{verbatim} +\end{lstlisting} The second argument is a pointer to the {\bf save\_pkt} structure for the file to be backed up. The plugin is responsible for filling in all the fields @@ -562,7 +562,7 @@ plugin for how to do I/O. Example of filling in the save\_pkt as used in bpipe-fd.c: -\begin{verbatim} +\begin{lstlisting} struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext; time_t now = time(NULL); sp->fname = p_ctx->fname; @@ -575,7 +575,7 @@ Example of filling in the save\_pkt as used in bpipe-fd.c: sp->statp.st_blocks = 1; p_ctx->backup = true; return bRC_OK; -\end{verbatim} +\end{lstlisting} Note: the filename to be created has already been created from the command string previously sent to the plugin and is in the plugin @@ -630,7 +630,7 @@ pluginIO command with a request to open the file write-only. This call must return one of the following values: -\begin{verbatim} +\begin{lstlisting} enum { CF_SKIP = 1, /* skip file (not newer or something) */ CF_ERROR, /* error creating file */ @@ -638,12 +638,12 @@ This call must return one of the following values: CF_CREATED, /* file created, no data to extract */ CF_CORE /* let bacula core handles the file creation */ }; -\end{verbatim} +\end{lstlisting} in the restore\_pkt value {\bf create\_status}. For a normal file, unless there is an error, you must return {\bf CF\_EXTRACT}. -\begin{verbatim} +\begin{lstlisting} struct restore_pkt { int32_t pkt_size; /* size of this packet */ @@ -664,11 +664,11 @@ struct restore_pkt { int32_t pkt_end; /* end packet sentinel */ }; -\end{verbatim} +\end{lstlisting} Typical code to create a regular file would be the following: -\begin{verbatim} +\begin{lstlisting} struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext; time_t now = time(NULL); sp->fname = p_ctx->fname; /* set the full path/filename I want to create */ @@ -681,7 +681,7 @@ Typical code to create a regular file would be the following: sp->statp.st_blksize = 4096; sp->statp.st_blocks = 1; return bRC_OK; -\end{verbatim} +\end{lstlisting} This will create a virtual file. If you are creating a file that actually exists, you will most likely want to fill the statp packet using the @@ -689,7 +689,7 @@ stat() system call. Creating a directory is similar, but requires a few extra steps: -\begin{verbatim} +\begin{lstlisting} struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext; time_t now = time(NULL); sp->fname = p_ctx->fname; /* set the full path I want to create */ @@ -703,7 +703,7 @@ Creating a directory is similar, but requires a few extra steps: sp->statp.st_blksize = 4096; sp->statp.st_blocks = 1; return bRC_OK; -\end{verbatim} +\end{lstlisting} The link field must be set with the full cononical path name, which always ends with a forward slash. If you do not terminate it with a forward slash, @@ -734,7 +734,7 @@ close(), and lseek() I/O calls, and the arguments are passed in the packet and the return values are also placed in the packet. In addition for Win32 systems the plugin must return two additional values (described below). -\begin{verbatim} +\begin{lstlisting} enum { IO_OPEN = 1, IO_READ = 2, @@ -759,7 +759,7 @@ struct io_pkt { bool win32; /* Win32 GetLastError returned */ int32_t pkt_end; /* end packet sentinel */ }; -\end{verbatim} +\end{lstlisting} The particular Unix function being simulated is indicated by the {\bf func}, which will have one of the IO\_OPEN, IO\_READ, ... codes listed above. The @@ -848,7 +848,7 @@ entrypoint currently is unimplemented. \subsection{bRC getBaculaValue(bpContext *ctx, bVariable var, void *value)} Calling this entrypoint, you can obtain specific values that are available in Bacula. The following Variables can be referenced: -\begin{itemize} +\begin{bsysitemize} \item bVarJobId returns an int \item bVarFDName returns a char * \item bVarLevel returns an int @@ -857,7 +857,7 @@ in Bacula. The following Variables can be referenced: \item bVarJobStatus returns an int \item bVarSinceTime returns an int (time\_t) \item bVarAccurate returns an int -\end{itemize} +\end{bsysitemize} \subsection{bRC setBaculaValue(bpContext *ctx, bVariable var, void *value)} Calling this entrypoint allows you to set particular values in @@ -889,7 +889,7 @@ There is currently one sample program {\bf example-plugin-fd.c} and one working plugin {\bf bpipe-fd.c} that can be found in the Bacula {\bf src/plugins/fd} directory. Both are built with the following: -\begin{verbatim} +\begin{lstlisting} cd ./configure make @@ -897,7 +897,7 @@ one working plugin {\bf bpipe-fd.c} that can be found in the Bacula cd src/plugins/fd make make test -\end{verbatim} +\end{lstlisting} After building Bacula and changing into the src/plugins/fd directory, the {\bf make} command will build the {\bf bpipe-fd.so} plugin, which diff --git a/docs/manuals/en/developers/porting.tex b/docs/manuals/en/developers/porting.tex index 278f0e5d..8a812465 100644 --- a/docs/manuals/en/developers/porting.tex +++ b/docs/manuals/en/developers/porting.tex @@ -22,7 +22,7 @@ them. In General, the following holds true: -\begin{itemize} +\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 @@ -51,14 +51,14 @@ distribution. \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. -\end{itemize} +\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{itemize} +\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. @@ -66,7 +66,7 @@ distribution. examine the output. It should look something like the following: \footnotesize -\begin{verbatim} +\begin{lstlisting} Configuration on Mon Oct 28 11:42:27 CET 2002: Host: i686-pc-linux-gnu -- redhat 7.3 Bacula version: 1.27 (26 October 2002) @@ -98,7 +98,7 @@ Configuration on Mon Oct 28 11:42:27 CET 2002: enable-smartalloc: yes enable-gnome: no gmp support: yes -\end{verbatim} +\end{lstlisting} \normalsize The details depend on your system. The first thing to check is that it @@ -123,7 +123,7 @@ release). \item The items to in the case statement that corresponds to your system are the following: -\begin{itemize} +\begin{bsysitemize} \item DISTVER -- set to the version of your operating system. Typically some form of {\bf uname} obtains it. \item TAPEDRIVE -- the default tape drive. Not too important as the user can @@ -147,7 +147,7 @@ Bacula in all cases. \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. -\end{itemize} +\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 @@ -170,4 +170,4 @@ 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{itemize} +\end{bsysitemize} diff --git a/docs/manuals/en/developers/regression.tex b/docs/manuals/en/developers/regression.tex index ce7cc162..63c6e621 100644 --- a/docs/manuals/en/developers/regression.tex +++ b/docs/manuals/en/developers/regression.tex @@ -38,9 +38,9 @@ clone the repository, do the following (note, we assume you are working in your home directory in a non-root account): \footnotesize -\begin{verbatim} +\begin{lstlisting} git clone http://git.bacula.org/bacula bacula -\end{verbatim} +\end{lstlisting} \normalsize This will create the directory {\bf bacula} and populate it with @@ -51,10 +51,10 @@ all the regression scripts. The above should be needed only once. Thereafter to update to the latest code, you do: \footnotesize -\begin{verbatim} +\begin{lstlisting} cd bacula git pull -\end{verbatim} +\end{lstlisting} \normalsize If you want to test with SQLite and it is not installed on your system, @@ -62,10 +62,10 @@ you will need to download the latest depkgs release from Source Forge and unpack it into {\bf depkgs}, then simply: \footnotesize -\begin{verbatim} +\begin{lstlisting} cd depkgs make -\end{verbatim} +\end{lstlisting} \normalsize @@ -95,9 +95,9 @@ There is nothing you need to change in the source directory. To begin: \footnotesize -\begin{verbatim} +\begin{lstlisting} cd bacula/regress -\end{verbatim} +\end{lstlisting} \normalsize @@ -107,15 +107,15 @@ need to create a custom config file for your system. We suggest that you start by: \footnotesize -\begin{verbatim} +\begin{lstlisting} cp prototype.conf config -\end{verbatim} +\end{lstlisting} \normalsize Then you can edit the {\bf config} file directly. \footnotesize -\begin{verbatim} +\begin{lstlisting} # Where to get the source to be tested BACULA_SOURCE="${HOME}/bacula/bacula" @@ -157,10 +157,10 @@ OPENSSL="--with-openssl" # non-networked machine HOST="localhost" -\end{verbatim} +\end{lstlisting} \normalsize -\begin{itemize} +\begin{bsysitemize} \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 @@ -175,8 +175,8 @@ HOST="localhost" \item {\bf SQLITE\_DIR} should be the full path to the sqlite package, must 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?=``\verb{--{with-postgresql''. For - MySQL use ``WHICHDB=''\verb{--{with-mysql``. + edit the Makefile and change (or add) WHICHDB?=``\lstinline+--with-postgresql+''. For + 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 @@ -220,7 +220,7 @@ HOST="localhost" \item {\bf scripts} is the bacula scripts location (where we could find database creation script, autochanger handler, etc.) -\end{itemize} +\end{bsysitemize} \subsection{Building the Test Bacula} \index{Building the Test Bacula} @@ -230,9 +230,9 @@ HOST="localhost" Once the above variables are set, you can build the setup by entering: \footnotesize -\begin{verbatim} +\begin{lstlisting} make setup -\end{verbatim} +\end{lstlisting} \normalsize This will setup the regression testing and you should not need to @@ -268,20 +268,20 @@ require a password to be supplied. This can be done by creating a ~/.my.cnf file which supplies the credentials by default to the MySQL commandline utilities. -\begin{verbatim} +\begin{lstlisting} [client] host = localhost user = regress password = asecret -\end{verbatim} +\end{lstlisting} A similar technique can be used PostgreSQL regression testing where the database is configured to require a password. The ~/.pgpass file should contain a line with the database connection properties. -\begin{verbatim} +\begin{lstlisting} hostname:port:database:username:password -\end{verbatim} +\end{lstlisting} \subsection{Running the Disk Only Regression} \index{Regression!Running the Disk Only} @@ -292,9 +292,9 @@ The simplest way to copy the source code, configure it, compile it, link it, and run the tests is to use a helper script: \footnotesize -\begin{verbatim} +\begin{lstlisting} ./do_disk -\end{verbatim} +\end{lstlisting} \normalsize @@ -309,7 +309,7 @@ to run these tests (I run under my regular userid). The result should be something similar to: \footnotesize -\begin{verbatim} +\begin{lstlisting} Test results ===== auto-label-test OK 12:31:33 ===== ===== backup-bacula-test OK 12:32:32 ===== @@ -354,20 +354,20 @@ Test results ===== scratch-pool-test OK 13:28:01 ===== Total time = 0:57:55 or 3475 secs -\end{verbatim} +\end{lstlisting} \normalsize and the working tape tests are run with \footnotesize -\begin{verbatim} +\begin{lstlisting} make full_test -\end{verbatim} +\end{lstlisting} \normalsize \footnotesize -\begin{verbatim} +\begin{lstlisting} Test results ===== Bacula tape test OK ===== @@ -376,7 +376,7 @@ Test results ===== incremental-tape test OK ===== ===== four-concurrent-jobs-tape OK ===== ===== four-jobs-tape OK ===== -\end{verbatim} +\end{lstlisting} \normalsize Each separate test is self contained in that it initializes to run Bacula from @@ -387,9 +387,9 @@ that it does not intefere with a production system. Alternatively, you can do the ./do\_disk work by hand with: \footnotesize -\begin{verbatim} +\begin{lstlisting} make setup -\end{verbatim} +\end{lstlisting} \normalsize The above will then copy the source code within @@ -405,9 +405,9 @@ Once Bacula is built, you can run the basic disk only non-root regression test by entering: \footnotesize -\begin{verbatim} +\begin{lstlisting} make test -\end{verbatim} +\end{lstlisting} \normalsize @@ -457,26 +457,26 @@ everything, and I don't run it very often. If you one or more tests fail, the line output will be similar to: \footnotesize -\begin{verbatim} +\begin{lstlisting} !!!!! concurrent-jobs-test failed!!! !!!!! -\end{verbatim} +\end{lstlisting} \normalsize If you want to determine why the test failed, you will need to rerun the script with the debug output turned on. You do so by defining the environment variable {\bf REGRESS\_DEBUG} with commands such as: -\begin{verbatim} +\begin{lstlisting} REGRESS_DEBUG=1 export REGRESS_DEBUG -\end{verbatim} +\end{lstlisting} Then from the "regress" directory (all regression scripts assume that you have "regress" as the current directory), enter: -\begin{verbatim} +\begin{lstlisting} tests/test-name -\end{verbatim} +\end{lstlisting} where test-name should be the name of a test script -- for example: {\bf tests/backup-bacula-test}. @@ -491,20 +491,20 @@ your installed binaries. Then define the variables \texttt{bin} and \texttt{scri in your config file. Example: -\begin{verbatim} +\begin{lstlisting} bin=/opt/bacula/bin scripts=/opt/bacula/scripts -\end{verbatim} +\end{lstlisting} The \texttt{./scripts/prepare-other-loc} will tweak the regress scripts to use your binary location. You will need to run it manually once before you run any regression tests. -\begin{verbatim} +\begin{lstlisting} $ ./scripts/prepare-other-loc $ ./tests/backup-bacula-test ... -\end{verbatim} +\end{lstlisting} 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}, @@ -522,20 +522,20 @@ rerun the {\bf make setup} step. If you wish to run a single test, you can simply: -\begin{verbatim} +\begin{lstlisting} cd regress tests/ -\end{verbatim} +\end{lstlisting} or, if the source code has been updated, you would do: -\begin{verbatim} +\begin{lstlisting} cd bacula git pull cd regress make setup tests/backup-to-null -\end{verbatim} +\end{lstlisting} \section{Writing a Regression Test} @@ -557,9 +557,9 @@ You can run any individual test by hand by cd'ing to the {\bf regress} directory and entering: \footnotesize -\begin{verbatim} +\begin{lstlisting} tests/ -\end{verbatim} +\end{lstlisting} \normalsize \subsection{Directory Structure} @@ -570,7 +570,7 @@ tests/ The directory structure of the regression tests is: \footnotesize -\begin{verbatim} +\begin{lstlisting} regress - Makefile, scripts to start tests |------ scripts - Scripts and conf files |-------tests - All test scripts are here @@ -586,7 +586,7 @@ The directory structure of the regression tests is: |------ tmp - Most temp files go here |------ working - Bacula working directory |------ weird-files - Weird files used in two of the tests. -\end{verbatim} +\end{lstlisting} \normalsize \subsection{Adding a New Test} @@ -611,26 +611,26 @@ 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: -\begin{verbatim} +\begin{lstlisting} REGRESS_WAIT=1 export REGRESS_WAIT -\end{verbatim} +\end{lstlisting} Then executing the script. When the script prints the following line: -\begin{verbatim} +\begin{lstlisting} Start Bacula under debugger and enter anything when ready ... -\end{verbatim} +\end{lstlisting} You start the Bacula component you want to run under the debugger in a different shell window. For example: -\begin{verbatim} +\begin{lstlisting} cd .../regress/bin gdb bacula-sd (possibly set breakpoints, ...) run -s -f -\end{verbatim} +\end{lstlisting} Then enter any character in the window with the above message. An error message will appear saying that the daemon you are debugging diff --git a/docs/manuals/en/developers/smartall.tex b/docs/manuals/en/developers/smartall.tex index 9bb13845..9e3a4aeb 100644 --- a/docs/manuals/en/developers/smartall.tex +++ b/docs/manuals/en/developers/smartall.tex @@ -1,9 +1,7 @@ %% %% -\addcontentsline{lof}{figure}{Smart Memory Allocation with Orphaned Buffer -Detection} -\includegraphics{\idir smartall.eps} +%\addcontentsline{lof}{figure}{Smart Memory Allocation with Orphaned Buffer \chapter{Smart Memory Allocation} \label{_ChapterStart4} @@ -12,6 +10,7 @@ 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 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 @@ -85,9 +84,9 @@ leaves any buffers around when it's done, each will be reported by {\tt sm\_dump()} on stderr as follows: \footnotesize -\begin{verbatim} +\begin{lstlisting} Orphaned buffer: 120 bytes allocated at line 50 of gutshot.c -\end{verbatim} +\end{lstlisting} \normalsize \subsection{ Squelching a SMARTALLOC} @@ -110,9 +109,9 @@ calloc()}, and {\tt realloc()} is monitored by SMARTALLOC. If you make the function call: \footnotesize -\begin{verbatim} +\begin{lstlisting} sm_static(1); -\end{verbatim} +\end{lstlisting} \normalsize you declare that subsequent storage allocated by {\tt malloc()}, {\tt @@ -123,9 +122,9 @@ 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: \footnotesize -\begin{verbatim} +\begin{lstlisting} sm_static(0); -\end{verbatim} +\end{lstlisting} \normalsize to resume normal monitoring of buffer allocations. Buffers allocated while @@ -177,11 +176,11 @@ expects information placed in the buffer by SMARTALLOC's special version of should call {\tt actuallyfree()}, as in this code fragment: \footnotesize -\begin{verbatim} +\begin{lstlisting} struct image *ibuf = getimage("ratpack.img"); display_on_screen(ibuf); actuallyfree(ibuf); -\end{verbatim} +\end{lstlisting} \normalsize Conversely, suppose we are to call a library function, ``{\tt putimage()}'', @@ -193,12 +192,12 @@ following code uses {\tt actuallymalloc()} to obtain the buffer passed to such a routine. \footnotesize -\begin{verbatim} +\begin{lstlisting} struct image *obuf = (struct image *) actuallymalloc(sizeof(struct image)); dump_screen_to_image(obuf); putimage("scrdump.img", obuf); /* putimage() releases obuf */ -\end{verbatim} +\end{lstlisting} \normalsize It's unlikely you'll need any of the ``actually'' calls except under very odd @@ -220,13 +219,13 @@ corresponding functions within smartall.c instead. (For details of the redefinitions, please refer to smartall.h.) \footnotesize -\begin{verbatim} +\begin{lstlisting} void *malloc(size_t size) void *calloc(size_t nelem, size_t elsize) void *realloc(void *ptr, size_t size) void free(void *ptr) void cfree(void *ptr) -\end{verbatim} +\end{lstlisting} \normalsize {\tt cfree()} is a historical artifact identical to {\tt free()}. diff --git a/docs/manuals/en/developers/storage.tex b/docs/manuals/en/developers/storage.tex index e46f228c..046efd20 100644 --- a/docs/manuals/en/developers/storage.tex +++ b/docs/manuals/en/developers/storage.tex @@ -10,7 +10,7 @@ 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 system administrators that want or need to know more of the working details of -{\bf Bacula}. +{\bf Bacula}. This document is somewhat out of date. @@ -24,14 +24,14 @@ An individual Storage daemon is associated with a physical permanent storage device (for example, a tape drive, CD writer, tape changer or jukebox, etc.), and may employ auxiliary storage resources (such as space on a hard disk file system) to increase performance and/or optimize use of the permanent storage -medium. +medium. Any number of storage daemons may be run on a given machine; each associated with an individual storage device connected to it, and BACULA operations may employ storage daemons on any number of hosts connected by a network, local or remote. The ability to employ remote storage daemons (with appropriate security measures) permits automatic off-site backup, possibly to publicly -available backup repositories. +available backup repositories. \section{SD Development Outline} \index{Outline!SD Development } @@ -66,7 +66,7 @@ number of connections has been reached or the specified host is not granted access to the storage server. Once a connection has been opened, the client may make any number of Query requests, and/or initiate (if permitted), one or more Append sessions (which transmit data to be stored by the storage daemon) -and/or Read sessions (which retrieve data from the storage daemon). +and/or Read sessions (which retrieve data from the storage daemon). Most requests and replies sent across the connection are simple ASCII strings, with status replies prefixed by a four digit status code for easier parsing. @@ -75,13 +75,13 @@ request may result in a single-line status reply of ``{\tt 3201\ Notification\ pending}'', which indicates the client must send a ``Query notification'' request to retrieve one or more notifications posted to it. Once the notifications have been returned, the client may then resubmit the request -which resulted in the 3201 status. +which resulted in the 3201 status. The following descriptions omit common error codes, yet to be defined, which can occur from most or many requests due to events like media errors, 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. +produce them in an update to this document. \subsection{SD Append Requests} \index{Requests!SD Append } @@ -99,8 +99,8 @@ ticket\ =\ }{\it number}'' reply used to identify subsequent messages in the session. If too many sessions are open, or a conflicting session (for example, a read in progress when simultaneous read and append sessions are not permitted), a status of ``{\tt 3502\ Volume\ busy}'' is returned. If no -volume is mounted, or the volume mounted cannot be appended to, a status of -``{\tt 3503\ Volume\ not\ mounted}'' is returned. +volume is mounted, or the volume mounted cannot be appended to, a status of +``{\tt 3503\ Volume\ not\ mounted}'' is returned. \item [append data = \lt{}ticket-number\gt{} ] \index{SPAN class } @@ -109,31 +109,31 @@ volume is mounted, or the volume mounted cannot be appended to, a status of IPaddress} and {\tt port} specify the IP address and port number of the data channel. Error status codes are {\tt 3504\ Invalid\ ticket\ number} and {\tt 3505\ Session\ aborted}, the latter of which indicates the entire append -session has failed due to a daemon or media error. +session has failed due to a daemon or media error. -Once the File daemon has established the connection to the data channel +Once the File daemon has established the connection to the data channel opened by the Storage daemon, it will transfer a header packet followed by -any number of data packets. The header packet is of the form: +any number of data packets. The header packet is of the form: -{\tt \lt{}file-index\gt{} \lt{}stream-id\gt{} \lt{}info\gt{}} +{\tt \lt{}file-index\gt{} \lt{}stream-id\gt{} \lt{}info\gt{}} -The details are specified in the +The details are specified in the \ilink{Daemon Protocol}{_ChapterStart2} section of this -document. +document. \item [*append abort session = \lt{}ticket-number\gt{} ] \index{SPAN class } The open append session with ticket {\it ticket-number} is aborted; any blocks -not yet written to permanent media are discarded. Subsequent attempts to +not yet written to permanent media are discarded. Subsequent attempts to append data to the session will receive an error status of {\tt 3505\ -Session\ aborted}. +Session\ aborted}. \item [append end session = \lt{}ticket-number\gt{} ] \index{SPAN class } The open append session with ticket {\it ticket-number} is marked complete; no further blocks may be appended. The storage daemon will give priority to saving any buffered blocks from this session to permanent media as soon as -possible. +possible. \item [append close session = \lt{}ticket-number\gt{} ] \index{SPAN class } @@ -143,7 +143,7 @@ stored on permanent media, at which time said reply is given, followed by a list of volumes, from first to last, which contain blocks from the session, along with the first and last file and block on each containing session data and the volume session key identifying data from that session in lines with -the following format: +the following format: {\tt {\tt Volume = }\lt{}Volume-id\gt{} \lt{}start-file\gt{} \lt{}start-block\gt{} \lt{}end-file\gt{} \lt{}end-block\gt{} @@ -152,7 +152,7 @@ start-file} and {\it start-block} are the file and block containing the first data from that session on the volume, {\it end-file} and {\it end-block} are the file and block with the last data from the session on the volume and {\it volume-session-id} is the volume session ID for blocks from the session -stored on that volume. +stored on that volume. \end{description} \subsection{SD Read Requests} @@ -171,21 +171,21 @@ start-block} are the file and block containing the first data from that session on the volume, {\it end-file} and {\it end-block} are the file and block with the last data from the session on the volume and {\it volume-session-id} is the volume session ID for blocks from the session -stored on that volume. +stored on that volume. -If the session is successfully opened, a status of +If the session is successfully opened, a status of -{\tt {\tt 3100\ OK Ticket\ =\ }{\it number}``} +{\tt {\tt 3100\ OK Ticket\ =\ }{\it number}``} is returned with a reply used to identify subsequent messages in the session. If too many sessions are open, or a conflicting session (for example, an append in progress when simultaneous read and append sessions are not permitted), a status of ''{\tt 3502\ Volume\ busy}`` is returned. If no -volume is mounted, or the volume mounted cannot be appended to, a status of +volume is mounted, or the volume mounted cannot be appended to, a status of ''{\tt 3503\ Volume\ not\ mounted}`` is returned. If no block with the given volume session ID and the correct client ID number appears in the given first file and block for the volume, a status of ''{\tt 3505\ Session\ not\ -found}`` is returned. +found}`` is returned. \item [Read data = \lt{}Ticket\gt{} \gt{} \lt{}Block\gt{} ] \index{SPAN class } @@ -196,17 +196,17 @@ which immediately follows. Blocks must be retrieved in ascending order, but blocks may be skipped. If a block number greater than the largest stored on the volume is requested, a status of ''{\tt 3201\ End\ of\ volume}`` is returned. If a block number greater than the largest in the file is -requested, a status of ''{\tt 3401\ End\ of\ file}`` is returned. +requested, a status of ''{\tt 3401\ End\ of\ file}`` is returned. \item [Read close session = \lt{}Ticket\gt{} ] \index{SPAN class } The read session with Ticket number is closed. A read session may be closed -at any time; you needn't read all its blocks before closing it. +at any time; you needn't read all its blocks before closing it. \end{description} -{\it by +{\it by \elink{John Walker}{http://www.fourmilab.ch/} -January 30th, MM } +January 30th, MM } \section{SD Data Structures} \index{SD Data Structures} @@ -228,23 +228,23 @@ the primary way of interfacing to the physical device. The DCR contains all the job specific data as well as a pointer to the Device resource (DEVRES structure) and the physical DEVICE structure. -Now if a job is writing to two devices (it could be writing two separate -streams to the same device), it must have two DCRs. Today, the code only +Now if a job is writing to two devices (it could be writing two separate +streams to the same device), it must have two DCRs. Today, the code only permits one. This won't be hard to change, but it is new code. Today three jobs (threads), two physical devices each job writes to only one device: -\begin{verbatim} +\begin{lstlisting} Job1 -> DCR1 -> DEVICE1 Job2 -> DCR2 -> DEVICE1 Job3 -> DCR3 -> DEVICE2 -\end{verbatim} +\end{lstlisting} To be implemented three jobs, three physical devices, but job1 is writing simultaneously to three devices: -\begin{verbatim} +\begin{lstlisting} Job1 -> DCR1 -> DEVICE1 -> DCR4 -> DEVICE2 -> DCR5 -> DEVICE3 @@ -254,5 +254,5 @@ To be implemented three jobs, three physical devices, but Job = job control record DCR = Job contorl data for a specific device DEVICE = Device only control data -\end{verbatim} +\end{lstlisting} diff --git a/docs/manuals/en/developers/table_databasetables.tex b/docs/manuals/en/developers/table_databasetables.tex new file mode 100644 index 00000000..c69a4c05 --- /dev/null +++ b/docs/manuals/en/developers/table_databasetables.tex @@ -0,0 +1,15 @@ +\begin{longtable}{|X|l|l|} +\caption{Filename table} \\ +\endlastfoot + \hline + \multicolumn{3}{|l|}{\bf Filename } \\ + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \hline + FilenameId & integer & Primary Key \\ + \hline + Name & Blob & Filename \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbbasefiles.tex b/docs/manuals/en/developers/table_dbbasefiles.tex new file mode 100644 index 00000000..b6990c81 --- /dev/null +++ b/docs/manuals/en/developers/table_dbbasefiles.tex @@ -0,0 +1,27 @@ +\begin{longtable}{|l|l|X|} + \caption{Base Files Table Layout}\label{table:dbbasefiles} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + BaseId & integer & Primary Key \\ + \hline + BaseJobId & integer & JobId of Base Job \\ + \hline + JobId & integer & Reference to Job \\ + \hline + FileId & integer & Reference to File \\ + \hline + FileIndex & integer & File Index number \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbclient.tex b/docs/manuals/en/developers/table_dbclient.tex new file mode 100644 index 00000000..dfd18f57 --- /dev/null +++ b/docs/manuals/en/developers/table_dbclient.tex @@ -0,0 +1,29 @@ +\begin{longtable}{|l|l|X|} + \caption{Client Table Layout}\label{table:dbclient} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + ClientId & integer & Primary Key \\ + \hline + Name & TinyBlob & File Services Name \\ + \hline + UName & TinyBlob & uname -a from Client (not yet used) \\ + \hline + AutoPrune & tinyint & yes|no for autopruning \\ + \hline + FileRetention & bigint & 64 bit seconds to retain Files \\ + \hline + JobRetention & bigint & 64 bit seconds to retain Job \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbcounter.tex b/docs/manuals/en/developers/table_dbcounter.tex new file mode 100644 index 00000000..124edc95 --- /dev/null +++ b/docs/manuals/en/developers/table_dbcounter.tex @@ -0,0 +1,27 @@ +\begin{longtable}{|l|l|X|} + \caption{Counter Table Layout}\label{table:dbcounter} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + Counter & tinyblob & Counter name \\ + \hline + MinValue & integer & Start/Min value for counter \\ + \hline + MaxValue & integer & Max value for counter \\ + \hline + CurrentValue & integer & Current counter value \\ + \hline + WrapCounter & tinyblob & Name of another counter \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbfile.tex b/docs/manuals/en/developers/table_dbfile.tex new file mode 100644 index 00000000..fa276468 --- /dev/null +++ b/docs/manuals/en/developers/table_dbfile.tex @@ -0,0 +1,25 @@ +\begin{longtable}{|l|l|X|} +\caption{File Table Layout}\label{table:dbfile} \\ +\endlastfoot +\hline +\multicolumn{1}{|c|}{\bf Column Name} +& \multicolumn{1}{c|}{\bf Data Type} +& \multicolumn{1}{c|}{\bf Remark} \\ +\hline +FileId & integer & Primary Key \\ +\hline +FileIndex & integer & The sequential file number in the Job \\ +\hline +JobId & integer & Link to Job Record \\ +\hline +PathId & integer & Link to Path Record \\ +\hline +FilenameId & integer & Link to Filename Record \\ +\hline +MarkId & integer & Used to mark files during Verify Jobs \\ +\hline +LStat & tinyblob & File attributes in base64 encoding \\ +\hline +MD5 & tinyblob & MD5/SHA1 signature in base64 encoding \\ +\hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbfilename.tex b/docs/manuals/en/developers/table_dbfilename.tex new file mode 100644 index 00000000..c3b8fd63 --- /dev/null +++ b/docs/manuals/en/developers/table_dbfilename.tex @@ -0,0 +1,13 @@ +\begin{longtable}{|l|l|X|} + \caption{Filename table}\label{table:dbfilename} \\ + \endlastfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \hline + FilenameId & integer & Primary Key \\ + \hline + Name & Blob & Filename \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbfileset.tex b/docs/manuals/en/developers/table_dbfileset.tex new file mode 100644 index 00000000..fe137472 --- /dev/null +++ b/docs/manuals/en/developers/table_dbfileset.tex @@ -0,0 +1,25 @@ +\begin{longtable}{|l|l|X|} + \caption{File Sets Table Layout}\label{table:dbfileset} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + FileSetId & integer & Primary Key \\ + \hline + FileSet & tinyblob & FileSet name \\ + \hline + MD5 & tinyblob & MD5 checksum of FileSet \\ + \hline + CreateTime & datetime & Time and date Fileset created \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbjob.tex b/docs/manuals/en/developers/table_dbjob.tex new file mode 100644 index 00000000..3fe7e10a --- /dev/null +++ b/docs/manuals/en/developers/table_dbjob.tex @@ -0,0 +1,65 @@ +\begin{longtable}{|l|l|X|} + \caption{Job Table Layout}\label{table:dbjob} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endhead + \hline + JobId & integer & Primary Key \\ + \hline + Job & tinyblob & Unique Job Name \\ + \hline + Name & tinyblob & Job Name \\ + \hline + PurgedFiles & tinyint & Used by Bacula for purging/retention periods \\ + \hline + Type & binary(1) & Job Type: Backup, Copy, Clone, Archive, Migration \\ + \hline + Level & binary(1) & Job Level \\ + \hline + ClientId & integer & Client index \\ + \hline + JobStatus & binary(1) & Job Termination Status \\ + \hline + SchedTime & datetime & Time/date when Job scheduled \\ + \hline + StartTime & datetime & Time/date when Job started \\ + \hline + EndTime & datetime & Time/date when Job ended \\ + \hline + RealEndTime & datetime & Time/date when original Job ended \\ + \hline + JobTDate & bigint & Start day in Unix format but 64 bits; used for Retention period. \\ + \hline + VolSessionId & integer & Unique Volume Session ID \\ + \hline + VolSessionTime & integer & Unique Volume Session Time \\ + \hline + JobFiles & integer & Number of files saved in Job \\ + \hline + JobBytes & bigint & Number of bytes saved in Job \\ + \hline + JobErrors & integer & Number of errors during Job \\ + \hline + JobMissingFiles & integer & Number of files not saved (not yet used) \\ + \hline + PoolId & integer & Link to Pool Record \\ + \hline + FileSetId & integer & Link to FileSet Record \\ + \hline + PrioJobId & integer & Link to prior Job Record when migrated \\ + \hline + PurgedFiles & tiny integer & Set when all File records purged \\ + \hline + HasBase & tiny integer & Set when Base Job run \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbjobhistory.tex b/docs/manuals/en/developers/table_dbjobhistory.tex new file mode 100644 index 00000000..c35f11d4 --- /dev/null +++ b/docs/manuals/en/developers/table_dbjobhistory.tex @@ -0,0 +1,67 @@ +\begin{longtable}{|l|l|X|} + \caption{Job History Table Layout}\label{table:dbjobhistory} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline +JobId & integer & Primary Key \\ + \hline +Job & tinyblob & Unique Job Name \\ + \hline +Name & tinyblob & Job Name \\ + \hline +Type & binary(1) & Job Type: Backup, Copy, Clone, Archive, Migration + \\ + \hline +Level & binary(1) & Job Level \\ + \hline +ClientId & integer & Client index \\ + \hline +JobStatus & binary(1) & Job Termination Status \\ + \hline +SchedTime & datetime & Time/date when Job scheduled \\ + \hline +StartTime & datetime & Time/date when Job started \\ + \hline +EndTime & datetime & Time/date when Job ended \\ + \hline +RealEndTime & datetime & Time/date when original Job ended \\ + \hline +JobTDate & bigint & Start day in Unix format but 64 bits; used for +Retention period. \\ + \hline +VolSessionId & integer & Unique Volume Session ID \\ + \hline +VolSessionTime & integer & Unique Volume Session Time \\ + \hline +JobFiles & integer & Number of files saved in Job \\ + \hline +JobBytes & bigint & Number of bytes saved in Job \\ + \hline +JobErrors & integer & Number of errors during Job \\ + \hline +JobMissingFiles & integer & Number of files not saved (not yet used) +\\ + \hline +PoolId & integer & Link to Pool Record \\ + \hline +FileSetId & integer & Link to FileSet Record \\ + \hline +PrioJobId & integer & Link to prior Job Record when migrated \\ + \hline +PurgedFiles & tiny integer & Set when all File records purged \\ + \hline +HasBase & tiny integer & Set when Base Job run +\\ \hline + +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbjobmedia.tex b/docs/manuals/en/developers/table_dbjobmedia.tex new file mode 100644 index 00000000..3c1464e0 --- /dev/null +++ b/docs/manuals/en/developers/table_dbjobmedia.tex @@ -0,0 +1,37 @@ +\begin{longtable}{|l|l|X|} + \caption{JobMedia Table Layout}\label{table:dbjobmedia} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + JobMediaId & integer & Primary Key \\ + \hline + JobId & integer & Link to Job Record \\ + \hline + MediaId & integer & Link to Media Record \\ + \hline + FirstIndex & integer & The index (sequence number) of the first file written for this Job to the Media \\ + \hline + LastIndex & integer & The index of the last file written for this Job to the Media \\ + \hline + StartFile & integer & The physical media (tape) file number of the first block written for this Job \\ + \hline + EndFile & integer & The physical media (tape) file number of the last block written for this Job \\ + \hline + StartBlock & integer & The number of the first block written for this Job \\ + \hline + EndBlock & integer & The number of the last block written for this Job \\ + \hline + VolIndex & integer & The Volume use sequence number within the Job \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbjobstatuses.tex b/docs/manuals/en/developers/table_dbjobstatuses.tex new file mode 100644 index 00000000..f5255e31 --- /dev/null +++ b/docs/manuals/en/developers/table_dbjobstatuses.tex @@ -0,0 +1,64 @@ +\begin{longtable}{|c|X|} + \caption{Job Statuses}\label{table:dbjobstatuses} \\ + \endlastfoot + \multicolumn{2}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Value} + & \multicolumn{1}{c|}{\bf Meaning} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Value} + & \multicolumn{1}{c|}{\bf Meaning} \\ + \endhead + C & Created but not yet running \\ + \hline + R & Running \\ + \hline + B & Blocked \\ + \hline + T & Terminated normally \\ + \hline + W & Terminated normally with warnings \\ + \hline + E & Terminated in Error \\ + \hline + e & Non-fatal error \\ + \hline + f & Fatal error \\ + \hline + D & Verify Differences \\ + \hline + A & Canceled by the user \\ + \hline + I & Incomplete Job \\ + \hline + F & Waiting on the File daemon \\ + \hline + S & Waiting on the Storage daemon \\ + \hline + m & Waiting for a new Volume to be mounted \\ + \hline + M & Waiting for a Mount \\ + \hline + s & Waiting for Storage resource \\ + \hline + j & Waiting for Job resource \\ + \hline + c & Waiting for Client resource \\ + \hline + d & Wating for Maximum jobs \\ + \hline + t & Waiting for Start Time \\ + \hline + p & Waiting for higher priority job to finish \\ + \hline + i & Doing batch insert file records \\ + \hline + a & SD despooling attributes \\ + \hline + l & Doing data despooling \\ + \hline + L & Committing data (last despool) \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbjobtypes.tex b/docs/manuals/en/developers/table_dbjobtypes.tex new file mode 100644 index 00000000..c17f2501 --- /dev/null +++ b/docs/manuals/en/developers/table_dbjobtypes.tex @@ -0,0 +1,35 @@ +\begin{longtable}{|c|X|} + \caption{Job Types}\label{table:dbjobtypes} \\ + \endlastfoot + \multicolumn{2}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Value} + & \multicolumn{1}{c|}{\bf Meaning} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Value} + & \multicolumn{1}{c|}{\bf Meaning} \\ + \endhead + \hline + B & Backup Job \\ + \hline + M & Migrated Job \\ + \hline + V & Verify Job \\ + \hline + R & Restore Job \\ + \hline + C & Console program (not in database) \\ + \hline + I & Internal or system Job \\ + \hline + D & Admin Job \\ + \hline + A & Archive Job (not implemented) \\ + \hline + C & Copy Job \\ + \hline + g & Migration Job \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dblocation.tex b/docs/manuals/en/developers/table_dblocation.tex new file mode 100644 index 00000000..82e973bf --- /dev/null +++ b/docs/manuals/en/developers/table_dblocation.tex @@ -0,0 +1,25 @@ +\begin{longtable}{|l|l|X|} + \caption{Location Table Layout}\label{table:dblocation} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + LocationId & integer & Primary Key \\ + \hline + Location & tinyblob & Text defining location \\ + \hline + Cost & integer & Relative cost of obtaining Volume \\ + \hline + Enabled & tinyint & Whether or not Volume is enabled \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dblocationlog.tex b/docs/manuals/en/developers/table_dblocationlog.tex new file mode 100644 index 00000000..e0a2c6d5 --- /dev/null +++ b/docs/manuals/en/developers/table_dblocationlog.tex @@ -0,0 +1,29 @@ +\begin{longtable}{|l|l|X|} + \caption{Location Log Table Layout}\label{table:dblocationlog} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + locLogIdId & integer & Primary Key \\ + \hline + Date & datetime & Time/date log record created \\ + \hline + MediaId & integer & Points to Media record \\ + \hline + LocationId & integer & Points to Location record \\ + \hline + NewVolStatus & integer & enum: Full, Archive, Append, Recycle, Purged Read-only, Disabled, Error, Busy, Used, Cleaning \\ + \hline + Enabled & tinyint & Whether or not Volume is enabled \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dblog.tex b/docs/manuals/en/developers/table_dblog.tex new file mode 100644 index 00000000..f2c3a294 --- /dev/null +++ b/docs/manuals/en/developers/table_dblog.tex @@ -0,0 +1,25 @@ +\begin{longtable}{|l|l|X|} + \caption{Log Table Layout}\label{table:dblog} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + LogIdId & integer & Primary Key \\ + \hline + JobId & integer & Points to Job record \\ + \hline + Time & datetime & Time/date log record created \\ + \hline + LogText & blob & Log text \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbmedia.tex b/docs/manuals/en/developers/table_dbmedia.tex new file mode 100644 index 00000000..d4ff5f73 --- /dev/null +++ b/docs/manuals/en/developers/table_dbmedia.tex @@ -0,0 +1,101 @@ +\begin{longtable}{|l|l|X|} + \caption{Media Table Layout}\label{table:dbmedia} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + MediaId & integer & Primary Key \\ + \hline + VolumeName & tinyblob & Volume name \\ + \hline + Slot & integer & Autochanger Slot number or zero \\ + \hline + PoolId & integer & Link to Pool Record \\ + \hline + MediaType & tinyblob & The MediaType supplied by the user \\ + \hline + MediaTypeId & integer & The MediaTypeId \\ + \hline + LabelType & tinyint & The type of label on the Volume \\ + \hline + FirstWritten & datetime & Time / date when first written \\ + \hline + LastWritten & datetime & Time/date when last written \\ + \hline + LabelDate & datetime & Time/date when tape labeled \\ + \hline + VolJobs & integer & Number of jobs written to this media \\ + \hline + VolFiles & integer & Number of files written to this media \\ + \hline + VolBlocks & integer & Number of blocks written to this media \\ + \hline + VolMounts & integer & Number of time media mounted \\ + \hline + VolBytes & bigint & Number of bytes saved in Job \\ + \hline + VolParts & integer & The number of parts for a Volume (DVD) \\ + \hline + VolErrors & integer & Number of errors during Job \\ + \hline + VolWrites & integer & Number of writes to media \\ + \hline + MaxVolBytes & bigint & Maximum bytes to put on this media \\ + \hline + VolCapacityBytes & bigint & Capacity estimate for this volume \\ + \hline + VolStatus & enum & Status of media: Full, Archive, Append, Recycle, Read-Only, Disabled, Error, Busy \\ + \hline + Enabled & tinyint & Whether or not Volume can be written \\ + \hline + Recycle & tinyint & Whether or not Bacula can recycle the Volumes: Yes, No \\ + \hline + ActionOnPurge & tinyint & What happens to a Volume after purging \\ + \hline + VolRetention & bigint & 64 bit seconds until expiration \\ + \hline + VolUseDuration & bigint & 64 bit seconds volume can be used \\ + \hline + MaxVolJobs & integer & maximum jobs to put on Volume \\ + \hline + MaxVolFiles & integer & maximume EOF marks to put on Volume \\ + \hline + InChanger & tinyint & Whether or not Volume in autochanger \\ + \hline + StorageId & integer & Storage record ID \\ + \hline + DeviceId & integer & Device record ID \\ + \hline + MediaAddressing & integer & Method of addressing media \\ + \hline + VolReadTime & bigint & Time Reading Volume \\ + \hline + VolWriteTime & bigint & Time Writing Volume \\ + \hline + EndFile & integer & End File number of Volume \\ + \hline + EndBlock & integer & End block number of Volume \\ + \hline + LocationId & integer & Location record ID \\ + \hline + RecycleCount & integer & Number of times recycled \\ + \hline + InitialWrite & datetime & When Volume first written \\ + \hline + ScratchPoolId & integer & Id of Scratch Pool \\ + \hline + RecyclePoolId & integer & Pool ID where to recycle Volume \\ + \hline + Comment & blob & User text field \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbpath.tex b/docs/manuals/en/developers/table_dbpath.tex new file mode 100644 index 00000000..47d1e223 --- /dev/null +++ b/docs/manuals/en/developers/table_dbpath.tex @@ -0,0 +1,21 @@ +\begin{longtable}{|l|l|X|} + \caption{Path Table Layout}\label{table:dbpath} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + PathId & integer & Primary Key \\ + \hline + Path & Blob & Full Path \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbpool.tex b/docs/manuals/en/developers/table_dbpool.tex new file mode 100644 index 00000000..4b5b2fad --- /dev/null +++ b/docs/manuals/en/developers/table_dbpool.tex @@ -0,0 +1,67 @@ +\begin{longtable}{|l|l|X|} + \caption{Pool Table Layout}\label{table:dbpool} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline + PoolId & integer & Primary Key \\ + \hline + Name & Tinyblob & Pool Name \\ + \hline + NumVols & Integer & Number of Volumes in the Pool \\ + \hline + MaxVols & Integer & Maximum Volumes in the Pool \\ + \hline + UseOnce & tinyint & Use volume once \\ + \hline + UseCatalog & tinyint & Set to use catalog \\ + \hline + AcceptAnyVolume & tinyint & Accept any volume from Pool \\ + \hline + VolRetention & bigint & 64 bit seconds to retain volume \\ + \hline + VolUseDuration & bigint & 64 bit seconds volume can be used \\ + \hline + MaxVolJobs & integer & max jobs on volume \\ + \hline + MaxVolFiles & integer & max EOF marks to put on Volume \\ + \hline + MaxVolBytes & bigint & max bytes to write on Volume \\ + \hline + AutoPrune & tinyint & yes|no for autopruning \\ + \hline + Recycle & tinyint & yes|no for allowing auto recycling of Volume \\ + \hline + ActionOnPurge & tinyint & Default Volume ActionOnPurge \\ + \hline + PoolType & enum & Backup, Copy, Cloned, Archive, Migration \\ + \hline + LabelType & tinyint & Type of label ANSI / Bacula \\ + \hline + LabelFormat & Tinyblob & Label format \\ + \hline + Enabled & tinyint & Whether or not Volume can be written \\ + \hline + ScratchPoolId & integer & Id of Scratch Pool \\ + \hline + RecyclePoolId & integer & Pool ID where to recycle Volume \\ + \hline + NextPoolId & integer & Pool ID of next Pool \\ + \hline + MigrationHighBytes & bigint & High water mark for migration \\ + \hline + MigrationLowBytes & bigint & Low water mark for migration \\ + \hline + MigrationTime & bigint & Time before migration \\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbstorage.tex b/docs/manuals/en/developers/table_dbstorage.tex new file mode 100644 index 00000000..291dbd48 --- /dev/null +++ b/docs/manuals/en/developers/table_dbstorage.tex @@ -0,0 +1,24 @@ +\begin{longtable}{|l|l|X|} + \caption{Storage Table Layout}\label{table:dbstorage} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline +StorageId & integer & Unique Id \\ + \hline +Name & tinyblob & Resource name of Storage device \\ + \hline +AutoChanger & tinyint & Set if it is an autochanger \\ + \hline + +\end{longtable} diff --git a/docs/manuals/en/developers/table_dbversion.tex b/docs/manuals/en/developers/table_dbversion.tex new file mode 100644 index 00000000..b6f52a14 --- /dev/null +++ b/docs/manuals/en/developers/table_dbversion.tex @@ -0,0 +1,19 @@ +\begin{longtable}{|l|l|X|} + \caption{Version Table Layout}\label{table:dbversion} \\ + \endlastfoot + \multicolumn{3}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark} \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Column Name} + & \multicolumn{1}{l|}{\bf Data Type} + & \multicolumn{1}{l|}{\bf Remark } \\ + \endhead + \hline +VersionId & integer & Primary Key \\ +\hline +\end{longtable} diff --git a/docs/manuals/en/developers/table_fileattributes.tex b/docs/manuals/en/developers/table_fileattributes.tex new file mode 100644 index 00000000..e627498d --- /dev/null +++ b/docs/manuals/en/developers/table_fileattributes.tex @@ -0,0 +1,47 @@ +\begin{longtable}{|c|c|p{2cm}|p{2cm}|p{2cm}|} + \caption{File Attributes}\label{table:fileattributes} \\ + \endlastfoot + \multicolumn{5}{c}{Cont. on next page} \\ + \endfoot + \hline + \multicolumn{1}{|c|}{\bf Field No.} + & \multicolumn{1}{c|}{\bf Stat Name} + & \multicolumn{1}{c|}{\bf Unix} + & \multicolumn{1}{c|}{\bf Win98 / NT} + & \multicolumn{1}{c|}{\bf MacOS } \\ + \endfirsthead + \hline + \multicolumn{1}{|c|}{\bf Field No.} + & \multicolumn{1}{c|}{\bf Stat Name} + & \multicolumn{1}{c|}{\bf Unix} + & \multicolumn{1}{c|}{\bf Win98 / NT} + & \multicolumn{1}{c|}{\bf MacOS} \\ + \endhead + \hline + 1 & st\_dev & Device number of filesystem & Drive number & vRefNum \\ + \hline + 2 & st\_ino & Inode number & Always 0 & fileID / dirID \\ + \hline + 3 & st\_mode & File mode & File mode & 777 dirs / apps; 666 docs; 444 locked docs \\ + \hline + 4 & st\_nlink & Number of links to the file & Number of link (only on NTFS) & Always 1 \\ + \hline + 5 & st\_uid & Owner ID & Always 0 & Always 0 \\ + \hline + 6 & st\_gid & Group ID & Always 0 &Always 0 \\ + \hline + 7 & st\_rdev & Device ID for special files & Drive No. & Always 0 \\ + \hline + 8 & st\_size & File size in bytes & File size in bytes & Data fork file size in bytes \\ + \hline + 9 & st\_blksize & Preferred block size & Always 0 & Preferred block size \\ + \hline + 10 & st\_blocks & Number of blocks allocated & Always 0 & Number of blocks allocated \\ + \hline + 11 & st\_atime & Last access time since epoch & Last access time since epoch & Last access time -66 years \\ + \hline + 12 & st\_mtime & Last modify time since epoch & Last modify time since epoch & Last access time -66 years \\ + \hline + 13 & st\_ctime & Inode change time since epoch & File create time since epoch & File create time -66 years\\ + \hline +\end{longtable} diff --git a/docs/manuals/en/developers/tls-techdoc.tex b/docs/manuals/en/developers/tls-techdoc.tex index 565869f1..8f36a154 100644 --- a/docs/manuals/en/developers/tls-techdoc.tex +++ b/docs/manuals/en/developers/tls-techdoc.tex @@ -21,12 +21,12 @@ 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{itemize} +\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 -\end{itemize} +\end{bsysitemize} This document will refer to both ``server'' and ``client'' contexts. These terms refer to the accepting and initiating peer, respectively. @@ -52,7 +52,7 @@ implementations. Additional configuration directives have been added to both the Console and Director resources. These new directives are defined as follows: -\begin{itemize} +\begin{bsysitemize} \item \underline{TLS Enable} \emph{(yes/no)} Enable TLS support. @@ -99,11 +99,11 @@ 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{verbatim} +\begin{lstlisting} openssl dhparam -out dh1024.pem -5 1024 -\end{verbatim} +\end{lstlisting} \normalsize -\end{itemize} +\end{bsysitemize} \section{TLS API Implementation} \index{TLS API Implimentation} @@ -120,18 +120,18 @@ TLS API is exported. \addcontentsline{toc}{subsection}{Library Initialization and Cleanup} \footnotesize -\begin{verbatim} +\begin{lstlisting} int init_tls (void); -\end{verbatim} +\end{lstlisting} \normalsize Performs TLS library initialization, including seeding of the PRNG. PRNG seeding has not yet been implemented for win32. \footnotesize -\begin{verbatim} +\begin{lstlisting} int cleanup_tls (void); -\end{verbatim} +\end{lstlisting} \normalsize Performs TLS library cleanup. @@ -142,11 +142,11 @@ Performs TLS library cleanup. \addcontentsline{toc}{subsection}{Manipulating TLS Contexts} \footnotesize -\begin{verbatim} +\begin{lstlisting} TLS_CONTEXT *new_tls_context (const char *ca_certfile, const char *ca_certdir, const char *certfile, const char *keyfile, const char *dhfile, bool verify_peer); -\end{verbatim} +\end{lstlisting} \normalsize Allocates and initalizes a new opaque \emph{TLS\_CONTEXT} structure. The @@ -161,9 +161,9 @@ Diffie-Hellman ephemeral keying. If \emph{verify\_peer} is \emph{true} , client certificate validation is enabled. \footnotesize -\begin{verbatim} +\begin{lstlisting} void free_tls_context (TLS_CONTEXT *ctx); -\end{verbatim} +\end{lstlisting} \normalsize Deallocated a previously allocated \emph{TLS\_CONTEXT} structure. @@ -174,9 +174,9 @@ Deallocated a previously allocated \emph{TLS\_CONTEXT} structure. \addcontentsline{toc}{subsection}{Performing Post-Connection Verification} \footnotesize -\begin{verbatim} +\begin{lstlisting} bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host); -\end{verbatim} +\end{lstlisting} \normalsize Performs post-connection verification of the peer-supplied x509 @@ -185,9 +185,9 @@ certificate. Checks whether the \emph{subjectAltName} and Returns \emph{true} if there is a match, \emph{false} otherwise. \footnotesize -\begin{verbatim} +\begin{lstlisting} bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list); -\end{verbatim} +\end{lstlisting} \normalsize Performs post-connection verification of the peer-supplied x509 @@ -201,26 +201,26 @@ strings supplied via the \emph{verify\_list} parameter. Returns \addcontentsline{toc}{subsection}{Manipulating TLS Connections} \footnotesize -\begin{verbatim} +\begin{lstlisting} TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd); -\end{verbatim} +\end{lstlisting} \normalsize Allocates and initializes a new \emph{TLS\_CONNECTION} structure with context \emph{ctx} and file descriptor \emph{fd}. \footnotesize -\begin{verbatim} +\begin{lstlisting} void free_tls_connection (TLS_CONNECTION *tls); -\end{verbatim} +\end{lstlisting} \normalsize Deallocates memory associated with the \emph{tls} structure. \footnotesize -\begin{verbatim} +\begin{lstlisting} bool tls_bsock_connect (BSOCK *bsock); -\end{verbatim} +\end{lstlisting} \normalsize Negotiates a a TLS client connection via \emph{bsock}. Returns \emph{true} @@ -228,9 +228,9 @@ if successful, \emph{false} otherwise. Will fail if there is a TLS protocol error or an invalid certificate is presented \footnotesize -\begin{verbatim} +\begin{lstlisting} bool tls_bsock_accept (BSOCK *bsock); -\end{verbatim} +\end{lstlisting} \normalsize Accepts a TLS client connection via \emph{bsock}. Returns \emph{true} if @@ -238,17 +238,17 @@ successful, \emph{false} otherwise. Will fail if there is a TLS protocol error or an invalid certificate is presented. \footnotesize -\begin{verbatim} +\begin{lstlisting} bool tls_bsock_shutdown (BSOCK *bsock); -\end{verbatim} +\end{lstlisting} \normalsize Issues a blocking TLS shutdown request to the peer via \emph{bsock}. This function may not wait for the peer's reply. \footnotesize -\begin{verbatim} +\begin{lstlisting} int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes); -\end{verbatim} +\end{lstlisting} \normalsize Writes \emph{nbytes} from \emph{ptr} via the \emph{TLS\_CONNECTION} @@ -259,9 +259,9 @@ to its original blocking state before the function returns. Less than bytes written will be returned. \footnotesize -\begin{verbatim} +\begin{lstlisting} int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes); -\end{verbatim} +\end{lstlisting} \normalsize Reads \emph{nbytes} from the \emph{TLS\_CONNECTION} associated with @@ -291,18 +291,18 @@ possible to discern the current blocking state of a socket. implemented using the new TLS API as follows: \footnotesize -\begin{verbatim} +\begin{lstlisting} int bnet_tls_client(TLS_CONTEXT *ctx, BSOCK * bsock); -\end{verbatim} +\end{lstlisting} \normalsize Negotiates a TLS session via \emph{bsock} using the settings from \emph{ctx}. Returns 1 if successful, 0 otherwise. \footnotesize -\begin{verbatim} +\begin{lstlisting} int bnet_tls_server(TLS_CONTEXT *ctx, BSOCK * bsock, alist *verify_list); -\end{verbatim} +\end{lstlisting} \normalsize Accepts a TLS client session via \emph{bsock} using the settings from @@ -322,27 +322,27 @@ to the MSDN documentation, but has not been tested. These functions are prototyped as follows: \footnotesize -\begin{verbatim} +\begin{lstlisting} int bnet_set_nonblocking (BSOCK *bsock); -\end{verbatim} +\end{lstlisting} \normalsize Enables non-blocking I/O on the socket associated with \emph{bsock}. Returns a copy of the socket flags prior to modification. \footnotesize -\begin{verbatim} +\begin{lstlisting} int bnet_set_blocking (BSOCK *bsock); -\end{verbatim} +\end{lstlisting} \normalsize Enables blocking I/O on the socket associated with \emph{bsock}. Returns a copy of the socket flags prior to modification. \footnotesize -\begin{verbatim} +\begin{lstlisting} void bnet_restore_blocking (BSOCK *bsock, int flags); -\end{verbatim} +\end{lstlisting} \normalsize Restores blocking or non-blocking IO setting on the socket associated with @@ -366,7 +366,7 @@ After exchanging cram-md5 authentication and TLS requirements, both the client and server independently decide whether to continue: \footnotesize -\begin{verbatim} +\begin{lstlisting} if (!cram_md5_get_auth(dir, password, &tls_remote_need) || !cram_md5_auth(dir, password, tls_local_need)) { [snip] @@ -387,5 +387,5 @@ if (tls_remote_need > tls_local_need && tls_local_need != BNET_TLS_OK && auth_success = false; goto auth_done; } -\end{verbatim} +\end{lstlisting} \normalsize