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 GNOME installed and used the {\bf \verb:--:enable-gnome} on the configure command,
135 you may use the GNOME Console program:
139 Another possibility is to run the wxWidgets program {\bf wx-console}.
141 For simplicity, here we will describe only the {\bf ./bconsole} program. Most
142 of what is described here applies equally well to {\bf ./gnome-console}
143 and to {\bf wx-console}
145 The {\bf ./bconsole} runs the Bacula Console program, which connects to the
146 Director daemon. Since Bacula is a network program, you can run the Console
147 program anywhere on your network. Most frequently, however, one runs it on the
148 same machine as the Director. Normally, the Console program will print
149 something similar to the following:
153 [kern@polymatou bin]$ ./bconsole
154 Connecting to Director lpmatou:9101
155 1000 OK: HeadMan Version: 1.30 (28 April 2003)
160 the asterisk is the console command prompt.
162 Type {\bf help} to see a list of available commands:
169 add add media to a pool
170 autodisplay autodisplay [on/off] -- console messages
171 automount automount [on/off] -- after label
172 cancel cancel job=nnn -- cancel a job
173 create create DB Pool from resource
174 delete delete [pool=<pool-name> | media volume=<volume-name>]
175 estimate performs FileSet estimate debug=1 give full listing
177 help print this command
179 list list [pools | jobs | jobtotals | media <pool> |
180 files jobid=<nn>]; from catalog
181 llist full or long list like list command
183 mount mount <storage-name>
184 prune prune expired records from catalog
185 purge purge records from catalog
188 relabel relabel a tape
189 release release <storage-name>
190 restore restore files
192 setdebug sets debug level
193 show show (resource records) [jobs | pools | ... | all]
194 sqlquery use SQL to query catalog
195 status status [storage | client]=<name>
196 time print current time
197 unmount unmount <storage-name>
198 update update Volume or Pool
200 var does variable expansion
201 version print Director version
202 wait wait until no jobs are running
207 Details of the console program's commands are explained in the
208 \ilink{Console Chapter}{_ConsoleChapter} of this manual.
210 \section{Running a Job}
212 \index[general]{Job!Running a }
213 \index[general]{Running a Job }
215 At this point, we assume you have done the following:
218 \item Configured Bacula with {\bf ./configure \verb:--:your-options}
219 \item Built Bacula using {\bf make}
220 \item Installed Bacula using {\bf make install}
221 \item Have created your database with, for example, {\bf
222 ./create\_sqlite\_database}
223 \item Have created the Bacula database tables with, {\bf
224 ./make\_bacula\_tables}
225 \item Have possibly edited your {\bf bacula-dir.conf} file to personalize it
226 a bit. BE CAREFUL! if you change the Director's name or password, you will
227 need to make similar modifications in the other .conf files. For the moment
228 it is probably better to make no changes.
229 \item You have started Bacula with {\bf ./bacula start}
230 \item You have invoked the Console program with {\bf ./bconsole}
233 Furthermore, we assume for the moment you are using the default configuration
236 At this point, enter the following command:
244 and you should get something similar to:
248 FileSet: name=Full Set
251 I /home/kern/bacula/regress/build
258 FileSet: name=Catalog
261 I /home/kern/bacula/regress/working/bacula.sql
266 This is a pre-defined {\bf FileSet} that will backup the Bacula source
267 directory. The actual directory names printed should correspond to your system
268 configuration. For testing purposes, we have chosen a directory of moderate
269 size (about 40 Megabytes) and complexity without being too big. The FileSet
270 {\bf Catalog} is used for backing up Bacula's catalog and is not of interest
271 to us for the moment. The {\bf I} entries are the files or directories that
272 will be included in the backup and the {\bf E} are those that will be
273 excluded, and the {\bf O} entries are the options specified for
274 the FileSet. You can change what is backed up by editing {\bf bacula-dir.conf}
275 and changing the {\bf File =} line in the {\bf FileSet} resource.
277 Now is the time to run your first backup job. We are going to backup your
278 Bacula source directory to a File Volume in your {\bf /tmp} directory just to
279 show you how easy it is. Now enter:
287 and you should get the following output:
291 rufus-dir Version: 1.30 (28 April 2003)
292 Daemon started 28-Apr-2003 14:03, 0 Jobs run.
293 Console connected at 28-Apr-2003 14:03
295 Level Type Scheduled Name
296 =================================================================
297 Incremental Backup 29-Apr-2003 01:05 Client1
298 Full Backup 29-Apr-2003 01:10 BackupCatalog
303 where the times and the Director's name will be different according to your
304 setup. This shows that an Incremental job is scheduled to run for the Job {\bf
305 Client1} at 1:05am and that at 1:10, a {\bf BackupCatalog} is scheduled to
306 run. Note, you should probably change the name {\bf Client1} to be the name of
307 your machine, if not, when you add additional clients, it will be very
308 confusing. For my real machine, I use {\bf Rufus} rather than {\bf Client1} as
319 and you should get something like:
323 The defined Client resources are:
325 Item 1 selected automatically.
326 Connecting to Client rufus-fd at rufus:8102
327 rufus-fd Version: 1.30 (28 April 2003)
328 Daemon started 28-Apr-2003 14:03, 0 Jobs run.
329 Director connected at: 28-Apr-2003 14:14
335 In this case, the client is named {\bf rufus-fd} your name will be different,
336 but the line beginning with {\bf rufus-fd Version ...} is printed by your File
337 daemon, so we are now sure it is up and running.
339 Finally do the same for your Storage daemon with:
351 The defined Storage resources are:
353 Item 1 selected automatically.
354 Connecting to Storage daemon File at rufus:8103
355 rufus-sd Version: 1.30 (28 April 2003)
356 Daemon started 28-Apr-2003 14:03, 0 Jobs run.
357 Device /tmp is not open.
363 You will notice that the default Storage daemon device is named {\bf File} and
364 that it will use device {\bf /tmp}, which is not currently open.
366 Now, let's actually run a job with:
374 you should get the following output:
378 Using default Catalog name=MyCatalog DB=bacula
379 A job name must be specified.
380 The defined Job resources are:
384 Select Job resource (1-3):
388 Here, Bacula has listed the three different Jobs that you can run, and you
389 should choose number {\bf 1} and type enter, at which point you will get:
400 When: 2003-04-28 14:18:57
401 OK to run? (yes/mod/no):
405 At this point, take some time to look carefully at what is printed and
406 understand it. It is asking you if it is OK to run a job named {\bf Client1}
407 with FileSet {\bf Full Set} (we listed above) as an Incremental job on your
408 Client (your client name will be different), and to use Storage {\bf File} and
409 Pool {\bf Default}, and finally, it wants to run it now (the current time
410 should be displayed by your console).
412 Here we have the choice to run ({\bf yes}), to modify one or more of the above
413 parameters ({\bf mod}), or to not run the job ({\bf no}). Please enter {\bf
414 yes}, at which point you should immediately get the command prompt (an
415 asterisk). If you wait a few seconds, then enter the command {\bf messages}
416 you will get back something like:
420 28-Apr-2003 14:22 rufus-dir: Last FULL backup time not found. Doing
422 28-Apr-2003 14:22 rufus-dir: Start Backup JobId 1,
423 Job=Client1.2003-04-28_14.22.33
424 28-Apr-2003 14:22 rufus-sd: Job Client1.2003-04-28_14.22.33 waiting.
425 Cannot find any appendable volumes.
426 Please use the "label" command to create a new Volume for:
433 The first message, indicates that no previous Full backup was done, so Bacula
434 is upgrading our Incremental job to a Full backup (this is normal). The second
435 message indicates that the job started with JobId 1., and the third message
436 tells us that Bacula cannot find any Volumes in the Pool for writing the
437 output. This is normal because we have not yet created (labeled) any Volumes.
438 Bacula indicates to you all the details of the volume it needs.
440 At this point, the job is BLOCKED waiting for a Volume. You can check this if
441 you want by doing a {\bf status dir}. In order to continue, we must create a
442 Volume that Bacula can write on. We do so with:
450 and Bacula will print:
454 The defined Storage resources are:
456 Item 1 selected automatically.
457 Enter new Volume name:
461 at which point, you should enter some name beginning with a letter and
462 containing only letters and numbers (period, hyphen, and underscore) are also
463 permitted. For example, enter {\bf TestVolume001}, and you should get back:
469 Item 1 selected automatically.
470 Connecting to Storage daemon File at rufus:8103 ...
471 Sending label command for Volume "TestVolume001" Slot 0 ...
472 3000 OK label. Volume=TestVolume001 Device=/tmp
473 Catalog record for Volume "TestVolume002", Slot 0 successfully created.
474 Requesting mount FileStorage ...
475 3001 OK mount. Device=/tmp
479 Finally, enter {\bf messages} and you should get something like:
483 28-Apr-2003 14:30 rufus-sd: Wrote label to prelabeled Volume
484 "TestVolume001" on device /tmp
485 28-Apr-2003 14:30 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:30
487 Job: Client1.2003-04-28_14.22.33
491 Start time: 28-Apr-2003 14:22
492 End time: 28-Apr-2003 14:30
494 Bytes Written: 38,988,877
496 Software Compression: None
497 Volume names(s): TestVolume001
499 Volume Session Time: 1051531381
500 Last Volume Bytes: 39,072,359
501 FD termination status: OK
502 SD termination status: OK
503 Termination: Backup OK
504 28-Apr-2003 14:30 rufus-dir: Begin pruning Jobs.
505 28-Apr-2003 14:30 rufus-dir: No Jobs found to prune.
506 28-Apr-2003 14:30 rufus-dir: Begin pruning Files.
507 28-Apr-2003 14:30 rufus-dir: No Files found to prune.
508 28-Apr-2003 14:30 rufus-dir: End auto prune.
512 If you don't see the output immediately, you can keep entering {\bf messages}
513 until the job terminates, or you can enter, {\bf autodisplay on} and your
514 messages will automatically be displayed as soon as they are ready.
516 If you do an {\bf ls -l} of your {\bf /tmp} directory, you will see that you
517 have the following item:
521 -rw-r----- 1 kern kern 39072153 Apr 28 14:30 TestVolume001
525 This is the file Volume that you just wrote and it contains all the data of
526 the job just run. If you run additional jobs, they will be appended to this
527 Volume unless you specify otherwise.
529 You might ask yourself if you have to label all the Volumes that Bacula is
530 going to use. The answer for disk Volumes, like the one we used, is no. It is
531 possible to have Bacula automatically label volumes. For tape Volumes, you
532 will most likely have to label each of the Volumes you want to use.
534 If you would like to stop here, you can simply enter {\bf quit} in the Console
535 program, and you can stop Bacula with {\bf ./bacula stop}. To clean up, simply
536 delete the file {\bf /tmp/TestVolume001}, and you should also re-initialize
546 Please note that this will erase all information about the previous jobs that
547 have run, and that you might want to do it now while testing but that normally
548 you will not want to re-initialize your database.
550 If you would like to try restoring the files that you just backed up, read the
554 \section{Restoring Your Files}
555 \index[general]{Files!Restoring Your }
556 \index[general]{Restoring Your Files }
558 If you have run the default configuration and the save of the Bacula source
559 code as demonstrated above, you can restore the backed up files in the Console
572 First you select one or more JobIds that contain files
573 to be restored. You will be presented several methods
574 of specifying the JobIds. Then you will be allowed to
575 select which files from those JobIds are to be restored.
577 To select the JobIds, you have the following choices:
578 1: List last 20 Jobs run
579 2: List Jobs where a given File is saved
580 3: Enter list of comma separated JobIds to select
581 4: Enter SQL list command
582 5: Select the most recent backup for a client
583 6: Select backup for a client before a specified time
584 7: Enter a list of files to restore
585 8: Enter a list of files to restore before a specified time
586 9: Find the JobIds of the most recent backup for a client
587 10: Find the JobIds for a backup for a client before a specified time
588 11: Enter a list of directories to restore for found JobIds
594 As you can see, there are a number of options, but for the current
595 demonstration, please enter {\bf 5} to do a restore of the last backup you
596 did, and you will get the following output:
602 Item 1 selected automatically.
603 The defined FileSet resources are:
604 1: 1 Full Set 2003-04-28 14:22:33
605 Item 1 selected automatically.
606 +-------+-------+----------+---------------------+---------------+
607 | JobId | Level | JobFiles | StartTime | VolumeName |
608 +-------+-------+----------+---------------------+---------------+
609 | 1 | F | 1444 | 2003-04-28 14:22:33 | TestVolume002 |
610 +-------+-------+----------+---------------------+---------------+
611 You have selected the following JobId: 1
612 Building directory tree for JobId 1 ...
613 1 Job inserted into the tree and marked for extraction.
614 The defined Storage resources are:
616 Item 1 selected automatically.
617 You are now entering file selection mode where you add and
618 remove files to be restored. All files are initially added.
619 Enter "done" to leave this mode.
625 where I have truncated the listing on the right side to make it more readable.
626 As you can see by starting at the top of the listing, Bacula knows what client
627 you have, and since there was only one, it selected it automatically, likewise
628 for the FileSet. Then Bacula produced a listing containing all the jobs that
629 form the current backup, in this case, there is only one, and the Storage
630 daemon was also automatically chosen. Bacula then took all the files that were
631 in Job number 1 and entered them into a {\bf directory tree} (a sort of in
632 memory representation of your filesystem). At this point, you can use the {\bf
633 cd} and {\bf ls} ro {\bf dir} commands to walk up and down the directory tree
634 and view what files will be restored. For example, if I enter {\bf cd
635 /home/kern/bacula/bacula-1.30} and then enter {\bf dir} I will get a listing
636 of all the files in the Bacula source directory. On your system, the path will
637 be somewhat different. For more information on this, please refer to the
638 \ilink{Restore Command Chapter}{RestoreChapter} of this manual for
641 To exit this mode, simply enter:
649 and you will get the following output:
653 Bootstrap records written to
654 /home/kern/bacula/testbin/working/restore.bsr
655 The restore job will require the following Volumes:
658 1444 files selected to restore.
660 JobName: RestoreFiles
661 Bootstrap: /home/kern/bacula/testbin/working/restore.bsr
662 Where: /tmp/bacula-restores
668 When: 2005-04-28 14:53:54
669 OK to run? (yes/mod/no):
673 If you answer {\bf yes} your files will be restored to {\bf
674 /tmp/bacula-restores}. If you want to restore the files to their original
675 locations, you must use the {\bf mod} option and explicitly set {\bf Where:}
676 to nothing (or to /). We recommend you go ahead and answer {\bf yes} and after
677 a brief moment, enter {\bf messages}, at which point you should get a listing
678 of all the files that were restored as well as a summary of the job that looks
683 28-Apr-2005 14:56 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:56
685 Job: RestoreFiles.2005-04-28_14.56.06
687 Start time: 28-Apr-2005 14:56
688 End time: 28-Apr-2005 14:56
689 Files Restored: 1,444
690 Bytes Restored: 38,816,381
692 FD termination status: OK
693 Termination: Restore OK
694 28-Apr-2005 14:56 rufus-dir: Begin pruning Jobs.
695 28-Apr-2005 14:56 rufus-dir: No Jobs found to prune.
696 28-Apr-2005 14:56 rufus-dir: Begin pruning Files.
697 28-Apr-2005 14:56 rufus-dir: No Files found to prune.
698 28-Apr-2005 14:56 rufus-dir: End auto prune.
702 After exiting the Console program, you can examine the files in {\bf
703 /tmp/bacula-restores}, which will contain a small directory tree with all the
704 files. Be sure to clean up at the end with:
708 rm -rf /tmp/bacula-restore
712 \section{Quitting the Console Program}
713 \index[general]{Program!Quitting the Console }
714 \index[general]{Quitting the Console Program }
716 Simply enter the command {\bf quit}.
719 \section{Adding a Second Client}
720 \index[general]{Client!Adding a Second }
721 \index[general]{Adding a Second Client }
723 If you have gotten the example shown above to work on your system, you may be
724 ready to add a second Client (File daemon). That is you have a second machine
725 that you would like backed up. The only part you need installed on the other
726 machine is the binary {\bf bacula-fd} (or {\bf bacula-fd.exe} for Windows) and
727 its configuration file {\bf bacula-fd.conf}. You can start with the same {\bf
728 bacula-fd.conf} file that you are currently using and make one minor
729 modification to it to create the conf file for your second client. Change the
730 File daemon name from whatever was configured, {\bf rufus-fd} in the example
731 above, but your system will have a different name. The best is to change it to
732 the name of your second machine. For example:
738 # "Global" File daemon configuration specifications
740 FileDaemon { # this is me
742 FDport = 9102 # where we listen for the director
743 WorkingDirectory = /home/kern/bacula/working
744 Pid Directory = /var/run
756 # "Global" File daemon configuration specifications
758 FileDaemon { # this is me
760 FDport = 9102 # where we listen for the director
761 WorkingDirectory = /home/kern/bacula/working
762 Pid Directory = /var/run
768 where I show just a portion of the file and have changed {\bf rufus-fd} to
769 {\bf matou-fd}. The names you use are your choice. For the moment, I recommend
770 you change nothing else. Later, you will want to change the password.
772 Now you should install that change on your second machine. Then you need to
773 make some additions to your Director's configuration file to define the new
774 File daemon or Client. Starting from our original example which should be
775 installed on your system, you should add the following lines (essentially
776 copies of the existing data but with the names changed) to your Director's
777 configuration file {\bf bacula-dir.conf}.
782 # Define the main nightly save backup job
783 # By default, this job will back up to disk in /tmp
789 Schedule = "WeeklyCycle"
793 Write Bootstrap = "/home/kern/bacula/working/matou.bsr"
795 # Client (File Services) to backup
801 Password = "xxxxx" # password for
802 File Retention = 30d # 30 days
803 Job Retention = 180d # six months
804 AutoPrune = yes # Prune expired Jobs/Files
809 Then make sure that the Address parameter in the Storage resource is set to
810 the fully qualified domain name and not to something like "localhost". The
811 address specified is sent to the File daemon (client) and it must be a fully
812 qualified domain name. If you pass something like "localhost" it will not
813 resolve correctly and will result in a time out when the File daemon fails to
814 connect to the Storage daemon.
816 That is all that is necessary. I copied the existing resource to create a
817 second Job (Matou) to backup the second client (matou-fd). It has the name
818 {\bf Matou}, the Client is named {\bf matou-fd}, and the bootstrap file name
819 is changed, but everything else is the same. This means that Matou will be
820 backed up on the same schedule using the same set of tapes. You may want to
821 change that later, but for now, let's keep it simple.
823 The second change was to add a new Client resource that defines {\bf matou-fd}
824 and has the correct address {\bf matou}, but in real life, you may need a
825 fully qualified domain name or an IP address. I also kept the password the
826 same (shown as xxxxx for the example).
828 At this point, if you stop Bacula and restart it, and start the Client on the
829 other machine, everything will be ready, and the prompts that you saw above
830 will now include the second machine.
832 To make this a real production installation, you will possibly want to use
833 different Pool, or a different schedule. It is up to you to customize. In any
834 case, you should change the password in both the Director's file and the
835 Client's file for additional security.
837 For some important tips on changing names and passwords, and a diagram of what
838 names and passwords must match, please see
839 \ilink{Authorization Errors}{AuthorizationErrors} in the FAQ chapter
842 \section{When The Tape Fills}
844 \index[general]{Fills!When The Tape }
845 \index[general]{When The Tape Fills }
847 If you have scheduled your job, typically nightly, there will come a time when
848 the tape fills up and {\bf Bacula} cannot continue. In this case, Bacula will
849 send you a message similar to the following:
853 rufus-sd: block.c:337 === Write error errno=28: ERR=No space left
858 This indicates that Bacula got a write error because the tape is full. Bacula
859 will then search the Pool specified for your Job looking for an appendable
860 volume. In the best of all cases, you will have properly set your Retention
861 Periods and you will have all your tapes marked to be Recycled, and {\bf
862 Bacula} will automatically recycle the tapes in your pool requesting and
863 overwriting old Volumes. For more information on recycling, please see the
864 \ilink{Recycling chapter}{RecyclingChapter} of this manual. If you
865 find that your Volumes were not properly recycled (usually because of a
866 configuration error), please see the
867 \ilink{Manually Recycling Volumes}{manualrecycling} section of
868 the Recycling chapter.
870 If like me, you have a very large set of Volumes and you label them with the
871 date the Volume was first writing, or you have not set up your Retention
872 periods, Bacula will not find a tape in the pool, and it will send you a
873 message similar to the following:
877 rufus-sd: Job kernsave.2002-09-19.10:50:48 waiting. Cannot find any
879 Please use the "label" command to create a new Volume for:
886 Until you create a new Volume, this message will be repeated an hour later,
887 then two hours later, and so on doubling the interval each time up to a
888 maximum interval of one day.
890 The obvious question at this point is: What do I do now?
892 The answer is simple: first, using the Console program, close the tape drive
893 using the {\bf unmount} command. If you only have a single drive, it will be
894 automatically selected, otherwise, make sure you release the one specified on
895 the message (in this case {\bf STD-10000}).
897 Next, you remove the tape from the drive and insert a new blank tape. Note, on
898 some older tape drives, you may need to write an end of file mark ({\bf mt \
899 -f \ /dev/nst0 \ weof}) to prevent the drive from running away when Bacula
900 attempts to read the label.
902 Finally, you use the {\bf label} command in the Console to write a label to
903 the new Volume. The {\bf label} command will contact the Storage daemon to
904 write the software label, if it is successful, it will add the new Volume to
905 the Pool, then issue a {\bf mount} command to the Storage daemon. See the
906 previous sections of this chapter for more details on labeling tapes.
908 The result is that Bacula will continue the previous Job writing the backup to
911 If you have a Pool of volumes and Bacula is cycling through them, instead of
912 the above message "Cannot find any appendable volumes.", Bacula may ask you
913 to mount a specific volume. In that case, you should attempt to do just that.
914 If you do not have the volume any more (for any of a number of reasons), you
915 can simply mount another volume from the same Pool, providing it is
916 appendable, and Bacula will use it. You can use the {\bf list volumes} command
917 in the console program to determine which volumes are appendable and which are
920 If like me, you have your Volume retention periods set correctly, but you have
921 no more free Volumes, you can relabel and reuse a Volume as follows:
924 \item Do a {\bf list volumes} in the Console and select the oldest Volume for
926 \item If you have setup your Retention periods correctly, the Volume should
927 have VolStatus {\bf Purged}.
928 \item If the VolStatus is not set to Purged, you will need to purge the
929 database of Jobs that are written on that Volume. Do so by using the command
930 {\bf purge jobs volume} in the Console. If you have multiple Pools, you will
931 be prompted for the Pool then enter the VolumeName (or MediaId) when
933 \item Then simply use the {\bf relabel} command to relabel the Volume.
936 To manually relabel the Volume use the following additional steps:
939 \item To delete the Volume from the catalog use the {\bf delete volume}
940 command in the Console and select the VolumeName (or MediaId) to be deleted.
942 \item Use the {\bf unmount} command in the Console to unmount the old tape.
943 \item Physically relabel the old Volume that you deleted so that it can be
945 \item Insert the old Volume in the tape drive.
946 \item From a command line do: {\bf mt \ -f \ /dev/st0 \ rewind} and {\bf mt \
947 -f \ /dev/st0 \ weof}, where you need to use the proper tape drive name for
948 your system in place of {\bf /dev/st0}.
949 \item Use the {\bf label} command in the Console to write a new Bacula label
951 \item Use the {\bf mount} command in the Console if it is not automatically
952 done, so that Bacula starts using your newly labeled tape.
955 \section{Other Useful Console Commands}
956 \index[general]{Commands!Other Useful Console }
957 \index[general]{Other Useful Console Commands }
962 \index[console]{status dir }
963 Print a status of all running jobs and jobs scheduled in the next 24 hours.
966 \index[console]{status }
967 The console program will prompt you to select a daemon type, then will
968 request the daemon's status.
970 \item [status jobid=nn]
971 \index[console]{status jobid }
972 Print a status of JobId nn if it is running. The Storage daemon is contacted
973 and requested to print a current status of the job as well.
976 \index[console]{list pools }
977 List the pools defined in the Catalog (normally only Default is used).
980 \index[console]{list media }
981 Lists all the media defined in the Catalog.
984 \index[console]{list jobs }
985 Lists all jobs in the Catalog that have run.
987 \item [list jobid=nn]
988 \index[console]{list jobid }
989 Lists JobId nn from the Catalog.
991 \item [list jobtotals]
992 \index[console]{list jobtotals }
993 Lists totals for all jobs in the Catalog.
995 \item [list files jobid=nn]
996 \index[console]{list files jobid }
997 List the files that were saved for JobId nn.
999 \item [list jobmedia]
1000 \index[console]{list jobmedia }
1001 List the media information for each Job run.
1004 \index[console]{messages }
1005 Prints any messages that have been directed to the console.
1007 \item [unmount storage=storage-name]
1008 \index[console]{unmount storage }
1009 Unmounts the drive associated with the storage device with the name {\bf
1010 storage-name} if the drive is not currently being used. This command is used
1011 if you wish Bacula to free the drive so that you can use it to label a tape.
1014 \item [mount storage=storage-name]
1015 \index[sd]{mount storage }
1016 Causes the drive associated with the storage device to be mounted again. When
1017 Bacula reaches the end of a volume and requests you to mount a new volume,
1018 you must issue this command after you have placed the new volume in the
1019 drive. In effect, it is the signal needed by Bacula to know to start reading
1020 or writing the new volume.
1024 Exit or quit the console program.
1027 Most of the commands given above, with the exception of {\bf list}, will
1028 prompt you for the necessary arguments if you simply enter the command name.
1030 \section{Debug Daemon Output}
1031 \index[general]{Debug Daemon Output }
1032 \index[general]{Output!Debug Daemon }
1034 If you want debug output from the daemons as they are running, start the
1035 daemons from the install directory as follows:
1039 ./bacula start -d100
1043 This can be particularly helpful if your daemons do not start correctly,
1044 because direct daemon output to the console is normally directed to the
1045 NULL device, but with the debug level greater than zero, the output
1046 will be sent to the starting terminal.
1048 To stop the three daemons, enter the following from the install directory:
1056 The execution of {\bf bacula stop} may complain about pids not found. This is
1057 OK, especially if one of the daemons has died, which is very rare.
1059 To do a full system save, each File daemon must be running as root so that it
1060 will have permission to access all the files. None of the other daemons
1061 require root privileges. However, the Storage daemon must be able to open the
1062 tape drives. On many systems, only root can access the tape drives. Either run
1063 the Storage daemon as root, or change the permissions on the tape devices to
1064 permit non-root access. MySQL and PostgreSQL can be installed and run with any
1065 userid; root privilege is not necessary.
1067 \section{Patience When Starting Daemons or Mounting Blank Tapes}
1069 When you start the Bacula daemons, the Storage daemon attempts to open all
1070 defined storage devices and verify the currently mounted Volume (if
1071 configured). Until all the storage devices are verified, the Storage daemon
1072 will not accept connections from the Console program. If a tape was previously
1073 used, it will be rewound, and on some devices this can take several minutes.
1074 As a consequence, you may need to have a bit of patience when first contacting
1075 the Storage daemon after starting the daemons. If you can see your tape drive,
1076 once the lights stop flashing, the drive will be ready to be used.
1078 The same considerations apply if you have just mounted a blank tape in a drive
1079 such as an HP DLT. It can take a minute or two before the drive properly
1080 recognizes that the tape is blank. If you attempt to {\bf mount} the tape with
1081 the Console program during this recognition period, it is quite possible that
1082 you will hang your SCSI driver (at least on my Red Hat Linux system). As a
1083 consequence, you are again urged to have patience when inserting blank tapes.
1084 Let the device settle down before attempting to access it.
1086 \section{Difficulties Connecting from the FD to the SD}
1087 \index[general]{Difficulties Connecting from the FD to the SD}
1088 \index[general]{SD!Difficulties Connecting from the FD to the SD}
1090 If you are having difficulties getting one or more of your File daemons to
1091 connect to the Storage daemon, it is most likely because you have not used a
1092 fully qualified domain name on the {\bf Address} directive in the
1093 Director's Storage resource. That is the resolver on the File daemon's machine
1094 (not on the Director's) must be able to resolve the name you supply into an IP
1095 address. An example of an address that is guaranteed not to work: {\bf
1096 localhost}. An example that may work: {\bf megalon}. An example that is more
1097 likely to work: {\bf magalon.mydomain.com}. On Win32 if you don't have a good
1098 resolver (often true on older Win98 systems), you might try using an IP
1099 address in place of a name.
1101 If your address is correct, then make sure that no other program is using the
1102 port 9103 on the Storage daemon's machine. The Bacula port number are
1103 authorized by IANA, and should not be used by other programs, but apparently
1104 some HP printers do use these port numbers. A {\bf netstat -a} on the Storage
1105 daemon's machine can determine who is using the 9103 port (used for FD to SD
1106 communications in Bacula).
1108 \section{Daemon Command Line Options}
1109 \index[general]{Daemon Command Line Options }
1110 \index[general]{Options!Daemon Command Line }
1112 Each of the three daemons (Director, File, Storage) accepts a small set of
1113 options on the command line. In general, each of the daemons as well as the
1114 Console program accepts the following options:
1118 \item [-c \lt{}file\gt{}]
1119 \index[sd]{-c \lt{}file\gt{} }
1120 Define the file to use as a configuration file. The default is the daemon
1121 name followed by {\bf .conf} i.e. {\bf bacula-dir.conf} for the Director,
1122 {\bf bacula-fd.conf} for the File daemon, and {\bf bacula-sd} for the Storage
1127 Set the debug level to {\bf nn}. Higher levels of debug cause more
1128 information to be displayed on STDOUT concerning what the daemon is doing.
1131 Run the daemon in the foreground. This option is needed to run the daemon
1135 Do not trap signals. This option is needed to run the daemon under the
1139 Read the configuration file and print any error messages, then immediately
1140 exit. Useful for syntax testing of new configuration files.
1143 Be more verbose or more complete in printing error and informational
1144 messages. Recommended.
1147 Print the version and list of options.
1150 The Director has the following additional Director specific option:
1154 \item [-r \lt{}job\gt{}]
1155 \index[fd]{-r \lt{}job\gt{} }
1156 Run the named job immediately. This is for debugging and should not be used.
1159 The File daemon has the following File daemon specific option:
1164 Assume that the daemon is called from {\bf inetd} or {\bf xinetd}. In this
1165 case, the daemon assumes that a connection has already been made and that it
1166 is passed as STDIN. After the connection terminates the daemon will exit.
1169 The Storage daemon has no Storage daemon specific options.
1171 The Console program has no console specific options.
1173 \section{Creating a Pool}
1175 \index[general]{Pool!Creating a }
1176 \index[general]{Creating a Pool }
1178 Creating the Pool is automatically done when {\bf Bacula} starts, so if you
1179 understand Pools, you can skip to the next section.
1181 When you run a job, one of the things that Bacula must know is what Volumes to
1182 use to backup the FileSet. Instead of specifying a Volume (tape) directly, you
1183 specify which Pool of Volumes you want Bacula to consult when it wants a tape
1184 for writing backups. Bacula will select the first available Volume from the
1185 Pool that is appropriate for the Storage device you have specified for the Job
1186 being run. When a volume has filled up with data, {\bf Bacula} will change its
1187 VolStatus from {\bf Append} to {\bf Full}, and then {\bf Bacula} will use the
1188 next volume and so on. If no appendable Volume exists in the Pool, the
1189 Director will attempt to recycle an old Volume, if there are still no
1190 appendable Volumes available, {\bf Bacula} will send a message requesting the
1191 operator to create an appropriate Volume.
1193 {\bf Bacula} keeps track of the Pool name, the volumes contained in the Pool,
1194 and a number of attributes of each of those Volumes.
1196 When Bacula starts, it ensures that all Pool resource definitions have been
1197 recorded in the catalog. You can verify this by entering:
1205 to the console program, which should print something like the following:
1210 Using default Catalog name=MySQL DB=bacula
1211 +--------+---------+---------+---------+----------+-------------+
1212 | PoolId | Name | NumVols | MaxVols | PoolType | LabelFormat |
1213 +--------+---------+---------+---------+----------+-------------+
1214 | 1 | Default | 3 | 0 | Backup | * |
1215 | 2 | File | 12 | 12 | Backup | File |
1216 +--------+---------+---------+---------+----------+-------------+
1221 If you attempt to create the same Pool name a second time, {\bf Bacula} will
1226 Error: Pool Default already exists.
1227 Once created, you may use the {\bf update} command to
1228 modify many of the values in the Pool record.
1234 \section{Labeling Your Volumes}
1235 \index[general]{Volumes!Labeling Your }
1236 \index[general]{Labeling Your Volumes }
1238 Bacula requires that each Volume contains a software label. There are several
1239 strategies for labeling volumes. The one I use is to label them as they are
1240 needed by {\bf Bacula} using the console program. That is when Bacula needs a
1241 new Volume, and it does not find one in the catalog, it will send me an email
1242 message requesting that I add Volumes to the Pool. I then use the {\bf label}
1243 command in the Console program to label a new Volume and to define it in the
1244 Pool database, after which Bacula will begin writing on the new Volume.
1245 Alternatively, I can use the Console {\bf relabel} command to relabel a Volume
1246 that is no longer used providing it has VolStatus {\bf Purged}.
1248 Another strategy is to label a set of volumes at the start, then use them as
1249 {\bf Bacula} requests them. This is most often done if you are cycling through
1250 a set of tapes, for example using an autochanger. For more details on
1251 recycling, please see the
1252 \ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of
1255 If you run a Bacula job, and you have no labeled tapes in the Pool, Bacula
1256 will inform you, and you can create them "on-the-fly" so to speak. In my
1257 case, I label my tapes with the date, for example: {\bf DLT-18April02}. See
1258 below for the details of using the {\bf label} command.
1260 \section{Labeling Volumes with the Console Program}
1261 \index[general]{Labeling Volumes with the Console Program }
1262 \index[general]{Program!Labeling Volumes with the Console }
1264 Labeling volumes is normally done by using the console program.
1271 If Bacula complains that you cannot label the tape because it is already
1272 labeled, simply {\bf unmount} the tape using the {\bf unmount} command in the
1273 console, then physically mount a blank tape and re-issue the {\bf label}
1276 Since the physical storage media is different for each device, the {\bf label}
1277 command will provide you with a list of the defined Storage resources such as
1282 The defined Storage resources are:
1287 Select Storage resource (1-4):
1291 At this point, you should have a blank tape in the drive corresponding to the
1292 Storage resource that you select.
1294 It will then ask you for the Volume name.
1298 Enter new Volume name:
1302 If Bacula complains:
1306 Media record for Volume xxxx already exists.
1310 It means that the volume name {\bf xxxx} that you entered already exists in
1311 the Media database. You can list all the defined Media (Volumes) with the {\bf
1312 list media} command. Note, the LastWritten column has been truncated for
1317 +---------------+---------+--------+----------------+-----/~/-+------------+-----+
1318 | VolumeName | MediaTyp| VolStat| VolBytes | LastWri | VolReten | Recy|
1319 +---------------+---------+--------+----------------+---------+------------+-----+
1320 | DLTVol0002 | DLT8000 | Purged | 56,128,042,217 | 2001-10 | 31,536,000 | 0 |
1321 | DLT-07Oct2001 | DLT8000 | Full | 56,172,030,586 | 2001-11 | 31,536,000 | 0 |
1322 | DLT-08Nov2001 | DLT8000 | Full | 55,691,684,216 | 2001-12 | 31,536,000 | 0 |
1323 | DLT-01Dec2001 | DLT8000 | Full | 55,162,215,866 | 2001-12 | 31,536,000 | 0 |
1324 | DLT-28Dec2001 | DLT8000 | Full | 57,888,007,042 | 2002-01 | 31,536,000 | 0 |
1325 | DLT-20Jan2002 | DLT8000 | Full | 57,003,507,308 | 2002-02 | 31,536,000 | 0 |
1326 | DLT-16Feb2002 | DLT8000 | Full | 55,772,630,824 | 2002-03 | 31,536,000 | 0 |
1327 | DLT-12Mar2002 | DLT8000 | Full | 50,666,320,453 | 1970-01 | 31,536,000 | 0 |
1328 | DLT-27Mar2002 | DLT8000 | Full | 57,592,952,309 | 2002-04 | 31,536,000 | 0 |
1329 | DLT-15Apr2002 | DLT8000 | Full | 57,190,864,185 | 2002-05 | 31,536,000 | 0 |
1330 | DLT-04May2002 | DLT8000 | Full | 60,486,677,724 | 2002-05 | 31,536,000 | 0 |
1331 | DLT-26May02 | DLT8000 | Append | 1,336,699,620 | 2002-05 | 31,536,000 | 1 |
1332 +---------------+---------+--------+----------------+-----/~/-+------------+-----+
1336 Once Bacula has verified that the volume does not already exist, it will
1337 prompt you for the name of the Pool in which the Volume (tape) is to be
1338 created. If there is only one Pool (Default), it will be automatically
1341 If the tape is successfully labeled, a Volume record will also be created in
1342 the Pool. That is the Volume name and all its other attributes will appear
1343 when you list the Pool. In addition, that Volume will be available for backup
1344 if the MediaType matches what is requested by the Storage daemon.
1346 When you labeled the tape, you answered very few questions about it --
1347 principally the Volume name, and perhaps the Slot. However, a Volume record in
1348 the catalog database (internally known as a Media record) contains quite a few
1349 attributes. Most of these attributes will be filled in from the default values
1350 that were defined in the Pool (i.e. the Pool holds most of the default
1351 attributes used when creating a Volume).
1353 It is also possible to add media to the pool without physically labeling the
1354 Volumes. This can be done with the {\bf add} command. For more information,
1356 \ilink{Console Chapter}{_ConsoleChapter} of this manual.