]> git.sur5r.net Git - bacula/docs/blob - docs/manuals/en/main/install.tex
356a6ff9b34c1016c79866c6fd7e3c7592c119b1
[bacula/docs] / docs / manuals / en / main / install.tex
1 %%
2 %%
3
4 \chapter{Installing Bacula}
5 \label{InstallChapter}
6 \index[general]{Bacula!Installing}
7 \index[general]{Installing Bacula}
8
9 In general, you will need the Bacula source release, and if you want to run
10 a Windows client, you will need the Bacula Windows binary release.
11 However, Bacula needs certain third party packages (such as {\bf MySQL},
12 {\bf PostgreSQL}, or {\bf SQLite} to build and run
13 properly depending on the
14 options you specify.  Normally, {\bf MySQL} and {\bf PostgreSQL} are
15 packages that can be installed on your distribution.  However, if you do
16 not have them, to simplify your task, we have combined a number of these
17 packages into three {\bf depkgs} releases (Dependency Packages).  This can
18 vastly simplify your life by providing you with all the necessary packages
19 rather than requiring you to find them on the Web, load them, and install
20 them.
21
22 \section{Source Release Files}
23 \index[general]{Source Files}
24 \index[general]{Release Files}
25  The source code has been broken into
26  three separate tar files each corresponding to a different module in
27  the Bacula git repository. The released files are:
28
29 \begin{description}
30 \item [bacula-7.2.0.tar.gz]
31   This is the primary source code release for Bacula. On each
32   release the version number (7.2.0) will be updated.
33
34 \item [bacula-docs-7.2.0.tar.bz2]
35   This file contains a copy of the docs directory with the
36   documents prebuild. English HTML directory, single HTML
37   file, and pdf file. The French, German, Spanish translations
38   are not built, but can be obtained from the git repository.
39   Note that this file is big, it used .bz2 compression which 
40   reduces the size.
41
42 \item [bacula-gui-7.2.0.tar.gz]
43   This file contains the non-core GUI programs. Currently,
44   it contains Baculum, a PHP program for producing management
45   viewing of your Bacula job status in a browser.
46
47 \item [win32bacula-7.2.0.exe]
48   This file is the 32 bit Windows installer for installing
49   the Windows client (File daemon) on a Windows machine.
50   This client will also run on 64 bit Windows machines, but
51   VSS support is not available if you are running a 64 bit
52   version of Windows.  This installer installs only the FD, 
53   the Director and Storage daemon are not included.
54
55 \item [win64bacula-7.2.0.exe]
56   This file is the 64 bit Windows installer for installing
57   the Windows client (File daemon) on a Windows machine.
58   This client will only run on 64 bit Windows OS machines.
59   It will not run on 32 bit machines or 32 bit Windows OSes.
60   The win64bacula release is necessary for Volume Shadow
61   Copy (VSS) to work on Win64 OSes.  This installer
62   installs only the FD, the Director and Storage daemon
63   are not included.
64
65 \end{description}
66
67 \label{upgrading1}
68 \section{Upgrading Bacula}
69 \index[general]{Bacula!Upgrading}
70 \index[general]{Upgrading Bacula}
71 \index[general]{Upgrading}
72
73 If you are upgrading from one Bacula version to another, you should first
74 carefully read the ReleaseNotes of all major versions between your current
75 version and the version to which you are upgrading.  In many upgrades,
76 especially for minor patch upgrades (e.g. between 3.0.0 and 3.0.1) there
77 will be no database upgrade, and hence the process is rather simple.
78
79 With version 3.0.0 and later, you {\bf must} ensure that on any one
80 machine that all components of Bacula are running on exactly the
81 same version.  Prior to version 3.0.0, it was possible to run a 
82 lower level FD with a newer Director and SD.  This is no longer the
83 case.  
84
85 As always, we attempt to support older File daemons. This avoids the
86 need to do a simultaneous upgrade of many machines. For exactly what
87 older versions of the FD are supported, please see the ReleaseNotes 
88 for the new version.  In any case, you must always upgrade both the
89 Director and the Storage daemon at the same time, and you must also
90 upgrade any File daemon that is running on the same machine as a Director
91 or a Storage daemon (see the prior paragraph).
92
93 If the Bacula catalog
94 database has been upgraded (as it is almost every major release), you will
95 either need to reinitialize your database starting from scratch (not
96 normally a good idea), or save an ASCII copy of your database, then proceed
97 to upgrade it. If you are upgrading two major versions (e.g. 1.36 to 2.0)
98 then life will be more complicated because you must do two database
99 upgrades. See below for more on this.
100
101 Upgrading the catalog is normally done after Bacula is build and installed
102 by:
103
104 \begin{verbatim}
105 cd <installed-scripts-dir> (default /etc/bacula)
106 ./update_bacula_tables
107 \end{verbatim}
108
109 This update script can also be find in the Bacula source src/cats
110 directory.
111
112 If there are several database upgrades between your version and the
113 version to which you are upgrading, you will need to apply each database
114 upgrade script. For your convenience, you can find all the old upgrade scripts
115 in the {\bf upgradedb} directory of the source code. You will need to edit the
116 scripts to correspond to your system configuration. The final upgrade script,
117 if any, can be applied as noted above.
118
119 If you are upgrading from one major version to another, you will need to
120 replace all your components at the same time as generally the inter-daemon
121 protocol will change. However, within any particular release (e.g. version
122 1.32.x) unless there is an oversight or bug, the daemon protocol will not
123 change. If this is confusing, simply read the ReleaseNotes very carefully as
124 they will note if all daemons must be upgraded at the same time. 
125
126 Finally, please note that in general it is not necessary or desirable
127 to do a {\bf make uninstall} before doing an upgrade providing you are careful
128 not to change the installation directories. In fact, if you do so, you will 
129 most likely delete all your conf files, which could be disastrous.
130 The normal procedure during an upgrade is simply:
131
132 \begin{verbatim}
133 ./configure (your options)
134 make
135 make install
136 \end{verbatim}
137
138 In general none of your existing .conf or .sql files will be overwritten,
139 and you must do both the {\bf make} and {\bf make install}  commands, a
140 {\bf make install} without the preceding {\bf make} will not work.
141   
142 For additional information on upgrading, please see the \borgxrlink{Upgrading Bacula Versions}{upgrading}{problems}{section} of the \problemsman{}.
143
144 \section{Releases Numbering}
145 \index[general]{Release Numbering}
146 \index[general]{Version Numbering}
147 Every Bacula release whether beta or production has a different number  
148 as well as the date of the release build. The numbering system follows
149 traditional Open Source conventions in that it is of the form.
150
151 \begin{verbatim}
152 major.minor.release
153 \end{verbatim}
154
155 For example:
156 \begin{verbatim}
157 1.38.11
158 \end{verbatim}
159
160 where each component (major, minor, patch) is a number.
161 The major number is currently 1 and normally does not change
162 very frequently.  The minor number starts at 0 and increases
163 each for each production release by 2 (i.e. it is always an
164 even number for a production release), and the patch number is
165 starts at zero each time the minor number changes.  The patch
166 number is increased each time a bug fix (or fixes) is released
167 to production.
168
169 So, as of this date (10 September 2006), the current production Bacula
170 release is version 1.38.11.  If there are bug fixes, the next release
171 will be 1.38.12 (i.e. the patch number has increased by one).
172
173 For all patch releases where the minor version number does not change,
174 the database and all the daemons will be compatible.  That means that
175 you can safely run a 1.38.0 Director with a 1.38.11 Client.  Of course,
176 in this case, the Director may have bugs that are not fixed. Generally,
177 within a minor release (some minor releases are not so minor), all
178 patch numbers are officially released to production. This means that while
179 the current Bacula version is 1.38.11, versions 1.38.0, 1.38.1, ... 1.38.10
180 have all been previously released.
181
182 When the minor number is odd, it indicates that the package is under 
183 development and thus may not be stable. For example, while the current 
184 production release of Bacula is currently 1.38.11, the current development
185 version is 1.39.22. All patch versions of the development code are 
186 available in the SVN (source repository).  However, not all patch versions
187 of the development code (odd minor version) are officially released. When
188 they are released, they are released as beta versions (see below for a
189 definition of what beta means for Bacula releases).                     
190
191 In general when the minor number increases from one production release
192 to the next (i.e. 1.38.x to 1.40.0), the catalog database must be upgraded,
193 the Director and Storage daemon must always be on the same minor release
194 number, and often (not always), the Clients must also be on the same minor
195 release. As often as possible, we attempt to make new releases that are
196 downwards compatible with prior clients, but this is not always possible.
197 You must check the release notes.  In general, you will have fewer problems
198 if you always run all the components on the same minor version number (i.e.
199 all either 1.38.x or 1.40.x but not mixed).
200
201
202 \label{BetaReleases}
203 \section*{Beta Releases}
204 \index[general]{Beta Releases}
205 Towards the end of the development cycle, which typically runs
206 one year from a major release to another, there will be several beta
207 releases of the development code prior to a production release.  
208 As noted above, beta versions always have odd minor version numbers
209 (e.g 1.37.x or 1.39.x). 
210 The purpose of the beta releases is to allow early adopter users to test
211 the new code.  Beta releases are made with the following considerations:
212
213 \begin{itemize}
214 \item The code passes the regression testing on FreeBSD, Linux, and Solaris
215   machines.
216
217 \item There are no known major bugs, or on the rare occasion that 
218   there are, they will be documented or already in the bugs database.
219
220 \item Some of the new code/features may not yet be tested.
221
222 \item Bugs are expected to be found, especially in the new
223   code before the final production release.
224
225 \item The code will have been run in production in at least one small
226   site (mine).
227
228 \item The Win32 client will have been run in production at least
229   one night at that small site.
230
231 \item The documentation in the manual is unlikely to be complete especially
232   for the new features, and the Release Notes may not be fully
233   organized.
234
235 \item Beta code is not generally recommended for everyone, but
236   rather for early adopters.
237 \end{itemize}
238
239
240 \label{Dependency}
241 \section{Dependency Packages}
242 \index[general]{Dependency Packages}
243 \index[general]{Packages!Dependency}
244
245 As discussed above, we have combined a number of third party packages that
246 Bacula might need into the {\bf depkgs} release. You can,
247 of course, get the latest packages from the original authors or 
248 from your operating system supplier. The locations of
249 where we obtained the packages are in the README file in each package.
250 However, be aware that the packages in the depkgs files have been tested by us
251 for compatibility with Bacula. 
252
253 Typically, a dependency package will be named {\bf depkgs-ddMMMyy.tar.gz}
254 where {\bf dd} is the day we release it, {\bf MMM}
255 is the abbreviated month (e.g. Jan), and {\bf yy} is the year. An actual
256 example is: {\bf depkgs-18Dec.tar.gz}. To install and build this package (if
257 needed), you do the following: 
258
259 \begin{enumerate}
260 \item Create a {\bf bacula} directory, into which you will place  both the
261    Bacula source as well as the dependency package.  
262 \item Detar the {\bf depkgs} into the {\bf bacula} directory.  
263 \item cd bacula/depkgs  
264 \item make 
265 \end{enumerate}
266
267 Although the exact composition of the dependency packages may change from time
268 to time, the current makeup is the following: 
269
270 \addcontentsline{lot}{table}{Dependency Packages}
271 \begin{longtable}{|l|l|l|}
272  \hline 
273 \multicolumn{1}{|c| }{\bf 3rd Party Package} & \multicolumn{1}{c| }{\bf depkgs}
274      & \multicolumn{1}{c| }{\bf depkgs-qt} \\
275  \hline {SQLite3 } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{ }\\
276  \hline {mtx } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{ } \\
277  \hline {qt4 } & \multicolumn{1}{c| }{ } & \multicolumn{1}{c| }{X } \\
278  \hline 
279 \end{longtable}
280
281 Note, some of these packages are quite large, so that building them can be a
282 bit time consuming. The above instructions will build all the packages
283 contained in the directory. However, when building Bacula, it will take only
284 those pieces that it actually needs. 
285
286 Alternatively, you can make just the packages that are needed. For example, 
287
288 \footnotesize
289 \begin{verbatim}
290 cd bacula/depkgs
291 make sqlite
292 \end{verbatim}
293 \normalsize
294
295 will configure and build only the SQLite package. 
296
297 You should build the packages that you will require in {\bf depkgs} a     
298 prior to configuring and building Bacula, since Bacula will need
299 them during the build process. 
300
301 Note, the {\bf depkgs-qt} package is required for building bat, because 
302 bat is currently built with Qt version 4.3.4.  It can be built with other
303 Qt versions, but that almost always creates problems or introduces
304 instabilities.
305
306 You can build the depkgs-qt with the following:
307
308 \footnotesize
309 \begin{verbatim}
310 cd bacula
311 tar xfvz depkgs-qt-28Jul09.tar.gz
312 cd depkgs-qt
313 make qt4
314 source qt4-path
315 \end{verbatim}
316 \normalsize
317
318 Doing the {\bf source qt4-path} defines the following environment
319 variables:
320
321 \footnotesize
322 \begin{verbatim}
323 QTDIR
324 QTLIB
325 QTINC
326 \end{verbatim}
327 \normalsize
328
329 Each one should point to a specific location in the depkgs-qt package
330 that you loaded.  It also puts the depkgs-qt/qt4/bin directory
331 on your path before all other directories.  This ensures that
332 the bat build will use your Qt 4.3.4 library rather than any that 
333 might be on your system.
334
335 Before running your Bacula build, please make sure that
336 {\bf qmake-qt4} is not on your path.  If it is please rename it. If
337 you don't do this, Bacula will attempt to build with any Qt4 package
338 installed on your system rather than the one you just built.
339 If you logoff and log back in, you must re-source the depkgs-qt/qt4-patch
340 file before attempting to rebuild the bat part of Bacula.
341
342 For more information on the {\bf depkgs-qt} package, please read the
343 INSTALL file in the main directory of that package. If you are going to 
344 build Qt4 using {\bf depkgs-qt}, you must source the {\bf qt4-paths} file
345 included in the package prior to building Bacula. Please read the INSTALL
346 file for more details.
347
348 Even if you do not use SQLite, you might find it worthwhile to build {\bf mtx}
349 because the {\bf tapeinfo} program that comes with it can often provide you
350 with valuable information about your SCSI tape drive (e.g. compression,
351 min/max block sizes, ...). Note, most distros provide {\bf mtx} as part of 
352 their release.
353
354 The {\bf depkgs1} package is depreciated and previously contained
355 readline, which should be available on all operating systems.
356
357 The {\bf depkgs-win32} package is deprecated and no longer used in 
358 Bacula version 1.39.x and later. It was previously used to build
359 the native Win32 client program, but this program is now built on Linux
360 systems using cross-compiling.  All the tools and third party libraries
361 are automatically downloaded by executing the appropriate scripts.  See
362 src/win32/README.mingw32 for more details.
363
364 \section{Supported Operating Systems}
365 \label{Systems}
366 \index[general]{Systems!Supported Operating}
367 \index[general]{Supported Operating Systems}
368
369 Please see the \ilink{Supported Operating Systems}{SupportedOSes} section
370 of the QuickStart chapter of this manual. 
371
372 \section{Building Bacula from Source}
373 \label{Building}
374 \index[general]{Source!Building Bacula from}
375 \index[general]{Building Bacula from Source}
376
377 The basic installation is rather simple. 
378
379 \begin{enumerate}
380 \item Install and build any {\bf depkgs} as noted above. This
381    should be unnecessary on most modern Operating Systems.
382
383 \item Configure and install MySQL or PostgreSQL (if desired). 
384    \ilink{Installing and Configuring MySQL Phase I}{MySqlChapter} or  
385    \ilink{Installing and Configuring PostgreSQL Phase I}{PostgreSqlChapter}.  If you are installing from rpms, and are
386    using MySQL, please be sure to install  {\bf mysql-devel}, so that the MySQL
387    header files are available  while compiling Bacula. In addition, the MySQL
388    client  library {\bf mysqlclient} requires the gzip compression library  {\bf
389    libz.a} or {\bf libz.so}. If you are using rpm packages,  these libraries are
390    in the {\bf libz-devel} package. On Debian  systems, you will need to load the
391    {\bf zlib1g-dev} package. If  you are not using rpms or debs, you will need to
392    find the  appropriate package for your system.  
393
394    Note, if you already have a running MySQL or PostgreSQL on your system, you 
395    can skip this phase provided that you have built the thread  safe libraries.
396    And you have already installed the additional  rpms noted above.  
397
398    SQLite is not supported on Solaris. This is because it
399    frequently fails with bus errors.  However SQLite3 may work.
400
401 \item Detar the Bacula source code preferably into the {\bf bacula}  directory
402    discussed above.  
403
404 \item {\bf cd} to the directory containing the source code.  
405
406 \item ./configure (with appropriate options as described below). Any
407    path names you specify as options on the ./configure command line
408    must be absolute paths and not relative.
409
410 \item Check the output of ./configure very carefully, especially  the Install
411    binaries and Install config directories.  If they are not correct,
412    please rerun ./configure until they  are. The output from ./configure is
413    stored in {\bf config.out}  and can be re-displayed at any time without
414    rerunning the  ./configure by doing {\bf cat config.out}.  
415
416 \item If after running ./configure once, you decide to change options  and
417    re-run it, that is perfectly fine, but before re-running it,  you should run: 
418
419 \footnotesize
420 \begin{verbatim}
421       make distclean
422 \end{verbatim}
423 \normalsize
424
425 so that you are sure to start from scratch and not have a  mixture of the two
426 options. This is because ./configure  caches much of the information. The {\bf
427 make distclean}  is also critical if you move the source directory from one 
428 machine to another. If the {\bf make distclean} fails,  just ignore it and
429 continue on.  
430
431 \item make  
432    If you get errors while linking in the Storage daemon directory
433    (src/stored), it is probably because you have not loaded the static
434    libraries on your system.  I noticed this problem on a Solaris system.
435    To correct it, make sure that you have not added {\bf
436    {-} {-}enable-static-tools} to the {\bf ./configure} command.
437
438    If you skip this step ({\bf make}) and proceed immediately to the {\bf
439    make install} you are making two serious errors: 1.  your install will
440    fail because Bacula requires a {\bf make} before a {\bf make install}.
441    2.  you are depriving yourself of the chance to make sure there are no
442    errors before beginning to write files to your system directories.
443                                  
444
445 \item make install  
446    Please be sure you have done a {\bf make} before entering this command,
447    and that everything has properly compiled and linked without errors.
448
449
450 \item If you are new to Bacula, we {\bf strongly} recommend that you skip
451    the next step and use the default configuration files, then run the
452    example program in the next chapter, then come back and modify your
453    configuration files to suit your particular needs.
454
455 \item Customize the configuration files for each of the three daemons 
456    (Directory, File, Storage) and for the Console program.  For the details
457    of how to do this, please see \ilink{Setting Up Bacula Configuration Files}{ConfigureChapter} in the Configuration chapter of this manual.  We
458    recommend that you start by modifying the default configuration files
459    supplied, making the minimum changes necessary.  Complete customization
460    can be done after you have Bacula up and running.  Please take care when
461    modifying passwords, which were randomly generated, and the {\bf Name}s
462    as the passwords and names must agree between the configuration files
463    for security reasons.  
464
465 \label{CreateDatabase}
466 \item Create the Bacula MySQL database and tables
467    (if using MySQL)
468       \ilink{Installing and Configuring MySQL Phase II}{mysql_phase2} or 
469       create the Bacula PostgreSQL database and tables  
470    \ilink{Configuring PostgreSQL II}{PostgreSQL_configure} or alternatively  if you are using
471    SQLite \ilink{Installing and Configuring SQLite Phase II}{phase2}.  
472
473 \item Start Bacula ({\bf ./bacula start}) Note. the next chapter  shows you
474    how to do this in detail.  
475
476 \item Interface with Bacula using the Console program  
477
478 \item For the previous two items, please follow the instructions  in the 
479    \ilink{Running Bacula}{TutorialChapter} chapter of  this manual,
480    where you will run a simple backup and do a  restore. Do this before you make
481    heavy modifications to the  configuration files so that you are sure that
482    Bacula works  and are familiar with it. After that changing the conf files 
483    will be easier.  
484
485 \item If after installing Bacula, you decide to "move it", that is  to
486    install it in a different set of directories, proceed  as follows:  
487
488 \footnotesize
489 \begin{verbatim}
490       make uninstall
491       make distclean
492       ./configure (your-new-options)
493       make
494       make install
495       
496 \end{verbatim}
497 \normalsize
498
499 \end{enumerate}
500
501 If all goes well, the {\bf ./configure} will correctly determine which
502 operating system you are running and configure the source code appropriately.
503 Currently, FreeBSD, Linux (Red Hat), and Solaris are supported. The Bacula
504 client (File daemon) is reported to work with MacOS X 10.3 is if 
505 readline support is not enabled (default) when building the client.       
506
507 If you install Bacula on more than one system, and they are identical, you can
508 simply transfer the source tree to that other system and do a "make
509 install". However, if there are differences in the libraries or OS versions,
510 or you wish to install on a different OS, you should start from the original
511 compress tar file. If you do transfer the source tree, and you have previously
512 done a ./configure command, you MUST do: 
513
514 \footnotesize
515 \begin{verbatim}
516 make distclean
517 \end{verbatim}
518 \normalsize
519
520 prior to doing your new ./configure. This is because the GNU autoconf tools
521 cache the configuration, and if you re-use a configuration for a Linux machine
522 on a Solaris, you can be sure your build will fail. To avoid this, as
523 mentioned above, either start from the tar file, or do a "make distclean". 
524
525 In general, you will probably want to supply a more complicated {\bf
526 configure} statement to ensure that the modules you want are built and that
527 everything is placed into the correct directories. 
528
529 For example, on Fedora, Red Hat, or SuSE one could use the following: 
530
531 \footnotesize
532 \begin{verbatim}
533 CFLAGS="-g -Wall" \
534   ./configure \
535     --sbindir=/opt/bacula/bin \
536     --sysconfdir=/opt/bacula/etc \
537     --with-pid-dir=/var/run \
538     --with-subsys-dir=/var/run \
539     --with-mysql \
540     --with-working-dir=/opt/bacula/working \
541     --with-dump-email=$USER
542 \end{verbatim}
543 \normalsize
544
545 The advantage of using the above configuration to start is that
546 everything will be put into a single directory, which you can later delete
547 once you have run the examples in the next chapter and learned how Bacula
548 works. In addition, the above can be installed and run as non-root. 
549
550 For the developer's convenience, I have added a {\bf defaultconfig} script to
551 the {\bf examples} directory. This script contains the statements that you
552 would normally use, and each developer/user may modify them to suit his needs.
553 You should find additional useful examples in this directory as well. 
554
555 The {\bf \verb:--:enable-conio} or {\bf \verb:--:enable-readline} options are
556 useful because they provide a command line history, editing capability for the
557 Console program and tab completion on various option. If you have included
558 either option in the build, either the {\bf termcap} or the {\bf ncurses}
559 package will be needed to link. On most systems, including Red Hat and SuSE,
560 you should include the ncurses package.  If Bacula's configure process finds
561 the ncurses libraries, it will use those rather than the termcap library.  On
562 some systems, such as SuSE, the termcap library is not in the standard library
563 directory.  As a consequence, the option may be disabled or you may get an
564 error message such as:
565
566 \footnotesize
567 \begin{verbatim}
568 /usr/lib/gcc-lib/i586-suse-linux/3.3.1/.../ld:
569 cannot find -ltermcap
570 collect2: ld returned 1 exit status
571 \end{verbatim}
572 \normalsize
573
574 while building the Bacula Console. In that case, you will need to set the {\bf
575 LDFLAGS} environment variable prior to building. 
576
577 \footnotesize
578 \begin{verbatim}
579 export LDFLAGS="-L/usr/lib/termcap"
580 \end{verbatim}
581 \normalsize
582
583 The same library requirements apply if you wish to use the readline subroutines
584 for command line editing, history and tab completion or if you are using a
585 MySQL library that requires encryption. If you need encryption, you can either
586 export the appropriate additional library options as shown above or,
587 alternatively, you can include them directly on the ./configure line as in:
588
589 \footnotesize
590 \begin{verbatim}
591 LDFLAGS="-lssl -lcyrpto" \
592    ./configure <your-options>
593 \end{verbatim}
594 \normalsize
595
596 On some systems such as Mandriva, readline tends to
597 gobble up prompts, which makes it totally useless. If this happens to you, use
598 the disable option, or if you are using version 1.33 and above try using {\bf
599 \verb:--:enable-conio} to use a built-in readline replacement. You will still need
600 either the termcap or the ncurses library, but it is unlikely that the {\bf conio}
601 package will gobble up prompts. 
602
603 readline is no longer supported after version 1.34.  The code within Bacula
604 remains, so it should be usable, and if users submit patches for it, we will
605 be happy to apply them.  However, due to the fact that each version of
606 readline seems to be incompatible with previous versions, and that there
607 are significant differences between systems, we can no longer afford to
608 support it.
609
610 \section{What Database to Use?}
611 \label{DB}
612 \index[general]{What Database to Use?}
613 \index[general]{Use!What Database to}
614
615 Before building Bacula you need to decide if you want to use SQLite, MySQL, or
616 PostgreSQL. If you are not already running MySQL or PostgreSQL, you might
617 want to start by testing with SQLite (not supported on Solaris).
618 This will greatly simplify the setup for you
619 because SQLite is compiled into Bacula an requires no administration. It
620 performs well and is suitable for small to medium sized installations (maximum
621 10-20 machines). However, we should note that a number of users have
622 had unexplained database corruption with SQLite. For that reason, we
623 recommend that you install either PostgreSQL or MySQL for production
624 work.
625
626 If you wish to use MySQL as the Bacula catalog, please see the
627 \ilink{Installing and Configuring MySQL}{MySqlChapter} chapter of this
628 manual. You will need to install MySQL prior to continuing with the
629 configuration of Bacula. MySQL is a high quality database that is very
630 efficient and is suitable for small and medium sized installation (up to
631 2,000,000 files per job). It is slightly more complicated than SQLite to setup
632 and administer because it has a number of sophisticated features such as
633 userids and passwords. It runs as a separate process, is truly professional and
634 can manage a database of any size.
635
636 If you wish to use PostgreSQL as the Bacula catalog, please see the
637 \ilink{Installing and Configuring PostgreSQL}{PostgreSqlChapter} chapter of
638 this manual. You will need to install PostgreSQL prior to continuing with the
639 configuration of Bacula. PostgreSQL is very similar to MySQL, though it tends
640 to be slightly more SQL92 compliant and has many more advanced features such as
641 transactions, stored procedures, and the such. It requires a certain knowledge
642 to install and maintain. PostgreSQL is suitable for any sized installation
643 (some sites have much more than 1 billion objects in the Catalog). Bacula uses
644 many optimized PostgreSQL functions, and can run more than 10 time faster on
645 jobs having millions of files than MySQL (Specially in during restore, accurate
646 mode, bvfs queries and when the database server is not on the same host than
647 the Director). It's possible to switch from MySQL/SQLite to PostgreSQL, but it
648 requires some DBA knowledge.
649
650 If you wish to use SQLite as the Bacula catalog, please see 
651 \ilink{Installing and Configuring SQLite}{SqlLiteChapter} chapter of
652 this manual. SQLite is not supported on Solaris.
653
654 \section{Quick Start}
655 \index[general]{Quick Start}
656 \index[general]{Start!Quick}
657
658 There are a number of options and important considerations given below
659 that you can skip for the moment if you have not had any problems building
660 Bacula with a simplified configuration as shown above. 
661       
662 If the ./configure process is unable to find specific libraries (e.g.    
663 libintl, you should ensure that the appropriate package is installed on
664 your system. Alternatively, if the package is installed in a non-standard
665 location (as far as Bacula is concerned), then there is generally an
666 option listed below (or listed with "./configure {-} {-}help" that will
667 permit you to specify the directory that should be searched. In other
668 cases, there are options that will permit you to disable to feature 
669 (e.g. {-} {-}disable-nls).
670
671 If you want to dive right into it, we recommend you skip to the next chapter,
672 and run the example program. It will teach you a lot about Bacula and as an
673 example can be installed into a single directory (for easy removal) and run as
674 non-root. If you have any problems or when you want to do a real installation,
675 come back to this chapter and read the details presented below. 
676
677 \section{Configure Options}
678 \label{Options}
679 \index[general]{Options!Configure}
680 \index[general]{Configure Options}
681
682 The following command line options are available for {\bf configure} to
683 customize your installation. 
684
685 \begin{description}
686 \item [ \--prefix=\lt{}patch\gt{}]
687    \index[general]{{-}prefix}
688    This option is meant to allow you to direct where the architecture
689    independent files should be placed.  However, we find this a somewhat
690    vague concept, and so we have not implemented this option other than
691    to use any explicit prefix that you may define.  If you do not
692    explicitly specify a prefix, Bacula's configure routine will not use
693    the default value that ./configure --help prints.
694    As a consequence, we suggest that
695    you avoid it. We have provided options that allow you to explicitly
696    specify the directories for each of the major categories of installation
697    files.
698 \item [ {-}{\-}sbindir=\lt{}binary-path\gt{}]
699    \index[general]{{-}{\-}sbindir}
700    Defines where the Bacula  binary (executable) files will be placed during a
701    {\bf make  install} command.  
702
703 \item [ {-}{\-}sysconfdir=\lt{}config-path\gt{}]
704    \index[general]{{-}{\-}sysconfdir}
705    Defines where the Bacula configuration files should be placed during a
706    {\bf make install} command.  Note, for security reasons,
707    this directory should be unique to Bacula and not read/writable by
708    any other user/group than Bacula is running under.
709
710    Please note that Bacula attempts to make the configuration directory 
711    secure by doing an:
712 \smallskip
713    chmod 770 \lt{}sysconfdir\gt{}
714 \smallskip
715    So, if you make sysconfdir point to a global directory such as
716    /usr/local/etc, the modes for that directory will be restricted, and
717    this may affect other programs that are installed there. We strongly 
718    recommend that you set {\bf sysconfdir} to {\bf /opt/bacula/etc} so
719    that the directory for all Bacula configuration files is unique to
720    Bacula and used only by Bacula.
721
722
723 \item [ {-}{\-}mandir=\lt{}path\gt{}]
724    \index[general]{{-}{\-}mandir}
725    Note, as of Bacula version 1.39.14, the meaning of any path
726    specified on this option is change from prior versions. It
727    now specifies the top level man directory.
728    Previously the mandir specified the full path to where you
729    wanted the man files installed.
730    The man files will be installed in gzip'ed format under
731    mandir/man1 and mandir/man8 as appropriate.
732    For the install to succeed you must have {\bf gzip} installed
733    on your system.
734
735    By default, Bacula will install the Unix man pages in 
736    /usr/share/man/man1 and /usr/share/man/man8.  
737    If you wish the man page to be installed in
738    a different location, use this option to specify the path.
739    Note, the main HTML and PDF Bacula documents are in a separate
740    tar file that is not part of the source distribution.
741
742 \item [ {-}{\-}datadir=\lt{}path\gt{} ]
743    \index[general]{{-}{\-}datadir}
744    If you translate Bacula or parts of Bacula into a different language
745    you may specify the location of the po files using the {\bf
746    {-}{\-}datadir} option. You must manually install any po files as
747    Bacula does not (yet) automatically do so.
748
749 \item [ {-}{\-}disable-ipv6 ]
750    \index[general]{{-}{\-}disable-ipv6}
751
752 \item [ {-}{\-}enable-smartalloc ]
753    \index[general]{{-}{\-}enable-smartalloc}
754    This enables the inclusion of the Smartalloc orphaned buffer detection
755    code.  This option is highly recommended.  Because we never build
756    without this option, you may experience problems if it is not enabled.
757    In this case, simply re-enable the option.  We strongly recommend
758    keeping this option enabled as it helps detect memory leaks.  This
759    configuration parameter is used while building Bacula
760
761 \item [ {-}{\-}enable-bat ]
762    \label{enablebat}
763    \index[general]{{-}{\-}enable-bat}
764    If you have Qt4 >= 4.3.4 installed on your computer including the
765    libqt4 and libqt4-devel (libqt4-dev on Debian) libraries, and you want
766    to use the Bacula Administration Tool (bat) GUI Console interface to
767    Bacula, you must specify this option.  Doing so will build everything in
768    the {\bf src/qt-console} directory.  The build with enable-bat will work
769    only with a full Bacula build (i.e. it will not work with a client-only
770    build). 
771
772    Qt4 is available on OpenSUSE 10.2, CentOS 5, Fedora, and Debian. If it
773    is not available on your system, you can download the {\bf depkgs-qt}
774    package from the Bacula Source Forge download area and build it.
775    See the
776    INSTALL file in that package for more details. In particular to use
777    the Qt4 built by {\bf depkgs-qt} you {\bf must} source the file
778    {\bf qt4-paths}.
779
780 \item [ {-}{\-}enable-batch-insert ]
781    \index[general]{{-}{\-}enable-batch-insert}
782    This option enables batch inserts of the attribute records (default) in
783     the catalog database, which is much faster (10 times or more) than
784    without this option for large numbers of files. However, this option
785    will automatically be disabled if your SQL libraries are not
786    thread safe. If you find that batch mode is not enabled on your Bacula
787    installation, then your database most likely does not support threads.
788
789    SQLite2 is not thread safe.  Batch insert cannot be enabled when using
790    SQLite2
791
792    On most systems, MySQL, PostgreSQL and SQLite3 are thread safe.
793
794    To verify that your PostgreSQL is thread safe, you can try this
795    (change the path to point to your particular installed libpq.a;
796    these commands were issued on FreeBSD 6.2):
797
798 \begin{verbatim}
799 $ nm /usr/local/lib/libpq.a | grep PQputCopyData
800 00001b08 T PQputCopyData
801 $ nm /usr/local/lib/libpq.a | grep mutex
802          U pthread_mutex_lock
803          U pthread_mutex_unlock
804          U pthread_mutex_init
805          U pthread_mutex_lock
806          U pthread_mutex_unlock
807 \end{verbatim}
808
809    The above example shows a libpq that contains the required function
810    PQputCopyData and is thread enabled (i.e. the pthread\_mutex* entries).
811    If you do not see PQputCopyData, your version of PostgreSQL is too old
812    to allow batch insert.  If you do not see the mutex entries, then thread
813    support has not been enabled. Our tests indicate you usually need to
814    change the configuration options and recompile/reinstall the PostgreSQL
815    client software to get thread support.
816
817    Bacula always links to the thread safe MySQL libraries.
818
819    Running with Batch Insert turned on is recommended because it can
820    significantly improve attribute insertion times. However, it does 
821    put a significantly larger part of the work on your SQL engine, so
822    you may need to pay more attention to tuning it. In particular,   
823    Batch Insert can require large temporary table space, and consequently,
824    the default location (often /tmp) may run out of space causing errors.
825    For MySQL, the location is set in my.conf with "tmpdir".  You may also
826    want to increase the memory available to your SQL engine to further
827    improve performance during Batch Inserts.
828
829 \item [ {-}{\-}enable-bwx-console ]
830    \index[general]{{-}{\-}enable-bwx-console}
831    If you have wxWidgets installed on your computer and you want to use the
832    wxWidgets GUI Console interface to Bacula, you must specify this option.
833    Doing so will build everything in the {\bf src/wx-console} directory.
834    This could also be useful to users who want a GUI Console and don't want
835    to install QT, as wxWidgets can work with GTK+, Motif or even X11
836    libraries.
837
838 \item [ {-}{\-}enable-static-tools]
839    \index[general]{{-}{\-}enable-static-tools}
840    This option causes the linker to link the Storage daemon utility tools
841    ({\bf bls}, {\bf bextract}, and {\bf bscan}) statically.  This permits
842    using them without having the shared libraries loaded.  If you have
843    problems linking in the {\bf src/stored} directory, make sure you have
844    not enabled this option, or explicitly disable static linking by adding
845    {\bf \verb:--:disable-static-tools}.
846
847 \item [ {-}{\-}enable-static-fd]
848    \index[general]{{-}{\-}enable-static-fd}
849    This option causes the make process to build a {\bf static-bacula-fd} in
850    addition to the standard File daemon.  This static version will include
851    statically linked libraries and is required for the Bare Metal recovery.
852    This option is largely superseded by using {\bf make static-bacula-fd}
853    from with in the {\bf src/filed} directory.  Also, the {\bf
854    \verb:--:enable-client-only} option described below is useful for just
855    building a client so that all the other parts of the program are not
856    compiled.   
857      
858    When linking a static binary, the linker needs the static versions
859    of all the libraries that are used, so frequently users will 
860    experience linking errors when this option is used. The first 
861    thing to do is to make sure you have the static glibc library 
862    installed on your system. The second thing to do is the make sure
863    you do not specify {\bf {-}{\-}openssl} or {\bf {-}{\-}with-python}
864    on your ./configure statement as these options require additional
865    libraries. You may be able to enable those options, but you will
866    need to load additional static libraries.
867
868
869 \item [ {-}{\-}enable-static-sd]
870    \index[general]{{-}{\-}enable-static-sd}
871    This option causes the make process to build a {\bf static-bacula-sd} in
872    addition to the standard Storage daemon.  This static version will
873    include statically linked libraries and could be useful during a Bare
874    Metal recovery.
875
876    When linking a static binary, the linker needs the static versions
877    of all the libraries that are used, so frequently users will 
878    experience linking errors when this option is used. The first 
879    thing to do is to make sure you have the static glibc library 
880    installed on your system. The second thing to do is the make sure
881    you do not specify {\bf {-}{\-}openssl} or {\bf {-}{\-}with-python}
882    on your ./configure statement as these options require additional
883    libraries. You may be able to enable those options, but you will
884    need to load additional static libraries.
885
886
887 \item [ {-}{\-}enable-static-dir]
888    \index[general]{{-}{\-}enable-static-dir}
889    This option causes the make process to build a {\bf static-bacula-dir}
890    in addition to the standard Director.  This static version will include
891    statically linked libraries and could be useful during a Bare Metal
892    recovery.
893
894    When linking a static binary, the linker needs the static versions
895    of all the libraries that are used, so frequently users will 
896    experience linking errors when this option is used. The first 
897    thing to do is to make sure you have the static glibc library 
898    installed on your system. The second thing to do is the make sure
899    you do not specify {\bf {-}{\-}openssl} or {\bf {-}{\-}with-python}
900    on your ./configure statement as these options require additional
901    libraries. You may be able to enable those options, but you will
902    need to load additional static libraries.
903
904
905 \item [ {-}{\-}enable-static-cons]
906    \index[general]{{-}{\-}enable-static-cons}
907    This option causes the make process to build a {\bf static-console} in
908    addition to the standard console.  This static version will include
909    statically linked libraries and could be useful during a Bare Metal
910    recovery.
911
912    When linking a static binary, the linker needs the static versions
913    of all the libraries that are used, so frequently users will 
914    experience linking errors when this option is used. The first 
915    thing to do is to make sure you have the static glibc library 
916    installed on your system. The second thing to do is the make sure
917    you do not specify {\bf {-}{\-}openssl} or {\bf {-}{\-}with-python}
918    on your ./configure statement as these options require additional
919    libraries. You may be able to enable those options, but you will
920    need to load additional static libraries.
921
922
923 \item [ {-}{\-}enable-client-only]
924    \index[general]{{-}{\-}enable-client-only}
925    This option causes the make process to build only the File daemon and
926    the libraries that it needs.  None of the other daemons, storage tools,
927    nor the console will be built.  Likewise a {\bf make install} will then
928    only install the File daemon.  To cause all daemons to be built, you
929    will need to do a configuration without this option.  This option
930    greatly facilitates building a Client on a client only machine.
931
932    When linking a static binary, the linker needs the static versions
933    of all the libraries that are used, so frequently users will 
934    experience linking errors when this option is used. The first 
935    thing to do is to make sure you have the static glibc library 
936    installed on your system. The second thing to do is the make sure
937    you do not specify {\bf {-}{\-}openssl} or {\bf {-}{\-}with-python}
938    on your ./configure statement as these options require additional
939    libraries. You may be able to enable those options, but you will
940    need to load additional static libraries.
941
942 \item [ {-}{\-}enable-build-dird]
943    \index[general]{{-}{\-}enable-build-dird}
944    This option causes the make process to build the Director and the
945    Director's tools. By default, this option is on, but you may turn
946    it off by using {\bf {-}{\-}disable-build-dird} to prevent the
947    Director from being built.
948
949 \item [ {-}{\-}enable-build-stored]
950    \index[general]{{-}{\-}enable-build-stored}
951    This option causes the make process to build the Storage daemon.
952    By default, this option is on, but you may turn
953    it off by using {\bf {-}{\-}disable-build-stored} to prevent the
954    Storage daemon from being built.
955
956
957 \item [ {-}{\-}enable-largefile]
958    \index[general]{{-}{\-}enable-largefile}
959    This option (default) causes  Bacula to be built with 64 bit file address
960    support if it  is available on your system. This permits Bacula to read and 
961    write files greater than 2 GBytes in size. You may disable this  feature and
962    revert to 32 bit file addresses by using  {\bf \verb:--:disable-largefile}.  
963
964 \item [ {-}{\-}disable-nls]
965    \index[general]{{-}{\-}disable-nls}
966    By default, Bacula uses the GNU Native Language Support (NLS) libraries. On
967    some machines, these libraries may not be present or may not function 
968    correctly (especially on non-Linux implementations). In such cases, you
969    may specify {\bf {-}{\-}disable-nls} to disable use of those libraries.
970    In such a case, Bacula will revert to using English.
971
972 \item [ {-}{\-}disable-ipv6 ]
973    \index[general]{{-}{\-}disable-ipv6}
974    By default, Bacula enables IPv6 protocol. On some systems, the files
975    for IPv6 may exist, but the functionality could be turned off in the
976    kernel. In that case, in order to correctly build Bacula, you will
977    explicitly need to use this option so that Bacula does not attempt
978    to reference OS function calls that do not exist.
979
980 \item [ {-}{\-}with-sqlite3=\lt{}sqlite3-path\gt{}]
981    \index[general]{{-}{\-}with-sqlite3}
982    This enables use of the SQLite version 3.x database.  The {\bf
983    sqlite3-path} is not normally specified as Bacula looks for the
984    necessary components in a standard location ({\bf depkgs/sqlite3}).  See
985    \ilink{Installing and Configuring SQLite}{SqlLiteChapter} chapter of
986    this manual for more details. SQLite3 is not supported on Solaris.
987
988 \item [ {-}{\-}with-mysql=\lt{}mysql-path\gt{}]
989    \index[general]{{-}{\-}with-mysql}
990    This enables building of the Catalog services for Bacula.  It assumes
991    that MySQL is running on your system, and expects it to be installed in
992    the {\bf mysql-path} that you specify.  Normally, if MySQL is installed
993    in a standard system location, you can simply use {\bf {-}{\-}with-mysql}
994    with no path specification.  If you do use this option, please proceed
995    to installing MySQL in the \ilink{Installing and Configuring MySQL}{MySqlChapter} chapter before proceeding with the configuration.
996
997    See the note below under the {-}{\-}with-postgresql item.
998
999 \item [ {-}{\-}with-postgresql=\lt{}path\gt{}]
1000    \index[general]{{-}{\-}with-postgresql}
1001    This provides an explicit path to the PostgreSQL libraries if Bacula
1002    cannot find it by default.  Normally to build with PostgreSQL, you would
1003    simply use {\bf {-}{\-}with-postgresql}.
1004
1005    Note, for Bacula to be configured properly, you must specify one
1006    of the three database options supported.  That is:
1007    {-}{\-}with-sqlite3, {-}{\-}with-mysql, or
1008    {-}{\-}with-postgresql, otherwise the ./configure will fail.
1009 \smallskip
1010    Note: SQLite is no longer supported.  The code remains in Bacula but
1011    we no longer test it.  
1012
1013
1014 \item [ {-}{\-}with-openssl=\lt{}path\gt{}]
1015    This configuration option is necessary if you want to enable TLS (ssl),
1016    which encrypts the communications within       
1017    Bacula or if you want to use File Daemon PKI data encryption.
1018    Normally, the {\bf path} specification is not necessary since
1019    the configuration searches for the OpenSSL libraries in standard system
1020    locations. However, you must ensure that all the libraries are
1021    loaded including {\bf libssl-dev} or the equivalent on your
1022    system. Enabling OpenSSL in Bacula permits secure communications
1023    between the daemons and/or data encryption in the File daemon.
1024    For more information on using TLS, please see the
1025    \ilink{Bacula TLS -- Communications Encryption}{CommEncryption} chapter
1026    of this manual.
1027    For more information on using PKI data encryption, please see the
1028    \ilink{Bacula PKI -- Data Encryption}{DataEncryption}
1029    chapter of this manual.
1030               
1031    If you get errors linking, you need to load the development libraries,
1032    or you need to disable SSL by setting without-openssl.
1033
1034
1035 \item [ {-}{\-}with-python=\lt{}path\gt{}]
1036    \index[general]{{-}{\-}with-python}
1037    This option enables Bacula support for Python.  If no path is supplied,
1038    configure will search the standard library locations for Python 2.2,
1039    2.3, 2.4, or 2.5.  If it cannot find the library, you will need to
1040    supply a path to your Python library directory.  Please see the
1041    \borgxrlink{Python Scripting}{PythonChapter}{misc}{chapter} of the \miscman{} for the details of using Python
1042    scripting.
1043
1044 \item [ {-}{\-}with-libintl-prefix=\lt{}DIR\gt{}]
1045    \index[general]{{-}{\-}with-libintl-prefix}
1046    This option may be used to tell Bacula to search DIR/include and
1047    DIR/lib for the libintl headers and libraries needed for Native
1048    Language Support (NLS).
1049
1050 \item [ {-}{\-}enable-conio]
1051    \index[general]{{-}{\-}enable-conio}
1052    Tells Bacula to enable building the small, light weight readline
1053    replacement routine.  It is generally much easier to configure than
1054    readline, although, like readline, it needs either the termcap or
1055    ncurses library.
1056
1057 \item [ {-}{\-}with-readline=\lt{}readline-path\gt{}]
1058    \index[general]{{-}{\-}with-readline}
1059    Tells Bacula where {\bf readline} is installed.  Normally, Bacula will
1060    find readline if it is in a standard library.  If it is not found and no
1061    {-}{\-}with-readline is specified, readline will be disabled.  This
1062    option affects the Bacula build.  Readline provides the Console program
1063    with a command line history and editing capability and is no longer
1064    supported, so you are on your own if you have problems.
1065
1066 \item [ {-}{\-}enable-readline]
1067    \index[general]{{-}{\-}enable-readline}
1068    Tells Bacula to enable readline support.  It is normally disabled due to the
1069    large number of configuration  problems and the fact that the package seems to
1070    change in incompatible  ways from version to version.  
1071
1072 \item [ {-}{\-}with-tcp-wrappers=\lt{}path\gt{}]
1073    \index[general]{{-}{\-}with-tcp-wrappers}
1074    \index[general]{TCP Wrappers}
1075    \index[general]{Wrappers!TCP}
1076    \index[general]{libwrappers}
1077    This specifies that you  want TCP wrappers (man hosts\_access(5)) compiled in.
1078    The path is optional since  Bacula will normally find the libraries in the
1079    standard locations.  This option affects the Bacula build.  In specifying your
1080    restrictions in the {\bf /etc/hosts.allow}  or {\bf /etc/hosts.deny} files, do
1081    not use the {\bf twist}  option (hosts\_options(5)) or the Bacula process will
1082    be terminated. Note, when setting up your {\bf /etc/hosts.allow}
1083    or {\bf /etc/hosts.deny}, you must identify the Bacula daemon in
1084    question with the name you give it in your conf file rather than the
1085    name of the executable.
1086    
1087    For more information on configuring and testing TCP wrappers, please  see the 
1088    \ilink{Configuring and Testing TCP Wrappers}{wrappers}  section
1089    in the Security Chapter.  
1090
1091    On SuSE, the libwrappers libraries needed to link Bacula are
1092    contained in the tcpd-devel package. On Red Hat, the package is named
1093    tcp\_wrappers.
1094
1095 \item [ {-}{\-}with-archivedir=\lt{}path\gt{} ]
1096    \index[general]{{-}{\-}with-archivedir}
1097    The directory used for disk-based backups.  Default value is /tmp.
1098    This parameter sets the default values in the bacula-dir.conf and bacula-sd.conf
1099    configuration files.  For example, it sets the Where directive for the
1100    default restore job and the Archive Device directive for the FileStorage
1101    device.
1102
1103    This option is designed primarily for use in regression testing.
1104    Most users can safely ignore this option.
1105
1106 \item [ {-}{\-}with-working-dir=\lt{}working-directory-path\gt{} ]
1107    \index[general]{{-}{\-}with-working-dir}
1108    This option is mandatory and specifies a directory  into which Bacula may
1109    safely place files that  will remain between Bacula executions. For example, 
1110    if the internal database is used, Bacula will keep  those files in this
1111    directory.  This option is only used to modify the daemon  configuration
1112    files. You may also accomplish the same  thing by directly editing them later.
1113    The working directory  is not automatically created by the install process, so
1114    you  must ensure that it exists before using Bacula for the  first time. 
1115
1116 \item [ {-}{\-}with-baseport=\lt{}port=number\gt{}]
1117    \index[general]{{-}{\-}with-baseport}
1118    In order to run,  Bacula needs three TCP/IP ports (one for the Bacula 
1119    Console, one for the Storage daemon, and one for the File daemon).  The {\bf
1120    \verb:--:with-baseport} option will automatically assign three  ports beginning at
1121    the base port address specified. You may  also change the port number in the
1122    resulting configuration  files. However, you need to take care that the
1123    numbers  correspond correctly in each of the three daemon configuration 
1124    files. The default base port is 9101, which assigns ports 9101  through 9103.
1125    These ports (9101, 9102, and 9103) have been  officially assigned to Bacula by
1126    IANA.  This option is only used  to modify the daemon configuration files. You
1127    may also accomplish  the same thing by directly editing them later. 
1128
1129 \item [ {-}{\-}with-dump-email=\lt{}email-address\gt{}]
1130    \index[general]{{-}{\-}with-dump-email}
1131    This option specifies  the email address where any core dumps should be set.
1132    This option  is normally only used by developers.  
1133
1134 \item [ {-}{\-}with-pid-dir=\lt{}PATH\gt{}  ]
1135    \index[general]{{-}{\-}with-pid-dir}
1136    This specifies where Bacula should place the process id  file during
1137    execution. The default is: {\bf /var/run}.  This directory is not created by
1138    the install process, so  you must ensure that it exists before using Bacula
1139    the  first time.  
1140
1141 \item [ {-}{\-}with-subsys-dir=\lt{}PATH\gt{}]
1142    \index[general]{{-}{\-}with-subsys-dir}
1143    This specifies where Bacula should place the subsystem lock  file during
1144    execution. The default is {\bf /var/run/subsys}.  Please make sure that you do
1145    not specify the same directory  for this directory and for the {\bf sbindir}
1146    directory.  This directory is used only within the autostart scripts.  The
1147    subsys directory is not created by the Bacula install,  so you must be sure to
1148    create it before using Bacula. 
1149
1150 \item [ {-}{\-}with-dir-password=\lt{}Password\gt{}]
1151    \index[general]{{-}{\-}with-dir-password}
1152    This option allows you to specify the password used to  access the Director
1153    (normally from the Console program).  If it is not specified, configure will
1154    automatically create a random  password.  
1155
1156 \item [ {-}{\-}with-fd-password=\lt{}Password\gt{} ]
1157    \index[general]{{-}{\-}with-fd-password}
1158    This option allows you to specify the password used to  access the File daemon
1159    (normally called from the Director).  If it is not specified, configure will
1160    automatically create a random  password.  
1161
1162 \item [ {-}{\-}with-sd-password=\lt{}Password\gt{} ]
1163    \index[general]{{-}{\-}with-sd-password}
1164    This option allows you to specify the password used to access the Storage daemon
1165    (normally called from the Director).  If it is not specified, configure will
1166    automatically create a random  password.  
1167
1168 \item [ {-}{\-}with-dir-user=\lt{}User\gt{} ]
1169    \index[general]{{-}{\-}with-dir-user}
1170    This option allows you to specify the Userid used to run the Director.  The
1171    Director must be started as root, but doesn't need to run as root, and
1172    after doing preliminary initializations, it can "drop" to the UserId
1173    specified on this option.  
1174    If you specify this option, you must
1175    create the User prior to running {\bf make install}, because the
1176    working directory owner will be set to {\bf User}.
1177                        
1178 \item [ {-}{\-}with-dir-group=\lt{}Group\gt{} ]
1179    \index[general]{{-}{\-}with-dir-group}
1180    This option allows you to specify the GroupId used to  run the Director. The
1181    Director must be started as root, but  doesn't need to run as root, and  after
1182    doing preliminary initializations, it can "drop"  to the GroupId specified
1183    on this option. 
1184    If you specify this option, you must
1185    create the Group prior to running {\bf make install}, because the
1186    working directory group will be set to {\bf Group}.
1187
1188 \item [ {-}{\-}with-sd-user=\lt{}User\gt{} ]
1189    \index[general]{{-}{\-}with-sd-user}
1190    This option allows you to specify the Userid used to  run the Storage daemon.
1191    The Storage daemon must be started as root, but  doesn't need to run as root,
1192    and  after doing preliminary initializations, it can "drop"  to the UserId
1193    specified on this option. If you use this option,  you will need to take care
1194    that the Storage daemon has access  to all the devices (tape drives, ...) that
1195    it needs. 
1196
1197 \item [ {-}{\-}with-sd-group=\lt{}Group\gt{} ]
1198    \index[general]{{-}{\-}with-sd-group}
1199    This option allows you to specify the GroupId used to  run the Storage daemon.
1200    The Storage daemon must be started as root, but  doesn't need to run as root,
1201    and  after doing preliminary initializations, it can "drop"  to the GroupId
1202    specified on this option. 
1203
1204 \item [ {-}{\-}with-fd-user=\lt{}User\gt{} ]
1205    \index[general]{{-}{\-}with-fd-user}
1206    This option allows you to specify the Userid used to  run the File daemon. The
1207    File daemon must be started as root,  and in most cases, it needs to run as
1208    root, so this option is  used only in very special cases,  after doing
1209    preliminary initializations, it can "drop"  to the UserId specified on this
1210    option. 
1211
1212 \item [ {-}{\-}with-fd-group=\lt{}Group\gt{} ]
1213    \index[general]{{-}{\-}with-fd-group}
1214    This option allows you to specify the GroupId used to  run the File daemon.
1215    The File daemon must be started as root, and  in most cases, it must be run as
1216    root, however,  after doing preliminary initializations, it can "drop"  to
1217    the GroupId specified on this option. 
1218
1219 \item [ {-}{\-}with-mon-dir-password=\lt{}Password\gt{}]
1220    \index[general]{{-}{\-}with-mon-dir-password}
1221    This option allows you to specify the password used to  access the Directory
1222    from the monitor.  If it is not specified, configure will
1223    automatically create a random  password.  
1224
1225 \item [ {-}{\-}with-mon-fd-password=\lt{}Password\gt{} ]
1226    \index[general]{{-}{\-}with-mon-fd-password}
1227    This option allows you to specify the password used to  access the File daemon
1228    from the Monitor.  If it is not specified, configure will
1229    automatically create a random  password.  
1230
1231 \item [ {-}{\-}with-mon-sd-password=\lt{}Password\gt{} ]
1232    \index[general]{{-}{\-}with-mon-sd-password}
1233    This option allows you to specify the password used to  access the
1234    Storage daemon from the Monitor. If it is not specified, configure will
1235    automatically create a random  password.  
1236
1237 \item [ {-}{\-}with-db-name=\lt{}database-name\gt{} ]
1238    \index[general]{{-}{\-}with-db-name}
1239    This option allows you to specify the database name to be used in
1240    the conf files.  The default is bacula.
1241
1242 \item [ {-}{\-}with-db-user=\lt{}database-user\gt{} ]
1243    \index[general]{{-}{\-}with-db-user}
1244    This option allows you to specify the database user name to be used in
1245    the conf files.  The default is bacula.
1246
1247 \end{description}
1248
1249 Note, many other options are presented when you do a {\bf ./configure
1250 \verb:--:help}, but they are not implemented.
1251
1252 \section{Recommended Options for Most Systems}
1253 \index[general]{Systems!Recommended Options for Most}
1254 \index[general]{Recommended Options for Most Systems}
1255
1256 For most systems, we recommend starting with the following options: 
1257
1258 \footnotesize
1259 \begin{verbatim}
1260 ./configure \
1261   --enable-smartalloc \
1262   --sbindir=/opt/bacula/bin \
1263   --sysconfdir=/opt/bacula/etc \
1264   --with-pid-dir=/opt/bacula/working \
1265   --with-subsys-dir=/opt/bacula/working \
1266   --with-working-dir=/opt/bacula/working
1267 \end{verbatim}
1268 \normalsize
1269
1270 If you want to install Bacula in an installation directory rather than run it
1271 out of the build directory (as developers will do most of the time), you
1272 should also include the \verb:--:sbindir and \verb:--:sysconfdir options with appropriate
1273 paths. Neither are necessary if you do not use "make install" as is the case
1274 for most development work. The install process will create the sbindir and
1275 sysconfdir if they do not exist, but it will not automatically create the
1276 pid-dir, subsys-dir, or working-dir, so you must ensure that they exist before
1277 running Bacula for the first time.
1278
1279 \section{Red Hat}
1280 \index[general]{Red Hat}
1281
1282 Using SQLite: 
1283
1284 \footnotesize
1285 \begin{verbatim}
1286  
1287 CFLAGS="-g -Wall" ./configure \
1288   --sbindir=/opt/bacula/bin \
1289   --sysconfdir=/opt/bacula/etc \
1290   --enable-smartalloc \
1291   --with-sqlite=$HOME/bacula/depkgs/sqlite \
1292   --with-working-dir=/opt/bacula/working \
1293   --with-pid-dir=/opt/bacula/working \
1294   --with-subsys-dir=/opt/bacula/working \
1295   --enable-bat \
1296   --enable-readline
1297 \end{verbatim}
1298 \normalsize
1299
1300 or 
1301
1302 \footnotesize
1303 \begin{verbatim}
1304  
1305 CFLAGS="-g -Wall" ./configure \
1306   --sbindir=/opt/bacula/bin \
1307   --sysconfdir=/opt/bacula/etc \
1308   --enable-smartalloc \
1309   --with-mysql \
1310   --with-working-dir=/opt/bacula/working
1311   --with-pid-dir=/opt/bacula/working \
1312   --with-subsys-dir=/opt/bacula/working
1313   --enable-readline
1314 \end{verbatim}
1315 \normalsize
1316
1317 or finally, a completely traditional Red Hat Linux install,
1318 which we do not recommend, because it make it harder to
1319 backup Bacula for disaster recovery purposes:
1320
1321 \footnotesize
1322 \begin{verbatim}
1323 CFLAGS="-g -Wall" ./configure \
1324   --sbindir=/usr/sbin \
1325   --sysconfdir=/etc/bacula \
1326   --with-scriptdir=/etc/bacula \
1327   --enable-smartalloc \
1328   --enable-bat \
1329   --with-mysql \
1330   --with-working-dir=/var/bacula \
1331   --with-pid-dir=/var/run \
1332   --enable-readline
1333 \end{verbatim}
1334 \normalsize
1335
1336 Note, Bacula assumes that /var/bacula, /var/run, and /var/lock/subsys exist so
1337 it will not automatically create them during the install process. 
1338
1339 \section{Solaris}
1340 \index[general]{Solaris}
1341
1342 To build Bacula from source, you will need the following installed on your
1343 system (they are not by default): libiconv, gcc 3.3.2, stdc++, libgcc (for
1344 stdc++ and gcc\_s libraries), make 3.8 or later. 
1345
1346 You will probably also need to: Add /usr/local/bin to PATH and Add
1347 /usr/ccs/bin to PATH for ar. 
1348
1349 It is possible to build Bacula on Solaris with the Solaris compiler, but
1350 we recommend using GNU C++ if possible.  
1351
1352 A typical configuration command might look like:
1353
1354 \footnotesize
1355 \begin{verbatim}
1356 #!/bin/sh
1357 CFLAGS="-g" ./configure \
1358   --sbindir=/opt/bacula/bin \
1359   --sysconfdir=/opt/bacula/etc \
1360   --with-mysql \
1361   --enable-smartalloc \
1362   --with-pid-dir=/opt/bacula/working \
1363   --with-subsys-dir=/opt/bacula/working \
1364   --with-working-dir=/opt/bacula/working
1365 \end{verbatim}
1366 \normalsize
1367
1368 Note, you may need to install the following packages to build Bacula
1369 from source:
1370 \footnotesize
1371 \begin{verbatim}
1372 SUNWbinutils,
1373 SUNWarc,
1374 SUNWhea,
1375 SUNWGcc,
1376 SUNWGnutls
1377 SUNWGnutls-devel
1378 SUNWGmake
1379 SUNWgccruntime
1380 SUNWlibgcrypt
1381 SUNWzlib
1382 SUNWzlibs
1383 SUNWreadline
1384 SUNWbinutilsS
1385 SUNWGmakeS
1386 SUNWlibm
1387
1388 export 
1389 PATH=/usr/bin::/usr/ccs/bin:/etc:/usr/openwin/bin:/usr/local/bin:/usr/sfw/bin:/opt/sfw/bin:/usr/ucb:/usr/sbin
1390 \end{verbatim}
1391 \normalsize
1392
1393 If you have installed special software not normally in the Solaris
1394 libraries, such as OpenSSL, or the packages shown above, then you may need
1395 to add {\bf /usr/sfw/lib} to the library search path.  Probably the
1396 simplest way to do so is to run:
1397
1398 \footnotesize
1399 \begin{verbatim}
1400 setenv LDFLAGS "-L/usr/sfw/lib -R/usr/sfw/lib"
1401 \end{verbatim}
1402 \normalsize
1403
1404 Prior to running the ./configure command.
1405
1406 Alternatively, you can set the LD\_LIBARY\_PATH and/or the LD\_RUN\_PATH
1407 environment variables appropriately.
1408
1409 It is also possible to use the {\bf crle} program to set the library
1410 search path.  However, this should be used with caution.
1411
1412 \section{FreeBSD}
1413 \index[general]{FreeBSD}
1414
1415 Please see: 
1416 \elink{The FreeBSD Diary}{http://www.freebsddiary.org/bacula.php} for a
1417 detailed description on how to make Bacula work on your system. In addition,
1418 users of FreeBSD prior to 4.9-STABLE dated Mon Dec 29 15:18:01 2003 UTC who
1419 plan to use tape devices, please see the 
1420 \borgxrlink{Tape Testing}{FreeBSDTapes}{problems}{chapter} of the \problemsman{} for
1421 {\bf important} information on how to configure your tape drive for
1422 compatibility with Bacula. 
1423
1424 If you are using Bacula with MySQL, you should take care to compile MySQL with
1425 FreeBSD native threads rather than LinuxThreads, since Bacula is normally built
1426 with FreeBSD native threads rather than LinuxTreads. Mixing the two will
1427 probably not work. 
1428
1429 \section{Win32}
1430 \index[general]{Win32}
1431
1432 To install the binary Win32 version of the File daemon please see the 
1433 \ilink{Win32 Installation Chapter}{Win32Chapter} in this document. 
1434
1435 \section{One File Configure Script}
1436 \index[general]{Script!One File Configure}
1437 \index[general]{One Files Configure Script}
1438
1439 The following script could be used if you want to put everything
1440 in a single directory (except for the working directory):
1441
1442 \footnotesize
1443 \begin{verbatim}
1444 #!/bin/sh
1445 CFLAGS="-g -Wall" \
1446   ./configure \
1447     --sbindir=$HOME/bacula/bin \
1448     --sysconfdir=$HOME/bacula/bin \
1449     --mandir=$HOME/bacula/bin \
1450     --enable-smartalloc \
1451     --enable-bat \
1452     --with-pid-dir=$HOME/bacula/bin/working \
1453     --with-subsys-dir=$HOME/bacula/bin/working \
1454     --with-mysql \
1455     --with-working-dir=$HOME/bacula/bin/working \
1456     --with-dump-email=$USER@your-site.com \
1457     --with-job-email=$USER@your-site.com \
1458     --with-smtp-host=mail.your-site.com
1459 exit 0
1460 \end{verbatim}
1461 \normalsize
1462
1463 You may also want to put the following entries in your {\bf /etc/services}
1464 file as it will make viewing the connections made by Bacula easier to
1465 recognize (i.e. netstat -a): 
1466
1467 \footnotesize
1468 \begin{verbatim}
1469 bacula-dir      9101/tcp
1470 bacula-fd       9102/tcp
1471 bacula-sd       9103/tcp
1472 \end{verbatim}
1473 \normalsize
1474
1475 \section{Installing Bacula}
1476 \index[general]{Bacula!Installing}
1477 \index[general]{Installing Bacula}
1478
1479 Before setting up your configuration files, you will want to install Bacula in
1480 its final location. Simply enter: 
1481
1482 \footnotesize
1483 \begin{verbatim}
1484 make install
1485 \end{verbatim}
1486 \normalsize
1487
1488 If you have previously installed Bacula, the old binaries will be overwritten,
1489 but the old configuration files will remain unchanged, and the "new"
1490 configuration files will be appended with a {\bf .new}. Generally if you have
1491 previously installed and run Bacula you will want to discard or ignore the
1492 configuration files with the appended {\bf .new}. 
1493
1494 \section{Building a File Daemon or Client}
1495 \index[general]{Client!Building a File Daemon or}
1496 \index[general]{Building a File Daemon or Client}
1497
1498 If you run the Director and the Storage daemon on one machine and you wish to
1499 back up another machine, you must have a copy of the File daemon for that
1500 machine. If the machine and the Operating System are identical, you can simply
1501 copy the Bacula File daemon binary file {\bf bacula-fd} as well as its
1502 configuration file {\bf bacula-fd.conf} then modify the name and password in
1503 the conf file to be unique. Be sure to make corresponding additions to the
1504 Director's configuration file ({\bf bacula-dir.conf}). 
1505
1506 If the architecture or the OS level are different, you will need to build a
1507 File daemon on the Client machine. To do so, you can use the same {\bf
1508 ./configure} command as you did for your main program, starting either from a
1509 fresh copy of the source tree, or using {\bf make\ distclean} before the {\bf
1510 ./configure}. 
1511
1512 Since the File daemon does not access the Catalog database, you can remove
1513 the {\bf \verb:--:with-mysql} or {\bf \verb:--:with-sqlite} options, then
1514 add {\bf \verb:--:enable-client-only}.  This will compile only the
1515 necessary libraries and the client programs and thus avoids the necessity
1516 of installing one or another of those database programs to build the File
1517 daemon.  With the above option, you simply enter {\bf make} and just the
1518 client will be built.
1519
1520 \label{autostart}
1521 \section{Auto Starting the Daemons}
1522 \index[general]{Daemons!Auto Starting the}
1523 \index[general]{Auto Starting the Daemons}
1524
1525 If you wish the daemons to be automatically started and stopped when your
1526 system is booted (a good idea), one more step is necessary. First, the
1527 ./configure process must recognize your system -- that is it must be a
1528 supported platform and not {\bf unknown}, then you must install the platform
1529 dependent files by doing: 
1530
1531 \footnotesize
1532 \begin{verbatim}
1533 (become root)
1534 make install-autostart
1535 \end{verbatim}
1536 \normalsize
1537
1538 Please note, that the auto-start feature is implemented only on systems
1539 that we officially support (currently, FreeBSD, Red Hat/Fedora Linux, and
1540 Solaris), and has only been fully tested on Fedora Linux.
1541
1542 The {\bf make install-autostart} will cause the appropriate startup scripts
1543 to be installed with the necessary symbolic links.  On Red Hat/Fedora Linux
1544 systems, these scripts reside in {\bf /etc/rc.d/init.d/bacula-dir} {\bf
1545 /etc/rc.d/init.d/bacula-fd}, and {\bf /etc/rc.d/init.d/bacula-sd}.  However
1546 the exact location depends on what operating system you are using.
1547
1548 If you only wish to install the File daemon, you may do so with: 
1549
1550 \footnotesize
1551 \begin{verbatim}
1552 make install-autostart-fd
1553 \end{verbatim}
1554 \normalsize
1555
1556 \section{Other Make Notes}
1557 \index[general]{Notes!Other Make}
1558 \index[general]{Other Make Notes}
1559
1560 To simply build a new executable in any directory, enter: 
1561
1562 \footnotesize
1563 \begin{verbatim}
1564 make
1565 \end{verbatim}
1566 \normalsize
1567
1568 To clean out all the objects and binaries (including the files named 1, 2, or
1569 3, which are development temporary files), enter: 
1570
1571 \footnotesize
1572 \begin{verbatim}
1573 make clean
1574 \end{verbatim}
1575 \normalsize
1576
1577 To really clean out everything for distribution, enter: 
1578
1579 \footnotesize
1580 \begin{verbatim}
1581 make distclean
1582 \end{verbatim}
1583 \normalsize
1584
1585 note, this cleans out the Makefiles and is normally done from the top level
1586 directory to prepare for distribution of the source. To recover from this
1587 state, you must redo the {\bf ./configure} in the top level directory, since
1588 all the Makefiles will be deleted. 
1589
1590 To add a new file in a subdirectory, edit the Makefile.in in that directory,
1591 then simply do a {\bf make}. In most cases, the make will rebuild the Makefile
1592 from the new Makefile.in. In some case, you may need to issue the {\bf make} a
1593 second time. In extreme cases, cd to the top level directory and enter: {\bf
1594 make Makefiles}. 
1595
1596 To add dependencies: 
1597
1598 \footnotesize
1599 \begin{verbatim}
1600 make depend
1601 \end{verbatim}
1602 \normalsize
1603
1604 The {\bf make depend} appends the header file dependencies for each of the
1605 object files to Makefile and Makefile.in. This command should be done in each
1606 directory where you change the dependencies. Normally, it only needs to be run
1607 when you add or delete source or header files. {\bf make depend} is normally
1608 automatically invoked during the configuration process. 
1609
1610 To install: 
1611
1612 \footnotesize
1613 \begin{verbatim}
1614 make install
1615 \end{verbatim}
1616 \normalsize
1617
1618 This not normally done if you are developing Bacula, but is used if you are
1619 going to run it to backup your system. 
1620
1621 After doing a {\bf make install} the following files will be installed on your
1622 system (more or less). The exact files and location (directory) for each file
1623 depends on your {\bf ./configure} command (e.g. if you are using SQLite instead
1624 of MySQL, some of the files will be different).
1625
1626 NOTE: it is quite probable that this list is out of date.  But it is a
1627 starting point.
1628
1629 \footnotesize
1630 \begin{verbatim}
1631 bacula
1632 bacula-dir
1633 bacula-dir.conf
1634 bacula-fd
1635 bacula-fd.conf
1636 bacula-sd
1637 bacula-sd.conf
1638 bextract
1639 bls
1640 bscan
1641 btape
1642 btraceback
1643 btraceback.gdb
1644 bconsole
1645 bconsole.conf
1646 create_mysql_database
1647 dbcheck
1648 delete_catalog_backup
1649 drop_bacula_tables
1650 drop_mysql_tables
1651 make_bacula_tables
1652 make_catalog_backup
1653 make_mysql_tables
1654 mtx-changer
1655 query.sql
1656 bsmtp
1657 startmysql
1658 stopmysql
1659 bwx-console
1660 bwx-console.conf
1661 9 man pages
1662 \end{verbatim}
1663 \normalsize
1664
1665 \label{monitor}
1666
1667 \section{Modifying the Bacula Configuration Files}
1668 \index[general]{Modifying the Bacula Configuration Files}
1669 \index[general]{Files!Modifying the Bacula Configuration}
1670
1671 See the chapter 
1672 \ilink{Configuring Bacula}{ConfigureChapter} in this manual for
1673 instructions on how to set Bacula configuration files.