4 \chapter{A Brief Tutorial}
5 \label{TutorialChapter}
6 \index[general]{Brief Tutorial }
7 \index[general]{Tutorial!Brief }
9 This chapter will guide you through running Bacula. To do so, we assume you
10 have installed Bacula, possibly in a single file as shown in the previous
11 chapter, in which case, you can run Bacula as non-root for these tests.
12 However, we assume that you have not changed the .conf files. If you have
13 modified the .conf files, please go back and uninstall Bacula, then reinstall
14 it, but do not make any changes. The examples in this chapter use the default
15 configuration files, and will write the volumes to disk in your {\bf /tmp}
16 directory, in addition, the data backed up will be the source directory where
17 you built Bacula. As a consequence, you can run all the Bacula daemons for
18 these tests as non-root. Please note, in production, your File daemon(s) must
19 run as root. See the Security chapter for more information on this subject.
21 % TODO: use crossreferences above
22 % TODO: add a section here
24 The general flow of running Bacula is:
27 \item cd \lt{}install-directory\gt{}
28 \item Start the Database (if using MySQL or PostgreSQL)
29 \item Start the Daemons with {\bf ./bacula start}
30 \item Start the Console program to interact with the Director
32 \item When the Volume fills, unmount the Volume, if it is a tape, label a new
33 one, and continue running. In this chapter, we will write only to disk files
34 so you won't need to worry about tapes for the moment.
35 \item Test recovering some files from the Volume just written to ensure the
36 backup is good and that you know how to recover. Better test before disaster
38 \item Add a second client.
41 Each of these steps is described in more detail below.
43 \section{Before Running Bacula}
44 \index[general]{Bacula!Before Running }
45 \index[general]{Before Running Bacula }
47 % TODO: some of this content is already covered once or twice critical
48 % TODO: or quickstart. Consolidate!
50 Before running Bacula for the first time in production, we recommend that you
51 run the {\bf test} command in the {\bf btape} program as described in the
52 \ilink{Utility Program Chapter}{btape} of this manual. This will
53 help ensure that Bacula functions correctly with your tape drive. If you have
54 a modern HP, Sony, or Quantum DDS or DLT tape drive running on Linux or
55 Solaris, you can probably skip this test as Bacula is well tested with these
56 drives and systems. For all other cases, you are {\bf strongly} encouraged to
57 run the test before continuing. {\bf btape} also has a {\bf fill} command that
58 attempts to duplicate what Bacula does when filling a tape and writing on the
59 next tape. You should consider trying this command as well, but be forewarned,
60 it can take hours (about four hours on my drive) to fill a large capacity tape.
62 \section{Starting the Database}
64 \index[general]{Starting the Database }
65 \index[general]{Database!Starting the }
67 If you are using MySQL or PostgreSQL as the Bacula database, you should start
68 it before you attempt to run a job to avoid getting error messages from Bacula
69 when it starts. The scripts {\bf startmysql} and {\bf stopmysql} are what I
70 (Kern) use to start and stop my local MySQL. Note, if you are using SQLite,
71 you will not want to use {\bf startmysql} or {\bf stopmysql}. If you are
72 running this in production, you will probably want to find some way to
73 automatically start MySQL or PostgreSQL after each system reboot.
75 If you are using SQLite (i.e. you specified the {\bf \verb:--:with-sqlite=xxx} option
76 on the {\bf ./configure} command, you need do nothing. SQLite is automatically
77 started by {\bf Bacula}.
79 \section{Starting the Daemons}
81 \index[general]{Starting the Daemons }
82 \index[general]{Daemons!Starting the }
84 Assuming you have built from source or have installed the rpms,
85 to start the three daemons, from your installation directory, simply enter:
89 The {\bf bacula} script starts the Storage daemon, the File daemon, and the
90 Director daemon, which all normally run as daemons in the background. If you
91 are using the autostart feature of Bacula, your daemons will either be
92 automatically started on reboot, or you can control them individually with the
93 files {\bf bacula-dir}, {\bf bacula-fd}, and {\bf bacula-sd}, which are
94 usually located in {\bf /etc/init.d}, though the actual location is system
96 Some distributions may do this differently.
98 Note, on Windows, currently only the File daemon is ported, and it must be
99 started differently. Please see the
100 \ilink{Windows Version of Bacula}{Win32Chapter} Chapter of this
103 The rpm packages configure the daemons to run as user=root and group=bacula.
104 The rpm installation also creates the group bacula if it does not exist on the
105 system. Any users that you add to the group bacula will have access to files
106 created by the daemons. To disable or alter this behavior edit the daemon
110 \item /etc/bacula/bacula
111 \item /etc/init.d/bacula-dir
112 \item /etc/init.d/bacula-sd
113 \item /etc/init.d/bacula-fd
116 and then restart as noted above.
119 \ilink{installation chapter}{InstallChapter} of this manual
120 explains how you can install scripts that will automatically restart the
121 daemons when the system starts.
123 \section{Using the Director to Query and Start Jobs}
124 \index[general]{Jobs!Querying or Starting Jobs}
125 \index[general]{Querying or starting Jobs}
126 % TODO: section name is too long; maybe use "Using the Console Program" ??
128 To communicate with the director and to query the state of Bacula or run jobs,
129 from the top level directory, simply enter:
133 Alternatively to running the command line console, if you have
134 Qt4 installed and used the {\bf \verb:--:enable-bat} on the configure command,
135 you may use the Bacula Administration Tool ({\bf bat}):
139 Which has a graphical interface, and many more features than bconsole.
141 Two other possibilities are to run the GNOME console
142 {\bf bgnome-console} or the wxWidgets program {\bf bwx-console}.
144 For simplicity, here we will describe only the {\bf ./bconsole} program. Most
145 of what is described here applies equally well to {\bf ./bat},
146 {\bf ./bgnome-console}, and to {\bf bwx-console}.
148 The {\bf ./bconsole} runs the Bacula Console program, which connects to the
149 Director daemon. Since Bacula is a network program, you can run the Console
150 program anywhere on your network. Most frequently, however, one runs it on the
151 same machine as the Director. Normally, the Console program will print
152 something similar to the following:
156 [kern@polymatou bin]$ ./bconsole
157 Connecting to Director lpmatou:9101
158 1000 OK: HeadMan Version: 2.1.8 (14 May 2007)
163 the asterisk is the console command prompt.
165 Type {\bf help} to see a list of available commands:
172 add add media to a pool
173 autodisplay autodisplay [on|off] -- console messages
174 automount automount [on|off] -- after label
175 cancel cancel [<jobid=nnn> | <job=name>] -- cancel a job
176 create create DB Pool from resource
177 delete delete [pool=<pool-name> | media volume=<volume-name>]
178 disable disable <job=name> -- disable a job
179 enable enable <job=name> -- enable a job
180 estimate performs FileSet estimate, listing gives full listing
182 gui gui [on|off] -- non-interactive gui mode
183 help print this command
184 list list [pools | jobs | jobtotals | media <pool=pool-name> |
185 files <jobid=nn>]; from catalog
187 llist full or long list like list command
188 memory print current memory usage
190 mount mount <storage-name>
191 prune prune expired records from catalog
192 purge purge records from catalog
193 python python control commands
196 restore restore files
197 relabel relabel a tape
198 release release <storage-name>
199 reload reload conf file
201 status status [storage | client]=<name>
202 setdebug sets debug level
203 setip sets new client address -- if authorized
204 show show (resource records) [jobs | pools | ... | all]
205 sqlquery use SQL to query catalog
206 time print current time
207 trace turn on/off trace to file
208 unmount unmount <storage-name>
209 umount umount <storage-name> for old-time Unix guys
210 update update Volume, Pool or slots
212 var does variable expansion
213 version print Director version
214 wait wait until no jobs are running [<jobname=name> | <jobid=nnn> | <ujobid=complete_name>]
219 Details of the console program's commands are explained in the
220 \ilink{Console Chapter}{_ConsoleChapter} of this manual.
222 \section{Running a Job}
224 \index[general]{Job!Running a }
225 \index[general]{Running a Job }
227 At this point, we assume you have done the following:
230 \item Configured Bacula with {\bf ./configure \verb:--:your-options}
231 \item Built Bacula using {\bf make}
232 \item Installed Bacula using {\bf make install}
233 \item Have created your database with, for example, {\bf
234 ./create\_sqlite\_database}
235 \item Have created the Bacula database tables with, {\bf
236 ./make\_bacula\_tables}
237 \item Have possibly edited your {\bf bacula-dir.conf} file to personalize it
238 a bit. BE CAREFUL! if you change the Director's name or password, you will
239 need to make similar modifications in the other .conf files. For the moment
240 it is probably better to make no changes.
241 \item You have started Bacula with {\bf ./bacula start}
242 \item You have invoked the Console program with {\bf ./bconsole}
245 Furthermore, we assume for the moment you are using the default configuration
248 At this point, enter the following command:
256 and you should get something similar to:
260 FileSet: name=Full Set
263 I /home/kern/bacula/regress/build
270 FileSet: name=Catalog
273 I /home/kern/bacula/regress/working/bacula.sql
278 This is a pre-defined {\bf FileSet} that will backup the Bacula source
279 directory. The actual directory names printed should correspond to your system
280 configuration. For testing purposes, we have chosen a directory of moderate
281 size (about 40 Megabytes) and complexity without being too big. The FileSet
282 {\bf Catalog} is used for backing up Bacula's catalog and is not of interest
283 to us for the moment. The {\bf I} entries are the files or directories that
284 will be included in the backup and the {\bf E} are those that will be
285 excluded, and the {\bf O} entries are the options specified for
286 the FileSet. You can change what is backed up by editing {\bf bacula-dir.conf}
287 and changing the {\bf File =} line in the {\bf FileSet} resource.
289 Now is the time to run your first backup job. We are going to backup your
290 Bacula source directory to a File Volume in your {\bf /tmp} directory just to
291 show you how easy it is. Now enter:
299 and you should get the following output:
303 rufus-dir Version: 1.30 (28 April 2003)
304 Daemon started 28-Apr-2003 14:03, 0 Jobs run.
305 Console connected at 28-Apr-2003 14:03
307 Level Type Scheduled Name
308 =================================================================
309 Incremental Backup 29-Apr-2003 01:05 Client1
310 Full Backup 29-Apr-2003 01:10 BackupCatalog
315 where the times and the Director's name will be different according to your
316 setup. This shows that an Incremental job is scheduled to run for the Job {\bf
317 Client1} at 1:05am and that at 1:10, a {\bf BackupCatalog} is scheduled to
318 run. Note, you should probably change the name {\bf Client1} to be the name of
319 your machine, if not, when you add additional clients, it will be very
320 confusing. For my real machine, I use {\bf Rufus} rather than {\bf Client1} as
331 and you should get something like:
335 The defined Client resources are:
337 Item 1 selected automatically.
338 Connecting to Client rufus-fd at rufus:8102
339 rufus-fd Version: 1.30 (28 April 2003)
340 Daemon started 28-Apr-2003 14:03, 0 Jobs run.
341 Director connected at: 28-Apr-2003 14:14
347 In this case, the client is named {\bf rufus-fd} your name will be different,
348 but the line beginning with {\bf rufus-fd Version ...} is printed by your File
349 daemon, so we are now sure it is up and running.
351 Finally do the same for your Storage daemon with:
363 The defined Storage resources are:
365 Item 1 selected automatically.
366 Connecting to Storage daemon File at rufus:8103
367 rufus-sd Version: 1.30 (28 April 2003)
368 Daemon started 28-Apr-2003 14:03, 0 Jobs run.
369 Device /tmp is not open.
375 You will notice that the default Storage daemon device is named {\bf File} and
376 that it will use device {\bf /tmp}, which is not currently open.
378 Now, let's actually run a job with:
386 you should get the following output:
390 Using default Catalog name=MyCatalog DB=bacula
391 A job name must be specified.
392 The defined Job resources are:
396 Select Job resource (1-3):
400 Here, Bacula has listed the three different Jobs that you can run, and you
401 should choose number {\bf 1} and type enter, at which point you will get:
412 When: 2003-04-28 14:18:57
413 OK to run? (yes/mod/no):
417 At this point, take some time to look carefully at what is printed and
418 understand it. It is asking you if it is OK to run a job named {\bf Client1}
419 with FileSet {\bf Full Set} (we listed above) as an Incremental job on your
420 Client (your client name will be different), and to use Storage {\bf File} and
421 Pool {\bf Default}, and finally, it wants to run it now (the current time
422 should be displayed by your console).
424 Here we have the choice to run ({\bf yes}), to modify one or more of the above
425 parameters ({\bf mod}), or to not run the job ({\bf no}). Please enter {\bf
426 yes}, at which point you should immediately get the command prompt (an
427 asterisk). If you wait a few seconds, then enter the command {\bf messages}
428 you will get back something like:
432 28-Apr-2003 14:22 rufus-dir: Last FULL backup time not found. Doing
434 28-Apr-2003 14:22 rufus-dir: Start Backup JobId 1,
435 Job=Client1.2003-04-28_14.22.33
436 28-Apr-2003 14:22 rufus-sd: Job Client1.2003-04-28_14.22.33 waiting.
437 Cannot find any appendable volumes.
438 Please use the "label" command to create a new Volume for:
445 The first message, indicates that no previous Full backup was done, so Bacula
446 is upgrading our Incremental job to a Full backup (this is normal). The second
447 message indicates that the job started with JobId 1., and the third message
448 tells us that Bacula cannot find any Volumes in the Pool for writing the
449 output. This is normal because we have not yet created (labeled) any Volumes.
450 Bacula indicates to you all the details of the volume it needs.
452 At this point, the job is BLOCKED waiting for a Volume. You can check this if
453 you want by doing a {\bf status dir}. In order to continue, we must create a
454 Volume that Bacula can write on. We do so with:
462 and Bacula will print:
466 The defined Storage resources are:
468 Item 1 selected automatically.
469 Enter new Volume name:
473 at which point, you should enter some name beginning with a letter and
474 containing only letters and numbers (period, hyphen, and underscore) are also
475 permitted. For example, enter {\bf TestVolume001}, and you should get back:
481 Item 1 selected automatically.
482 Connecting to Storage daemon File at rufus:8103 ...
483 Sending label command for Volume "TestVolume001" Slot 0 ...
484 3000 OK label. Volume=TestVolume001 Device=/tmp
485 Catalog record for Volume "TestVolume002", Slot 0 successfully created.
486 Requesting mount FileStorage ...
487 3001 OK mount. Device=/tmp
491 Finally, enter {\bf messages} and you should get something like:
495 28-Apr-2003 14:30 rufus-sd: Wrote label to prelabeled Volume
496 "TestVolume001" on device /tmp
497 28-Apr-2003 14:30 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:30
499 Job: Client1.2003-04-28_14.22.33
503 Start time: 28-Apr-2003 14:22
504 End time: 28-Apr-2003 14:30
506 Bytes Written: 38,988,877
508 Software Compression: None
509 Volume names(s): TestVolume001
511 Volume Session Time: 1051531381
512 Last Volume Bytes: 39,072,359
513 FD termination status: OK
514 SD termination status: OK
515 Termination: Backup OK
516 28-Apr-2003 14:30 rufus-dir: Begin pruning Jobs.
517 28-Apr-2003 14:30 rufus-dir: No Jobs found to prune.
518 28-Apr-2003 14:30 rufus-dir: Begin pruning Files.
519 28-Apr-2003 14:30 rufus-dir: No Files found to prune.
520 28-Apr-2003 14:30 rufus-dir: End auto prune.
524 If you don't see the output immediately, you can keep entering {\bf messages}
525 until the job terminates, or you can enter, {\bf autodisplay on} and your
526 messages will automatically be displayed as soon as they are ready.
528 If you do an {\bf ls -l} of your {\bf /tmp} directory, you will see that you
529 have the following item:
533 -rw-r----- 1 kern kern 39072153 Apr 28 14:30 TestVolume001
537 This is the file Volume that you just wrote and it contains all the data of
538 the job just run. If you run additional jobs, they will be appended to this
539 Volume unless you specify otherwise.
541 You might ask yourself if you have to label all the Volumes that Bacula is
542 going to use. The answer for disk Volumes, like the one we used, is no. It is
543 possible to have Bacula automatically label volumes. For tape Volumes, you
544 will most likely have to label each of the Volumes you want to use.
546 If you would like to stop here, you can simply enter {\bf quit} in the Console
547 program, and you can stop Bacula with {\bf ./bacula stop}. To clean up, simply
548 delete the file {\bf /tmp/TestVolume001}, and you should also re-initialize
558 Please note that this will erase all information about the previous jobs that
559 have run, and that you might want to do it now while testing but that normally
560 you will not want to re-initialize your database.
562 If you would like to try restoring the files that you just backed up, read the
566 \section{Restoring Your Files}
567 \index[general]{Files!Restoring Your }
568 \index[general]{Restoring Your Files }
570 If you have run the default configuration and the save of the Bacula source
571 code as demonstrated above, you can restore the backed up files in the Console
584 First you select one or more JobIds that contain files
585 to be restored. You will be presented several methods
586 of specifying the JobIds. Then you will be allowed to
587 select which files from those JobIds are to be restored.
589 To select the JobIds, you have the following choices:
590 1: List last 20 Jobs run
591 2: List Jobs where a given File is saved
592 3: Enter list of comma separated JobIds to select
593 4: Enter SQL list command
594 5: Select the most recent backup for a client
595 6: Select backup for a client before a specified time
596 7: Enter a list of files to restore
597 8: Enter a list of files to restore before a specified time
598 9: Find the JobIds of the most recent backup for a client
599 10: Find the JobIds for a backup for a client before a specified time
600 11: Enter a list of directories to restore for found JobIds
606 As you can see, there are a number of options, but for the current
607 demonstration, please enter {\bf 5} to do a restore of the last backup you
608 did, and you will get the following output:
614 Item 1 selected automatically.
615 The defined FileSet resources are:
616 1: 1 Full Set 2003-04-28 14:22:33
617 Item 1 selected automatically.
618 +-------+-------+----------+---------------------+---------------+
619 | JobId | Level | JobFiles | StartTime | VolumeName |
620 +-------+-------+----------+---------------------+---------------+
621 | 1 | F | 1444 | 2003-04-28 14:22:33 | TestVolume002 |
622 +-------+-------+----------+---------------------+---------------+
623 You have selected the following JobId: 1
624 Building directory tree for JobId 1 ...
625 1 Job inserted into the tree and marked for extraction.
626 The defined Storage resources are:
628 Item 1 selected automatically.
629 You are now entering file selection mode where you add and
630 remove files to be restored. All files are initially added.
631 Enter "done" to leave this mode.
637 where I have truncated the listing on the right side to make it more readable.
638 As you can see by starting at the top of the listing, Bacula knows what client
639 you have, and since there was only one, it selected it automatically, likewise
640 for the FileSet. Then Bacula produced a listing containing all the jobs that
641 form the current backup, in this case, there is only one, and the Storage
642 daemon was also automatically chosen. Bacula then took all the files that were
643 in Job number 1 and entered them into a {\bf directory tree} (a sort of in
644 memory representation of your filesystem). At this point, you can use the {\bf
645 cd} and {\bf ls} ro {\bf dir} commands to walk up and down the directory tree
646 and view what files will be restored. For example, if I enter {\bf cd
647 /home/kern/bacula/bacula-1.30} and then enter {\bf dir} I will get a listing
648 of all the files in the Bacula source directory. On your system, the path will
649 be somewhat different. For more information on this, please refer to the
650 \ilink{Restore Command Chapter}{RestoreChapter} of this manual for
653 To exit this mode, simply enter:
661 and you will get the following output:
665 Bootstrap records written to
666 /home/kern/bacula/testbin/working/restore.bsr
667 The restore job will require the following Volumes:
670 1444 files selected to restore.
672 JobName: RestoreFiles
673 Bootstrap: /home/kern/bacula/testbin/working/restore.bsr
674 Where: /tmp/bacula-restores
677 Backup Client: rufus-fd
678 Restore Client: rufus-fd
681 When: 2005-04-28 14:53:54
682 OK to run? (yes/mod/no):
686 If you answer {\bf yes} your files will be restored to {\bf
687 /tmp/bacula-restores}. If you want to restore the files to their original
688 locations, you must use the {\bf mod} option and explicitly set {\bf Where:}
689 to nothing (or to /). We recommend you go ahead and answer {\bf yes} and after
690 a brief moment, enter {\bf messages}, at which point you should get a listing
691 of all the files that were restored as well as a summary of the job that looks
696 28-Apr-2005 14:56 rufus-dir: Bacula 2.1.8 (08May07): 08-May-2007 14:56:06
697 Build OS: i686-pc-linux-gnu suse 10.2
699 Job: RestoreFiles.2007-05-08_14.56.06
700 Restore Client: rufus-fd
701 Start time: 08-May-2007 14:56
702 End time: 08-May-2007 14:56
703 Files Restored: 1,444
704 Bytes Restored: 38,816,381
707 FD termination status: OK
708 SD termination status: OK
709 Termination: Restore OK
710 08-May-2007 14:56 rufus-dir: Begin pruning Jobs.
711 08-May-2007 14:56 rufus-dir: No Jobs found to prune.
712 08-May-2007 14:56 rufus-dir: Begin pruning Files.
713 08-May-2007 14:56 rufus-dir: No Files found to prune.
714 08-May-2007 14:56 rufus-dir: End auto prune.
718 After exiting the Console program, you can examine the files in {\bf
719 /tmp/bacula-restores}, which will contain a small directory tree with all the
720 files. Be sure to clean up at the end with:
724 rm -rf /tmp/bacula-restore
728 \section{Quitting the Console Program}
729 \index[general]{Program!Quitting the Console }
730 \index[general]{Quitting the Console Program }
732 Simply enter the command {\bf quit}.
735 \section{Adding a Second Client}
736 \index[general]{Client!Adding a Second }
737 \index[general]{Adding a Second Client }
739 If you have gotten the example shown above to work on your system, you may be
740 ready to add a second Client (File daemon). That is you have a second machine
741 that you would like backed up. The only part you need installed on the other
742 machine is the binary {\bf bacula-fd} (or {\bf bacula-fd.exe} for Windows) and
743 its configuration file {\bf bacula-fd.conf}. You can start with the same {\bf
744 bacula-fd.conf} file that you are currently using and make one minor
745 modification to it to create the conf file for your second client. Change the
746 File daemon name from whatever was configured, {\bf rufus-fd} in the example
747 above, but your system will have a different name. The best is to change it to
748 the name of your second machine. For example:
754 # "Global" File daemon configuration specifications
756 FileDaemon { # this is me
758 FDport = 9102 # where we listen for the director
759 WorkingDirectory = /home/kern/bacula/working
760 Pid Directory = /var/run
772 # "Global" File daemon configuration specifications
774 FileDaemon { # this is me
776 FDport = 9102 # where we listen for the director
777 WorkingDirectory = /home/kern/bacula/working
778 Pid Directory = /var/run
784 where I show just a portion of the file and have changed {\bf rufus-fd} to
785 {\bf matou-fd}. The names you use are your choice. For the moment, I recommend
786 you change nothing else. Later, you will want to change the password.
788 Now you should install that change on your second machine. Then you need to
789 make some additions to your Director's configuration file to define the new
790 File daemon or Client. Starting from our original example which should be
791 installed on your system, you should add the following lines (essentially
792 copies of the existing data but with the names changed) to your Director's
793 configuration file {\bf bacula-dir.conf}.
798 # Define the main nightly save backup job
799 # By default, this job will back up to disk in /tmp
805 Schedule = "WeeklyCycle"
809 Write Bootstrap = "/home/kern/bacula/working/matou.bsr"
811 # Client (File Services) to backup
817 Password = "xxxxx" # password for
818 File Retention = 30d # 30 days
819 Job Retention = 180d # six months
820 AutoPrune = yes # Prune expired Jobs/Files
825 Then make sure that the Address parameter in the Storage resource is set to
826 the fully qualified domain name and not to something like "localhost". The
827 address specified is sent to the File daemon (client) and it must be a fully
828 qualified domain name. If you pass something like "localhost" it will not
829 resolve correctly and will result in a time out when the File daemon fails to
830 connect to the Storage daemon.
832 That is all that is necessary. I copied the existing resource to create a
833 second Job (Matou) to backup the second client (matou-fd). It has the name
834 {\bf Matou}, the Client is named {\bf matou-fd}, and the bootstrap file name
835 is changed, but everything else is the same. This means that Matou will be
836 backed up on the same schedule using the same set of tapes. You may want to
837 change that later, but for now, let's keep it simple.
839 The second change was to add a new Client resource that defines {\bf matou-fd}
840 and has the correct address {\bf matou}, but in real life, you may need a
841 fully qualified domain name or an IP address. I also kept the password the
842 same (shown as xxxxx for the example).
844 At this point, if you stop Bacula and restart it, and start the Client on the
845 other machine, everything will be ready, and the prompts that you saw above
846 will now include the second machine.
848 To make this a real production installation, you will possibly want to use
849 different Pool, or a different schedule. It is up to you to customize. In any
850 case, you should change the password in both the Director's file and the
851 Client's file for additional security.
853 For some important tips on changing names and passwords, and a diagram of what
854 names and passwords must match, please see
855 \ilink{Authorization Errors}{AuthorizationErrors} in the FAQ chapter
858 \section{When The Tape Fills}
860 \index[general]{Fills!When The Tape }
861 \index[general]{When The Tape Fills }
863 If you have scheduled your job, typically nightly, there will come a time when
864 the tape fills up and {\bf Bacula} cannot continue. In this case, Bacula will
865 send you a message similar to the following:
869 rufus-sd: block.c:337 === Write error errno=28: ERR=No space left
874 This indicates that Bacula got a write error because the tape is full. Bacula
875 will then search the Pool specified for your Job looking for an appendable
876 volume. In the best of all cases, you will have properly set your Retention
877 Periods and you will have all your tapes marked to be Recycled, and {\bf
878 Bacula} will automatically recycle the tapes in your pool requesting and
879 overwriting old Volumes. For more information on recycling, please see the
880 \ilink{Recycling chapter}{RecyclingChapter} of this manual. If you
881 find that your Volumes were not properly recycled (usually because of a
882 configuration error), please see the
883 \ilink{Manually Recycling Volumes}{manualrecycling} section of
884 the Recycling chapter.
886 If like me, you have a very large set of Volumes and you label them with the
887 date the Volume was first writing, or you have not set up your Retention
888 periods, Bacula will not find a tape in the pool, and it will send you a
889 message similar to the following:
893 rufus-sd: Job kernsave.2002-09-19.10:50:48 waiting. Cannot find any
895 Please use the "label" command to create a new Volume for:
902 Until you create a new Volume, this message will be repeated an hour later,
903 then two hours later, and so on doubling the interval each time up to a
904 maximum interval of one day.
906 The obvious question at this point is: What do I do now?
908 The answer is simple: first, using the Console program, close the tape drive
909 using the {\bf unmount} command. If you only have a single drive, it will be
910 automatically selected, otherwise, make sure you release the one specified on
911 the message (in this case {\bf STD-10000}).
913 Next, you remove the tape from the drive and insert a new blank tape. Note, on
914 some older tape drives, you may need to write an end of file mark ({\bf mt \
915 -f \ /dev/nst0 \ weof}) to prevent the drive from running away when Bacula
916 attempts to read the label.
918 Finally, you use the {\bf label} command in the Console to write a label to
919 the new Volume. The {\bf label} command will contact the Storage daemon to
920 write the software label, if it is successful, it will add the new Volume to
921 the Pool, then issue a {\bf mount} command to the Storage daemon. See the
922 previous sections of this chapter for more details on labeling tapes.
924 The result is that Bacula will continue the previous Job writing the backup to
927 If you have a Pool of volumes and Bacula is cycling through them, instead of
928 the above message "Cannot find any appendable volumes.", Bacula may ask you
929 to mount a specific volume. In that case, you should attempt to do just that.
930 If you do not have the volume any more (for any of a number of reasons), you
931 can simply mount another volume from the same Pool, providing it is
932 appendable, and Bacula will use it. You can use the {\bf list volumes} command
933 in the console program to determine which volumes are appendable and which are
936 If like me, you have your Volume retention periods set correctly, but you have
937 no more free Volumes, you can relabel and reuse a Volume as follows:
940 \item Do a {\bf list volumes} in the Console and select the oldest Volume for
942 \item If you have setup your Retention periods correctly, the Volume should
943 have VolStatus {\bf Purged}.
944 \item If the VolStatus is not set to Purged, you will need to purge the
945 database of Jobs that are written on that Volume. Do so by using the command
946 {\bf purge jobs volume} in the Console. If you have multiple Pools, you will
947 be prompted for the Pool then enter the VolumeName (or MediaId) when
949 \item Then simply use the {\bf relabel} command to relabel the Volume.
952 To manually relabel the Volume use the following additional steps:
955 \item To delete the Volume from the catalog use the {\bf delete volume}
956 command in the Console and select the VolumeName (or MediaId) to be deleted.
958 \item Use the {\bf unmount} command in the Console to unmount the old tape.
959 \item Physically relabel the old Volume that you deleted so that it can be
961 \item Insert the old Volume in the tape drive.
962 \item From a command line do: {\bf mt \ -f \ /dev/st0 \ rewind} and {\bf mt \
963 -f \ /dev/st0 \ weof}, where you need to use the proper tape drive name for
964 your system in place of {\bf /dev/st0}.
965 \item Use the {\bf label} command in the Console to write a new Bacula label
967 \item Use the {\bf mount} command in the Console if it is not automatically
968 done, so that Bacula starts using your newly labeled tape.
971 \section{Other Useful Console Commands}
972 \index[general]{Commands!Other Useful Console }
973 \index[general]{Other Useful Console Commands }
978 \index[console]{status dir }
979 Print a status of all running jobs and jobs scheduled in the next 24 hours.
982 \index[console]{status }
983 The console program will prompt you to select a daemon type, then will
984 request the daemon's status.
986 \item [status jobid=nn]
987 \index[console]{status jobid }
988 Print a status of JobId nn if it is running. The Storage daemon is contacted
989 and requested to print a current status of the job as well.
992 \index[console]{list pools }
993 List the pools defined in the Catalog (normally only Default is used).
996 \index[console]{list media }
997 Lists all the media defined in the Catalog.
1000 \index[console]{list jobs }
1001 Lists all jobs in the Catalog that have run.
1003 \item [list jobid=nn]
1004 \index[console]{list jobid }
1005 Lists JobId nn from the Catalog.
1007 \item [list jobtotals]
1008 \index[console]{list jobtotals }
1009 Lists totals for all jobs in the Catalog.
1011 \item [list files jobid=nn]
1012 \index[console]{list files jobid }
1013 List the files that were saved for JobId nn.
1015 \item [list jobmedia]
1016 \index[console]{list jobmedia }
1017 List the media information for each Job run.
1020 \index[console]{messages }
1021 Prints any messages that have been directed to the console.
1023 \item [unmount storage=storage-name]
1024 \index[console]{unmount storage }
1025 Unmounts the drive associated with the storage device with the name {\bf
1026 storage-name} if the drive is not currently being used. This command is used
1027 if you wish Bacula to free the drive so that you can use it to label a tape.
1030 \item [mount storage=storage-name]
1031 \index[sd]{mount storage }
1032 Causes the drive associated with the storage device to be mounted again. When
1033 Bacula reaches the end of a volume and requests you to mount a new volume,
1034 you must issue this command after you have placed the new volume in the
1035 drive. In effect, it is the signal needed by Bacula to know to start reading
1036 or writing the new volume.
1040 Exit or quit the console program.
1043 Most of the commands given above, with the exception of {\bf list}, will
1044 prompt you for the necessary arguments if you simply enter the command name.
1046 \section{Debug Daemon Output}
1047 \index[general]{Debug Daemon Output }
1048 \index[general]{Output!Debug Daemon }
1050 If you want debug output from the daemons as they are running, start the
1051 daemons from the install directory as follows:
1055 ./bacula start -d100
1059 This can be particularly helpful if your daemons do not start correctly,
1060 because direct daemon output to the console is normally directed to the
1061 NULL device, but with the debug level greater than zero, the output
1062 will be sent to the starting terminal.
1064 To stop the three daemons, enter the following from the install directory:
1072 The execution of {\bf bacula stop} may complain about pids not found. This is
1073 OK, especially if one of the daemons has died, which is very rare.
1075 To do a full system save, each File daemon must be running as root so that it
1076 will have permission to access all the files. None of the other daemons
1077 require root privileges. However, the Storage daemon must be able to open the
1078 tape drives. On many systems, only root can access the tape drives. Either run
1079 the Storage daemon as root, or change the permissions on the tape devices to
1080 permit non-root access. MySQL and PostgreSQL can be installed and run with any
1081 userid; root privilege is not necessary.
1083 \section{Patience When Starting Daemons or Mounting Blank Tapes}
1085 When you start the Bacula daemons, the Storage daemon attempts to open all
1086 defined storage devices and verify the currently mounted Volume (if
1087 configured). Until all the storage devices are verified, the Storage daemon
1088 will not accept connections from the Console program. If a tape was previously
1089 used, it will be rewound, and on some devices this can take several minutes.
1090 As a consequence, you may need to have a bit of patience when first contacting
1091 the Storage daemon after starting the daemons. If you can see your tape drive,
1092 once the lights stop flashing, the drive will be ready to be used.
1094 The same considerations apply if you have just mounted a blank tape in a drive
1095 such as an HP DLT. It can take a minute or two before the drive properly
1096 recognizes that the tape is blank. If you attempt to {\bf mount} the tape with
1097 the Console program during this recognition period, it is quite possible that
1098 you will hang your SCSI driver (at least on my Red Hat Linux system). As a
1099 consequence, you are again urged to have patience when inserting blank tapes.
1100 Let the device settle down before attempting to access it.
1102 \section{Difficulties Connecting from the FD to the SD}
1103 \index[general]{Difficulties Connecting from the FD to the SD}
1104 \index[general]{SD!Difficulties Connecting from the FD to the SD}
1106 If you are having difficulties getting one or more of your File daemons to
1107 connect to the Storage daemon, it is most likely because you have not used a
1108 fully qualified domain name on the {\bf Address} directive in the
1109 Director's Storage resource. That is the resolver on the File daemon's machine
1110 (not on the Director's) must be able to resolve the name you supply into an IP
1111 address. An example of an address that is guaranteed not to work: {\bf
1112 localhost}. An example that may work: {\bf megalon}. An example that is more
1113 likely to work: {\bf magalon.mydomain.com}. On Win32 if you don't have a good
1114 resolver (often true on older Win98 systems), you might try using an IP
1115 address in place of a name.
1117 If your address is correct, then make sure that no other program is using the
1118 port 9103 on the Storage daemon's machine. The Bacula port number are
1119 authorized by IANA, and should not be used by other programs, but apparently
1120 some HP printers do use these port numbers. A {\bf netstat -a} on the Storage
1121 daemon's machine can determine who is using the 9103 port (used for FD to SD
1122 communications in Bacula).
1124 \section{Daemon Command Line Options}
1125 \index[general]{Daemon Command Line Options }
1126 \index[general]{Options!Daemon Command Line }
1128 Each of the three daemons (Director, File, Storage) accepts a small set of
1129 options on the command line. In general, each of the daemons as well as the
1130 Console program accepts the following options:
1134 \item [-c \lt{}file\gt{}]
1135 \index[sd]{-c \lt{}file\gt{} }
1136 Define the file to use as a configuration file. The default is the daemon
1137 name followed by {\bf .conf} i.e. {\bf bacula-dir.conf} for the Director,
1138 {\bf bacula-fd.conf} for the File daemon, and {\bf bacula-sd} for the Storage
1143 Set the debug level to {\bf nn}. Higher levels of debug cause more
1144 information to be displayed on STDOUT concerning what the daemon is doing.
1147 Run the daemon in the foreground. This option is needed to run the daemon
1151 Do not trap signals. This option is needed to run the daemon under the
1155 Read the configuration file and print any error messages, then immediately
1156 exit. Useful for syntax testing of new configuration files.
1159 Be more verbose or more complete in printing error and informational
1160 messages. Recommended.
1163 Print the version and list of options.
1168 \section{Creating a Pool}
1170 \index[general]{Pool!Creating a }
1171 \index[general]{Creating a Pool }
1173 Creating the Pool is automatically done when {\bf Bacula} starts, so if you
1174 understand Pools, you can skip to the next section.
1176 When you run a job, one of the things that Bacula must know is what Volumes to
1177 use to backup the FileSet. Instead of specifying a Volume (tape) directly, you
1178 specify which Pool of Volumes you want Bacula to consult when it wants a tape
1179 for writing backups. Bacula will select the first available Volume from the
1180 Pool that is appropriate for the Storage device you have specified for the Job
1181 being run. When a volume has filled up with data, {\bf Bacula} will change its
1182 VolStatus from {\bf Append} to {\bf Full}, and then {\bf Bacula} will use the
1183 next volume and so on. If no appendable Volume exists in the Pool, the
1184 Director will attempt to recycle an old Volume, if there are still no
1185 appendable Volumes available, {\bf Bacula} will send a message requesting the
1186 operator to create an appropriate Volume.
1188 {\bf Bacula} keeps track of the Pool name, the volumes contained in the Pool,
1189 and a number of attributes of each of those Volumes.
1191 When Bacula starts, it ensures that all Pool resource definitions have been
1192 recorded in the catalog. You can verify this by entering:
1200 to the console program, which should print something like the following:
1205 Using default Catalog name=MySQL DB=bacula
1206 +--------+---------+---------+---------+----------+-------------+
1207 | PoolId | Name | NumVols | MaxVols | PoolType | LabelFormat |
1208 +--------+---------+---------+---------+----------+-------------+
1209 | 1 | Default | 3 | 0 | Backup | * |
1210 | 2 | File | 12 | 12 | Backup | File |
1211 +--------+---------+---------+---------+----------+-------------+
1216 If you attempt to create the same Pool name a second time, {\bf Bacula} will
1221 Error: Pool Default already exists.
1222 Once created, you may use the {\bf update} command to
1223 modify many of the values in the Pool record.
1229 \section{Labeling Your Volumes}
1230 \index[general]{Volumes!Labeling Your }
1231 \index[general]{Labeling Your Volumes }
1233 Bacula requires that each Volume contains a software label. There are several
1234 strategies for labeling volumes. The one I use is to label them as they are
1235 needed by {\bf Bacula} using the console program. That is when Bacula needs a
1236 new Volume, and it does not find one in the catalog, it will send me an email
1237 message requesting that I add Volumes to the Pool. I then use the {\bf label}
1238 command in the Console program to label a new Volume and to define it in the
1239 Pool database, after which Bacula will begin writing on the new Volume.
1240 Alternatively, I can use the Console {\bf relabel} command to relabel a Volume
1241 that is no longer used providing it has VolStatus {\bf Purged}.
1243 Another strategy is to label a set of volumes at the start, then use them as
1244 {\bf Bacula} requests them. This is most often done if you are cycling through
1245 a set of tapes, for example using an autochanger. For more details on
1246 recycling, please see the
1247 \ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of
1250 If you run a Bacula job, and you have no labeled tapes in the Pool, Bacula
1251 will inform you, and you can create them "on-the-fly" so to speak. In my
1252 case, I label my tapes with the date, for example: {\bf DLT-18April02}. See
1253 below for the details of using the {\bf label} command.
1255 \section{Labeling Volumes with the Console Program}
1256 \index[general]{Labeling Volumes with the Console Program }
1257 \index[general]{Program!Labeling Volumes with the Console }
1259 Labeling volumes is normally done by using the console program.
1266 If Bacula complains that you cannot label the tape because it is already
1267 labeled, simply {\bf unmount} the tape using the {\bf unmount} command in the
1268 console, then physically mount a blank tape and re-issue the {\bf label}
1271 Since the physical storage media is different for each device, the {\bf label}
1272 command will provide you with a list of the defined Storage resources such as
1277 The defined Storage resources are:
1282 Select Storage resource (1-4):
1286 At this point, you should have a blank tape in the drive corresponding to the
1287 Storage resource that you select.
1289 It will then ask you for the Volume name.
1293 Enter new Volume name:
1297 If Bacula complains:
1301 Media record for Volume xxxx already exists.
1305 It means that the volume name {\bf xxxx} that you entered already exists in
1306 the Media database. You can list all the defined Media (Volumes) with the {\bf
1307 list media} command. Note, the LastWritten column has been truncated for
1312 +---------------+---------+--------+----------------+-----/~/-+------------+-----+
1313 | VolumeName | MediaTyp| VolStat| VolBytes | LastWri | VolReten | Recy|
1314 +---------------+---------+--------+----------------+---------+------------+-----+
1315 | DLTVol0002 | DLT8000 | Purged | 56,128,042,217 | 2001-10 | 31,536,000 | 0 |
1316 | DLT-07Oct2001 | DLT8000 | Full | 56,172,030,586 | 2001-11 | 31,536,000 | 0 |
1317 | DLT-08Nov2001 | DLT8000 | Full | 55,691,684,216 | 2001-12 | 31,536,000 | 0 |
1318 | DLT-01Dec2001 | DLT8000 | Full | 55,162,215,866 | 2001-12 | 31,536,000 | 0 |
1319 | DLT-28Dec2001 | DLT8000 | Full | 57,888,007,042 | 2002-01 | 31,536,000 | 0 |
1320 | DLT-20Jan2002 | DLT8000 | Full | 57,003,507,308 | 2002-02 | 31,536,000 | 0 |
1321 | DLT-16Feb2002 | DLT8000 | Full | 55,772,630,824 | 2002-03 | 31,536,000 | 0 |
1322 | DLT-12Mar2002 | DLT8000 | Full | 50,666,320,453 | 1970-01 | 31,536,000 | 0 |
1323 | DLT-27Mar2002 | DLT8000 | Full | 57,592,952,309 | 2002-04 | 31,536,000 | 0 |
1324 | DLT-15Apr2002 | DLT8000 | Full | 57,190,864,185 | 2002-05 | 31,536,000 | 0 |
1325 | DLT-04May2002 | DLT8000 | Full | 60,486,677,724 | 2002-05 | 31,536,000 | 0 |
1326 | DLT-26May02 | DLT8000 | Append | 1,336,699,620 | 2002-05 | 31,536,000 | 1 |
1327 +---------------+---------+--------+----------------+-----/~/-+------------+-----+
1331 Once Bacula has verified that the volume does not already exist, it will
1332 prompt you for the name of the Pool in which the Volume (tape) is to be
1333 created. If there is only one Pool (Default), it will be automatically
1336 If the tape is successfully labeled, a Volume record will also be created in
1337 the Pool. That is the Volume name and all its other attributes will appear
1338 when you list the Pool. In addition, that Volume will be available for backup
1339 if the MediaType matches what is requested by the Storage daemon.
1341 When you labeled the tape, you answered very few questions about it --
1342 principally the Volume name, and perhaps the Slot. However, a Volume record in
1343 the catalog database (internally known as a Media record) contains quite a few
1344 attributes. Most of these attributes will be filled in from the default values
1345 that were defined in the Pool (i.e. the Pool holds most of the default
1346 attributes used when creating a Volume).
1348 It is also possible to add media to the pool without physically labeling the
1349 Volumes. This can be done with the {\bf add} command. For more information,
1351 \ilink{Console Chapter}{_ConsoleChapter} of this manual.