en/developers/developers.toc

\babel@toc {english}{}
\contentsline {chapter}{\numberline {1}Bacula{} Developer Notes}{1}{chapter.1}%
\contentsline {section}{\numberline {1.1}Contributions}{1}{section.1.1}%
\contentsline {section}{\numberline {1.2}Patches}{1}{section.1.2}%
\contentsline {section}{\numberline {1.3}Copyrights}{2}{section.1.3}%
\contentsline {section}{\numberline {1.4}Copyright Assignment -- Fiduciary License Agreement}{2}{section.1.4}%
\contentsline {section}{\numberline {1.5}The Development Cycle}{3}{section.1.5}%
\contentsline {subsection}{\numberline {1.5.1}Feature Requests}{3}{subsection.1.5.1}%
\contentsline {subsubsection}{Implementation of Feature Requests}{4}{section*.5}%
\contentsline {subsubsection}{How Feature Requests are accepted}{4}{section*.6}%
\contentsline {subsubsection}{How Feature Requests are prioritized}{4}{section*.7}%
\contentsline {section}{\numberline {1.6}Bacula{} Code Submissions and Projects}{5}{section.1.6}%
\contentsline {section}{\numberline {1.7}Patches for Released Versions}{5}{section.1.7}%
\contentsline {section}{\numberline {1.8}Developing Bacula{}}{6}{section.1.8}%
\contentsline {section}{\numberline {1.9}Debugging}{7}{section.1.9}%
\contentsline {section}{\numberline {1.10}Using a Debugger}{7}{section.1.10}%
\contentsline {section}{\numberline {1.11}Memory Leaks}{7}{section.1.11}%
\contentsline {section}{\numberline {1.12}Special Files}{8}{section.1.12}%
\contentsline {section}{\numberline {1.13}When Implementing Incomplete Code}{8}{section.1.13}%
\contentsline {subsection}{\numberline {1.13.1}Bacula{} Source File Structure}{8}{subsection.1.13.1}%
\contentsline {section}{\numberline {1.14}Header Files}{9}{section.1.14}%
\contentsline {section}{\numberline {1.15}Programming Standards}{9}{section.1.15}%
\contentsline {section}{\numberline {1.16}Do Not Use}{10}{section.1.16}%
\contentsline {section}{\numberline {1.17}Avoid if Possible}{10}{section.1.17}%
\contentsline {section}{\numberline {1.18}Do Use Whenever Possible}{10}{section.1.18}%
\contentsline {section}{\numberline {1.19}Indenting Standards}{11}{section.1.19}%
\contentsline {section}{\numberline {1.20}Naming Convention}{12}{section.1.20}%
\contentsline {section}{\numberline {1.21}Locks and Threads}{13}{section.1.21}%
\contentsline {section}{\numberline {1.22}Tabbing}{14}{section.1.22}%
\contentsline {section}{\numberline {1.23}Don'ts}{14}{section.1.23}%
\contentsline {paragraph}{Note}{15}{section*.8}%
\contentsline {section}{\numberline {1.24}Message Classes}{15}{section.1.24}%
\contentsline {section}{\numberline {1.25}Debug Messages}{15}{section.1.25}%
\contentsline {subsection}{\numberline {1.25.1}Debug Tags}{16}{subsection.1.25.1}%
\contentsline {section}{\numberline {1.26}Error Messages}{16}{section.1.26}%
\contentsline {section}{\numberline {1.27}Job Messages}{17}{section.1.27}%
\contentsline {section}{\numberline {1.28}Queued Job Messages}{17}{section.1.28}%
\contentsline {section}{\numberline {1.29}Memory Messages}{17}{section.1.29}%
\contentsline {section}{\numberline {1.30}Bugs Database}{18}{section.1.30}%
\contentsline {chapter}{\numberline {2}Bacula Git Usage}{19}{chapter.2}%
\contentsline {section}{\numberline {2.1}Bacula Git repositories}{19}{section.2.1}%
\contentsline {section}{\numberline {2.2}Git Usage}{19}{section.2.2}%
\contentsline {subsection}{\numberline {2.2.1}Learning Git}{20}{subsection.2.2.1}%
\contentsline {section}{\numberline {2.3}Step by Step Modifying Bacula Code}{21}{section.2.3}%
\contentsline {subsection}{\numberline {2.3.1}More Details}{23}{subsection.2.3.1}%
\contentsline {section}{\numberline {2.4}Forcing Changes}{24}{section.2.4}%
\contentsline {chapter}{\numberline {3}Bacula FD Plugin API}{27}{chapter.3}%
\contentsline {section}{\numberline {3.1}Normal vs Command vs Options Plugins}{27}{section.3.1}%
\contentsline {section}{\numberline {3.2}Loading Plugins}{28}{section.3.2}%
\contentsline {section}{\numberline {3.3}loadPlugin}{29}{section.3.3}%
\contentsline {section}{\numberline {3.4}Plugin Entry Points}{31}{section.3.4}%
\contentsline {subsection}{\numberline {3.4.1}newPlugin(bpContext *ctx)}{31}{subsection.3.4.1}%
\contentsline {subsection}{\numberline {3.4.2}freePlugin(bpContext *ctx)}{31}{subsection.3.4.2}%
\contentsline {subsection}{\numberline {3.4.3}getPluginValue(bpContext *ctx, pVariable var, void *value)}{32}{subsection.3.4.3}%
\contentsline {subsection}{\numberline {3.4.4}setPluginValue(bpContext *ctx, pVariable var, void *value)}{32}{subsection.3.4.4}%
\contentsline {subsection}{\numberline {3.4.5}handlePluginEvent(bpContext *ctx, bEvent *event, void *value)}{32}{subsection.3.4.5}%
\contentsline {subsection}{\numberline {3.4.6}startBackupFile(bpContext *ctx, struct save\_pkt *sp)}{34}{subsection.3.4.6}%
\contentsline {subsection}{\numberline {3.4.7}endBackupFile(bpContext *ctx)}{35}{subsection.3.4.7}%
\contentsline {subsection}{\numberline {3.4.8}startRestoreFile(bpContext *ctx, const char *cmd)}{35}{subsection.3.4.8}%
\contentsline {subsection}{\numberline {3.4.9}createFile(bpContext *ctx, struct restore\_pkt *rp)}{35}{subsection.3.4.9}%
\contentsline {subsection}{\numberline {3.4.10}setFileAttributes(bpContext *ctx, struct restore\_pkt *rp)}{36}{subsection.3.4.10}%
\contentsline {subsection}{\numberline {3.4.11}endRestoreFile(bpContext *ctx)}{37}{subsection.3.4.11}%
\contentsline {subsection}{\numberline {3.4.12}pluginIO(bpContext *ctx, struct io\_pkt *io)}{37}{subsection.3.4.12}%
\contentsline {subsection}{\numberline {3.4.13}bool checkFile(bpContext *ctx, char *fname)}{38}{subsection.3.4.13}%
\contentsline {section}{\numberline {3.5}Bacula Plugin Entrypoints}{38}{section.3.5}%
\contentsline {subsection}{\numberline {3.5.1}bRC registerBaculaEvents(bpContext *ctx, ...)}{38}{subsection.3.5.1}%
\contentsline {subsection}{\numberline {3.5.2}bRC getBaculaValue(bpContext *ctx, bVariable var, void *value)}{38}{subsection.3.5.2}%
\contentsline {subsection}{\numberline {3.5.3}bRC setBaculaValue(bpContext *ctx, bVariable var, void *value)}{39}{subsection.3.5.3}%
\contentsline {subsection}{\numberline {3.5.4}bRC JobMessage(bpContext *ctx, const char *file, int line, int type, utime\_t mtime, const char *fmt, ...)}{39}{subsection.3.5.4}%
\contentsline {subsection}{\numberline {3.5.5}bRC DebugMessage(bpContext *ctx, const char *file, int line, int level, const char *fmt, ...)}{39}{subsection.3.5.5}%
\contentsline {subsection}{\numberline {3.5.6}void baculaMalloc(bpContext *ctx, const char *file, int line, size\_t size)}{39}{subsection.3.5.6}%
\contentsline {subsection}{\numberline {3.5.7}void baculaFree(bpContext *ctx, const char *file, int line, void *mem)}{39}{subsection.3.5.7}%
\contentsline {section}{\numberline {3.6}Building Bacula Plugins}{39}{section.3.6}%
\contentsline {section}{\numberline {3.7}Advanced Restore Options}{40}{section.3.7}%
\contentsline {section}{\numberline {3.8}Bacula Auth Plugin Documentation}{41}{section.3.8}%
\contentsline {subsection}{\numberline {3.8.1}Overview}{41}{subsection.3.8.1}%
\contentsline {subsection}{\numberline {3.8.2}Dictionary}{41}{subsection.3.8.2}%
\contentsline {subsection}{\numberline {3.8.3}Bacula DIR Plugin API}{41}{subsection.3.8.3}%
\contentsline {subsubsection}{Loading Plugins}{41}{section*.10}%
\contentsline {subsubsection}{Plugin Entry Points}{44}{section*.13}%
\contentsline {subsection}{\numberline {3.8.4}Bacula Pluggable Authentication Modules API Framework \textbf {BPAM}]}{46}{subsection.3.8.4}%
\contentsline {subsubsection}{BPAM Plugin registration}{47}{section*.19}%
\contentsline {chapter}{\numberline {4}Platform Support}{53}{chapter.4}%
\contentsline {section}{\numberline {4.1}General}{53}{section.4.1}%
\contentsline {section}{\numberline {4.2}Requirements to become a Supported Platform}{53}{section.4.2}%
\contentsline {chapter}{\numberline {5}Daemon Protocol}{55}{chapter.5}%
\contentsline {section}{\numberline {5.1}General}{55}{section.5.1}%
\contentsline {section}{\numberline {5.2}Low Level Network Protocol}{55}{section.5.2}%
\contentsline {section}{\numberline {5.3}General Daemon Protocol}{55}{section.5.3}%
\contentsline {section}{\numberline {5.4}The Protocol Used Between the Director and the Storage Daemon}{56}{section.5.4}%
\contentsline {section}{\numberline {5.5}The Protocol Used Between the Director and the File Daemon}{56}{section.5.5}%
\contentsline {section}{\numberline {5.6}The Save Protocol Between the File Daemon and the Storage Daemon}{57}{section.5.6}%
\contentsline {subsection}{\numberline {5.6.1}Command and Control Information}{57}{subsection.5.6.1}%
\contentsline {subsection}{\numberline {5.6.2}Data Information}{57}{subsection.5.6.2}%
\contentsline {chapter}{\numberline {6}Director Services Daemon}{59}{chapter.6}%
\contentsline {chapter}{\numberline {7}File Services Daemon}{61}{chapter.7}%
\contentsline {section}{\numberline {7.1}Commands Received from the Director for a Backup}{61}{section.7.1}%
\contentsline {section}{\numberline {7.2}Commands Received from the Director for a Restore}{62}{section.7.2}%
\contentsline {chapter}{\numberline {8}Storage Daemon Design}{63}{chapter.8}%
\contentsline {section}{\numberline {8.1}SD Design Introduction}{63}{section.8.1}%
\contentsline {section}{\numberline {8.2}SD Development Outline}{63}{section.8.2}%
\contentsline {section}{\numberline {8.3}SD Connections and Sessions}{64}{section.8.3}%
\contentsline {subsection}{\numberline {8.3.1}SD Append Requests}{64}{subsection.8.3.1}%
\contentsline {subsection}{\numberline {8.3.2}SD Read Requests}{65}{subsection.8.3.2}%
\contentsline {section}{\numberline {8.4}SD Data Structures}{65}{section.8.4}%
\contentsline {chapter}{\numberline {9}Catalog Services}{67}{chapter.9}%
\contentsline {section}{\numberline {9.1}General}{67}{section.9.1}%
\contentsline {subsection}{\numberline {9.1.1}Filenames and Maximum Filename Length}{67}{subsection.9.1.1}%
\contentsline {subsection}{\numberline {9.1.2}Installing and Configuring \texttt {MySQL}{}}{68}{subsection.9.1.2}%
\contentsline {subsection}{\numberline {9.1.3}Installing and Configuring \texttt {PostgreSQL}{}}{68}{subsection.9.1.3}%
\contentsline {subsection}{\numberline {9.1.4}Internal Bacula{} Catalog}{68}{subsection.9.1.4}%
\contentsline {subsection}{\numberline {9.1.5}Database Table Design}{68}{subsection.9.1.5}%
\contentsline {section}{\numberline {9.2}Sequence of Creation of Records for a Save Job}{68}{section.9.2}%
\contentsline {section}{\numberline {9.3}Database Tables}{69}{section.9.3}%
\contentsline {chapter}{\numberline {10}Storage Media Output Format}{81}{chapter.10}%
\contentsline {section}{\numberline {10.1}General}{81}{section.10.1}%
\contentsline {section}{\numberline {10.2}Definitions}{81}{section.10.2}%
\contentsline {section}{\numberline {10.3}Storage Daemon File Output Format}{83}{section.10.3}%
\contentsline {section}{\numberline {10.4}Overall Format}{83}{section.10.4}%
\contentsline {section}{\numberline {10.5}Serialization}{83}{section.10.5}%
\contentsline {section}{\numberline {10.6}Block Header}{83}{section.10.6}%
\contentsline {section}{\numberline {10.7}Record Header}{84}{section.10.7}%
\contentsline {section}{\numberline {10.8}Version BB02 Block Header}{85}{section.10.8}%
\contentsline {section}{\numberline {10.9}Version 2 Record Header}{85}{section.10.9}%
\contentsline {section}{\numberline {10.10}Volume Label Format}{85}{section.10.10}%
\contentsline {section}{\numberline {10.11}Session Label}{86}{section.10.11}%
\contentsline {section}{\numberline {10.12}Overall Storage Format}{87}{section.10.12}%
\contentsline {section}{\numberline {10.13}Unix File Attributes}{90}{section.10.13}%
\contentsline {section}{\numberline {10.14}Old Depreciated Tape Format}{91}{section.10.14}%
\contentsline {chapter}{\numberline {11}Bacula Porting Notes}{97}{chapter.11}%
\contentsline {section}{\numberline {11.1}Porting Requirements}{97}{section.11.1}%
\contentsline {section}{\numberline {11.2}Steps to Take for Porting}{98}{section.11.2}%
\contentsline {section}{\numberline {11.1}General}{101}{section.11.1}%
\contentsline {subsection}{\numberline {11.1.1}Minimal Code in Console Program}{101}{subsection.11.1.1}%
\contentsline {subsection}{\numberline {11.1.2}\acs {GUI} Interface is Difficult}{101}{subsection.11.1.2}%
\contentsline {section}{\numberline {11.2}Bvfs API}{102}{section.11.2}%
\contentsline {chapter}{\numberline {12}TLS}{107}{chapter.12}%
\contentsline {section}{\numberline {12.1}Introduction to TLS}{107}{section.12.1}%
\contentsline {section}{\numberline {12.2}New Configuration Directives}{107}{section.12.2}%
\contentsline {section}{\numberline {12.3}TLS API Implementation}{108}{section.12.3}%
\contentsline {subsection}{\numberline {12.3.1}Library Initialization and Cleanup}{108}{subsection.12.3.1}%
\contentsline {subsection}{\numberline {12.3.2}Manipulating TLS Contexts}{108}{subsection.12.3.2}%
\contentsline {subsection}{\numberline {12.3.3}Performing Post-Connection Verification}{109}{subsection.12.3.3}%
\contentsline {subsection}{\numberline {12.3.4}Manipulating TLS Connections}{109}{subsection.12.3.4}%
\contentsline {section}{\numberline {12.4}Bnet API Changes}{110}{section.12.4}%
\contentsline {subsection}{\numberline {12.4.1}Negotiating a TLS Connection}{110}{subsection.12.4.1}%
\contentsline {subsection}{\numberline {12.4.2}Manipulating Socket Blocking State}{110}{subsection.12.4.2}%
\contentsline {section}{\numberline {12.5}Authentication Negotiation}{111}{section.12.5}%
\contentsline {chapter}{\numberline {13}Bacula{} Regression Testing}{113}{chapter.13}%
\contentsline {section}{\numberline {13.1}Setting up Regession Testing}{113}{section.13.1}%
\contentsline {section}{\numberline {13.2}Running the Regression Script}{113}{section.13.2}%
\contentsline {subsection}{\numberline {13.2.1}Setting the Configuration Parameters}{114}{subsection.13.2.1}%
\contentsline {subsection}{\numberline {13.2.2}Building the Test Bacula{}}{115}{subsection.13.2.2}%
\contentsline {subsection}{\numberline {13.2.3}Setting up your SQL engine}{115}{subsection.13.2.3}%
\contentsline {subsection}{\numberline {13.2.4}Running the Disk Only Regression}{115}{subsection.13.2.4}%
\contentsline {subsection}{\numberline {13.2.5}Other Tests}{117}{subsection.13.2.5}%
\contentsline {subsection}{\numberline {13.2.6}If a Test Fails}{117}{subsection.13.2.6}%
\contentsline {section}{\numberline {13.3}Testing a Binary Installation}{117}{section.13.3}%
\contentsline {section}{\numberline {13.4}Running a Single Test}{118}{section.13.4}%
\contentsline {section}{\numberline {13.5}Writing a Regression Test}{118}{section.13.5}%
\contentsline {subsection}{\numberline {13.5.1}Running the Tests by Hand}{118}{subsection.13.5.1}%
\contentsline {subsection}{\numberline {13.5.2}Directory Structure}{118}{subsection.13.5.2}%
\contentsline {subsection}{\numberline {13.5.3}Adding a New Test}{118}{subsection.13.5.3}%
\contentsline {subsection}{\numberline {13.5.4}Running a Test Under The Debugger}{119}{subsection.13.5.4}%
\contentsline {chapter}{\numberline {14}Bacula MD5 Algorithm}{121}{chapter.14}%
\contentsline {section}{\numberline {14.1}Command Line Message Digest Utility }{121}{section.14.1}%
\contentsline {subsection}{\numberline {14.1.1}Name}{121}{subsection.14.1.1}%
\contentsline {subsection}{\numberline {14.1.2}Synopsis}{121}{subsection.14.1.2}%
\contentsline {subsection}{\numberline {14.1.3}Description}{121}{subsection.14.1.3}%
\contentsline {subsection}{\numberline {14.1.4}Options}{122}{subsection.14.1.4}%
\contentsline {subsection}{\numberline {14.1.5}Files}{122}{subsection.14.1.5}%
\contentsline {subsection}{\numberline {14.1.6}Bugs}{122}{subsection.14.1.6}%
\contentsline {section}{\numberline {14.2}Download md5.zip (Zipped archive)}{122}{section.14.2}%
\contentsline {subsection}{\numberline {14.2.1}See Also}{122}{subsection.14.2.1}%
\contentsline {subsection}{\numberline {14.2.2}Exit Status}{122}{subsection.14.2.2}%
\contentsline {subsection}{\numberline {14.2.3}Copying}{122}{subsection.14.2.3}%
\contentsline {subsection}{\numberline {14.2.4}Acknowledgements}{122}{subsection.14.2.4}%
\contentsline {chapter}{\numberline {15}Bacula Memory Management}{123}{chapter.15}%
\contentsline {section}{\numberline {15.1}General}{123}{section.15.1}%
\contentsline {subsection}{\numberline {15.1.1}Statically Allocated Memory}{123}{subsection.15.1.1}%
\contentsline {subsection}{\numberline {15.1.2}Dynamically Allocated Memory}{123}{subsection.15.1.2}%
\contentsline {subsection}{\numberline {15.1.3}Pooled and Non-pooled Memory}{124}{subsection.15.1.3}%
\contentsline {chapter}{\numberline {16}TCP/IP Network Protocol}{127}{chapter.16}%
\contentsline {section}{\numberline {16.1}General}{127}{section.16.1}%
\contentsline {section}{\numberline {16.2}bnet and Threads}{127}{section.16.2}%
\contentsline {section}{\numberline {16.3}bnet\_open}{127}{section.16.3}%
\contentsline {section}{\numberline {16.4}bnet\_send}{128}{section.16.4}%
\contentsline {section}{\numberline {16.5}bnet\_fsend}{128}{section.16.5}%
\contentsline {section}{\numberline {16.6}Additional Error information}{128}{section.16.6}%
\contentsline {section}{\numberline {16.7}bnet\_recv}{128}{section.16.7}%
\contentsline {section}{\numberline {16.8}bnet\_sig}{128}{section.16.8}%
\contentsline {section}{\numberline {16.9}bnet\_strerror}{129}{section.16.9}%
\contentsline {section}{\numberline {16.10}bnet\_close}{129}{section.16.10}%
\contentsline {section}{\numberline {16.11}Becoming a Server}{129}{section.16.11}%
\contentsline {section}{\numberline {16.12}Higher Level Conventions}{129}{section.16.12}%
\contentsline {chapter}{\numberline {17}Smart Memory Allocation}{131}{chapter.17}%
\contentsline {subsection}{\numberline {17.0.1} Installing SMARTALLOC}{131}{subsection.17.0.1}%
\contentsline {subsection}{\numberline {17.0.2} Squelching a SMARTALLOC}{132}{subsection.17.0.2}%
\contentsline {subsection}{\numberline {17.0.3} Living with Libraries}{133}{subsection.17.0.3}%
\contentsline {subsection}{\numberline {17.0.4} SMARTALLOC Details}{134}{subsection.17.0.4}%
\contentsline {subsection}{\numberline {17.0.5} When SMARTALLOC is Disabled}{135}{subsection.17.0.5}%
\contentsline {subsection}{\numberline {17.0.6} The {\tt alloc()} Function}{135}{subsection.17.0.6}%
\contentsline {subsection}{\numberline {17.0.7} Overlays and Underhandedness}{135}{subsection.17.0.7}%
\contentsline {subsection}{\numberline {17.0.8} Test and Demonstration Program}{136}{subsection.17.0.8}%
\contentsline {subsection}{\numberline {17.0.9} Invitation to the Hack}{136}{subsection.17.0.9}%
\contentsline {section}{\numberline {17.1}Download smartall.zip (Zipped archive)}{136}{section.17.1}%
\contentsline {subsection}{\numberline {17.1.1} Copying}{136}{subsection.17.1.1}%
\contentsline {chapter}{Appendices}{137}{section*.44}%
\contentsline {chapter}{\numberline {A}Acronyms}{139}{Appendix.1.A}%
\contentsline {subsection}{Index}{140}{section*.45}%