4 \chapter{Bacula Console}
5 \label{_ConsoleChapter}
6 \index[general]{Console!Bacula}
7 \index[general]{Bacula Console}
8 \index[console]{Console!Bacula}
9 \index[console]{Bacula Console}
11 The {\bf Bacula Console} (sometimes called the User Agent) is a program that
12 allows the user or the System Administrator, to interact with the Bacula
13 Director daemon while the daemon is running.
15 The current Bacula Console comes in two versions: a shell interface (TTY
16 style), and a GNOME GUI interface. Both permit the administrator or authorized
17 users to interact with Bacula. You can determine the status of a particular
18 job, examine the contents of the Catalog as well as perform certain tape
19 manipulations with the Console program.
21 In addition, there is a bwx-console built with wxWidgets that allows a graphic
22 restore of files. As of version 1.34.1 it is in an early stage of development,
23 but it already is quite useful. Unfortunately, it has not been enhanced for
26 Since the Console program interacts with the Director through the network, your
27 Console and Director programs do not necessarily need to run on the same
30 In fact, a certain minimal knowledge of the Console program is needed in order
31 for Bacula to be able to write on more than one tape, because when Bacula
32 requests a new tape, it waits until the user, via the Console program,
33 indicates that the new tape is mounted.
35 \section{Console Configuration}
36 \index[general]{Console Configuration}
37 \index[general]{Configuration!Console}
38 \index[console]{Console Configuration}
39 \index[console]{Configuration!Console}
41 When the Console starts, it reads a standard Bacula configuration file named
42 {\bf bconsole.conf} or {\bf bgnome-console.conf} in the case of the GNOME
43 Console version. This file allows default configuration of the Console, and at
44 the current time, the only Resource Record defined is the Director resource,
45 which gives the Console the name and address of the Director. For more
46 information on configuration of the Console program, please see the
47 \ilink{Console Configuration File}{ConsoleConfChapter} Chapter of
50 \section{Running the Console Program}
51 \index[general]{Running the Console Program}
52 \index[general]{Program!Running the Console}
53 \index[console]{Running the Console Program}
54 \index[console]{Program!Running the Console}
56 The console program can be run with the following options:
59 Usage: bconsole [-s] [-c config_file] [-d debug_level]
60 -c <file> set configuration file to file
61 -dnn set debug level to nn
64 -t test - read configuration and exit
65 -? print this message.
70 After launching the Console program (bconsole), it will prompt you for the
71 next command with an asterisk (*). (Note, in the GNOME version, the prompt is
72 not present; you simply enter the commands you want in the command text box at
73 the bottom of the screen.) Generally, for all commands, you can simply enter
74 the command name and the Console program will prompt you for the necessary
75 arguments. Alternatively, in most cases, you may enter the command followed by
76 arguments. The general format is:
80 <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
84 where {\bf command} is one of the commands listed below; {\bf keyword} is one
85 of the keywords listed below (usually followed by an argument); and {\bf
86 argument} is the value. The command may be abbreviated to the shortest unique
87 form. If two commands have the same starting letters, the one that will be
88 selected is the one that appears first in the {\bf help} listing. If you want
89 the second command, simply spell out the full command. None of the keywords
90 following the command may be abbreviated.
100 will list all files saved for JobId 23. Or:
108 will display all the Pool resource records.
110 The maximum command line length is limited to 511 characters, so if you
111 are scripting the console, you may need to take some care to limit the
114 \section{Stopping the Console Program}
115 \index[general]{Program!Stopping the Console}
116 \index[general]{Stopping the Console Program}
117 \index[console]{Program!Stopping the Console}
118 \index[console]{Stopping the Console Program}
120 Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
121 will terminate. However, it waits until the Director acknowledges the command.
122 If the Director is already doing a lengthy command (e.g. prune), it may take
123 some time. If you want to immediately terminate the Console program, enter the
126 There is currently no way to interrupt a Console command once issued (i.e.
127 Ctrl-C does not work). However, if you are at a prompt that is asking you to
128 select one of several possibilities and you would like to abort the command,
129 you can enter a period ({\bf .}), and in most cases, you will either be
130 returned to the main command prompt or if appropriate the previous prompt (in
131 the case of nested prompts). In a few places such as where it is asking for a
132 Volume name, the period will be taken to be the Volume name. In that case, you
133 will most likely be able to cancel at the next prompt.
136 \section{Alphabetic List of Console Keywords}
137 \index[general]{Keywords!Alphabetic List of Console}
138 \index[general]{Alphabetic List of Console Keywords}
139 \index[console]{Keywords!Alphabetic List of Console}
140 \index[console]{Alphabetic List of Console Keywords}
141 Unless otherwise specified, each of the following keywords
142 takes an argument, which is specified after the keyword following
143 an equal sign. For example:
149 Please note, this list is incomplete as it is currently in
150 the process of being created and is not currently totally in
156 Permitted on the python command, and causes the Python
157 interpreter to be restarted. Takes no argument.
159 Permitted on the status and show commands to specify all components or
160 resources respectively.
162 Permitted on the update command to specify that all Volumes in the
163 pool (specified on the command line) should be updated.
165 Used in the restore command.
167 Used in the restore command.
169 Allowed in the use command to specify the catalog name
172 Used in the show command. Takes no arguments.
175 Used in the show, list, and llist commands. Takes no arguments.
177 Used in the show command. Takes no arguments.
179 Used in the restore command. Takes no argument.
181 Used to define the number of days the "list nextvol" command
182 should consider when looking for jobs to be run. The days keyword
183 can also be used on the "status dir" command so that it will display
184 jobs scheduled for the number of days you want.
186 Used in the show command. Takes no arguments.
187 \item [dir | director]
189 Used in the show command. Takes no arguments.
191 Used in the restore command. Its argument specifies the directory
194 This keyword can appear on the {\bf update volume} as well
195 as the {\bf update slots} commands, and can
196 allows one of the following arguments: yes, true, no, false, archived,
197 0, 1, 2. Where 0 corresponds to no or false, 1 corresponds to yes or true, and
198 2 corresponds to archived. Archived volumes will not be used, nor will
199 the Media record in the catalog be pruned. Volumes that are not enabled,
200 will not be used for backup or restore.
202 Used in the restore command. Takes no argument.
204 Used in the restore command.
206 Used in the list and llist commands. Takes no arguments.
209 Used in the show command. Takes no arguments.
211 Used in the show command. Takes no arguments.
213 Used in the show, list and llist commands. Takes no arguments.
215 Used in the list and llist commands. Takes no arguments.
217 Used in the list and llist commands. Takes no arguments.
219 The JobId is the numeric jobid that is printed in the Job
220 Report output. It is the index of the database record for the
221 given job. While it is unique for all the existing Job records
222 in the catalog database, the same JobId can be reused once a
223 Job is removed from the catalog. Probably you will refer
224 specific Jobs that ran using their numeric JobId.
225 \item [job | jobname]
226 The Job or Jobname keyword refers to the name you specified
227 in the Job resource, and hence it refers to any number of
228 Jobs that ran. It is typically useful if you want to list
229 all jobs of a particular name.
232 Permitted on the estimate command. Takes no argument.
235 Used in the show command. Takes no arguments.
237 Used in the list and llist commands. Takes no arguments.
238 \item [nextvol | nextvolume]
239 Used in the list and llist commands. Takes no arguments.
246 Used in the show, list, and llist commands. Takes no arguments.
248 Used in the restore command. Takes no argument.
250 Used in the show command. Takes no arguments.
252 Used in the show command. Takes no arguments.
253 \item [sd | store | storage]
255 The ujobid is a unique job identification that is printed
256 in the Job Report output. At the current time, it consists
257 of the Job name (from the Name directive for the job) appended
258 with the date and time the job was run. This keyword is useful
259 if you want to completely identify the Job instance run.
262 Used in the list and llist commands. Takes no arguments.
264 Used in the restore command.
266 Used in the restore command. Takes no argument.
270 \section{Alphabetic List of Console Commands}
271 \index[general]{Commands!Alphabetic List of Console}
272 \index[general]{Alphabetic List of Console Commands}
273 \index[console]{Commands!Alphabetic List of Console}
274 \index[console]{Alphabetic List of Console Commands}
276 The following commands are currently implemented:
279 \item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
280 jobid=\lt{}JobId\gt{}]} ]
282 This command is used to add Volumes to an existing Pool. That is,
283 it creates the Volume name in the catalog and inserts into the Pool
284 in the catalog, but does not attempt to access the physical Volume.
286 added, Bacula expects that Volume to exist and to be labeled.
287 This command is not normally used since Bacula will
288 automatically do the equivalent when Volumes are labeled. However,
289 there may be times when you have removed a Volume from the catalog
290 and want to later add it back.
292 Normally, the {\bf label} command is used rather than this command
293 because the {\bf label} command labels the physical media (tape) and
294 does the equivalent of the {\bf add} command. The {\bf add} command
295 affects only the Catalog and not the physical media (data on Volumes).
296 The physical media must exist and be labeled before use (usually with
297 the {\bf label} command). This command can, however, be useful if you
298 wish to add a number of Volumes to the Pool that will be physically
299 labeled at a later time. It can also be useful if you are importing a
300 tape from another site. Please see the {\bf label} command below for
301 the list of legal characters in a Volume name.
303 \item [autodisplay on/off]
304 \index[console]{autodisplay on/off}
305 This command accepts {\bf on} or {\bf off} as an argument, and turns
306 auto-display of messages on or off respectively. The default for the
307 console program is {\bf off}, which means that you will be notified when
308 there are console messages pending, but they will not automatically be
309 displayed. The default for the bgnome-console program is {\bf on}, which
310 means that messages will be displayed when they are received (usually
311 within five seconds of them being generated).
313 When autodisplay is turned off, you must explicitly retrieve the
314 messages with the {\bf messages} command. When autodisplay is turned
315 on, the messages will be displayed on the console as they are received.
317 \item [automount on/off]
318 \index[console]{automount on/off}
319 This command accepts {\bf on} or {\bf off} as the argument, and turns
320 auto-mounting of the tape after a {\bf label} command on or off
321 respectively. The default is {\bf on}. If {\bf automount} is turned
322 off, you must explicitly {\bf mount} the tape after a label command to
325 \item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
326 \index[console]{cancel jobid}
327 This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
328 job=xxx} as an argument where nnn is replaced by the JobId and xxx is
329 replaced by the job name. If you do not specify a keyword, the Console
330 program will prompt you with the names of all the active jobs allowing
333 Once a Job is marked to be canceled, it may take a bit of time
334 (generally within a minute) before it actually terminates, depending on
335 what operations it is doing.
337 \item [{create [pool=\lt{}pool-name\gt{}]}]
338 \index[console]{create pool}
339 This command is not normally used as the Pool records are automatically
340 created by the Director when it starts based on what it finds in
341 the conf file. If needed, this command can be
342 to create a Pool record in the database using the
343 Pool resource record defined in the Director's configuration file. So
344 in a sense, this command simply transfers the information from the Pool
345 resource in the configuration file into the Catalog. Normally this
346 command is done automatically for you when the Director starts providing
347 the Pool is referenced within a Job resource. If you use this command
348 on an existing Pool, it will automatically update the Catalog to have
349 the same information as the Pool resource. After creating a Pool, you
350 will most likely use the {\bf label} command to label one or more
351 volumes and add their names to the Media database.
353 When starting a Job, if Bacula determines that there is no Pool record
354 in the database, but there is a Pool resource of the appropriate name,
355 it will create it for you. If you want the Pool record to appear in the
356 database immediately, simply use this command to force it to be created.
358 \item [{delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
359 jobid=\lt{}id\gt{}]}]
360 \index[console]{delete}
361 The delete command is used to delete a Volume, Pool or Job record from
362 the Catalog as well as all associated catalog Volume records that were
363 created. This command operates only on the Catalog database and has no
364 effect on the actual data written to a Volume. This command can be
365 dangerous and we strongly recommend that you do not use it unless you
366 know what you are doing.
368 If the keyword {\bf Volume} appears on the command line, the named
369 Volume will be deleted from the catalog, if the keyword {\bf Pool}
370 appears on the command line, a Pool will be deleted, and if the keyword
371 {\bf Job} appears on the command line, a Job and all its associated
372 records (File and JobMedia) will be deleted from the catalog. The full
373 form of this command is:
376 delete pool=<pool-name>
382 delete volume=>volume-name> pool=>pool-name> or
386 delete JobId=>job-id> JobId=>job-id2> ... or
390 delete Job JobId=n,m,o-r,t ...
393 The first form deletes a Pool record from the catalog database. The
394 second form deletes a Volume record from the specified pool in the
395 catalog database. The third form deletes the specified Job record from
396 the catalog database. The last form deletes JobId records for JobIds
397 n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
398 number. That is a "delete jobid" accepts lists and ranges of
401 \item [disable job\lt{}job-name\gt{}]
402 \index[console]{enable}
403 This command permits you to disable a Job for automatic scheduling.
404 The job may have been previously enabled with the Job resource
405 {\bf Enabled} directive or using the console {\bf enable} command.
406 The next time the Director is restarted or the conf file is reloaded,
407 the Enable/Disable state will be set to the value in the Job resource
408 (default enabled) as defined in the bacula-dir.conf file.
410 \item [enable job\lt{}job-name\gt{}]
411 \index[console]{enable}
412 This command permits you to enable a Job for automatic scheduling.
413 The job may have been previously disabled with the Job resource
414 {\bf Enabled} directive or using the console {\bf disable} command.
415 The next time the Director is restarted or the conf file is reloaded,
416 the Enable/Disable state will be set to the value in the Job resource
417 (default enabled) as defined in the bacula-dir.conf file.
421 \index[console]{estimate}
422 Using this command, you can get an idea how many files will be backed
423 up, or if you are unsure about your Include statements in your FileSet,
424 you can test them without doing an actual backup. The default is to
425 assume a Full backup. However, you can override this by specifying a
426 {\bf level=Incremental} or {\bf level=Differential} on the command line.
427 A Job name must be specified or you will be prompted for one, and
428 optionally a Client and FileSet may be specified on the command line.
429 It then contacts the client which computes the number of files and bytes
430 that would be backed up. Please note that this is an estimate
431 calculated from the number of blocks in the file rather than by reading
432 the actual bytes. As such, the estimated backup size will generally be
433 larger than an actual backup.
435 Optionally you may specify the keyword {\bf listing} in which case, all the
436 files to be backed up will be listed. Note, it could take quite some time to
437 display them if the backup is large. The full form is:
441 estimate job=<job-name> listing client=<client-name>
442 fileset=<fileset-name> level=<level-name>
445 Specification of the {\bf job} is sufficient, but you can also override
446 the client, fileset and/or level by specifying them on the estimate
450 As an example, you might do:
455 estimate job=NightlySave listing level=Incremental
460 which will do a full listing of all files to be backed up for the Job {\bf
461 NightlySave} during an Incremental save and put it in the file {\bf
462 /tmp/listing}. Note, the byte estimate provided by this command is
463 based on the file size contained in the directory item. This can give
464 wildly incorrect estimates of the actual storage used if there are
465 sparse files on your systems. Sparse files are often found on 64 bit
466 systems for certain system files. The size that is returned is the size
467 Bacula will backup if the sparse option is not specified in the FileSet.
468 There is currently no way to get an estimate of the real file size that
469 would be found should the sparse option be enabled.
473 \index[console]{help}
474 This command displays the list of commands available.
477 \index[console]{label}
478 \index[console]{relabel}
479 \index[general]{label}
480 \index[general]{relabel}
481 This command is used to label physical volumes. The full form of this command
485 label storage=>storage-name> volume=>volume-name>
489 If you leave out any part, you will be prompted for it. The media type
490 is automatically taken from the Storage resource definition that you
491 supply. Once the necessary information is obtained, the Console program
492 contacts the specified Storage daemon and requests that the tape be
493 labeled. If the tape labeling is successful, the Console program will
494 create a Volume record in the appropriate Pool.
496 The Volume name is restricted to letters, numbers, and the special
497 characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
498 period ({\bf .}). All other characters including a space are invalid.
499 This restriction is to ensure good readability of Volume names to reduce
502 Please note, when labeling a blank tape, Bacula will get {\bf read I/O
503 error} when it attempts to ensure that the tape is not already labeled. If
504 you wish to avoid getting these messages, please write an EOF mark on
505 your tape before attempting to label it:
515 The label command can fail for a number of reasons:
518 \item The Volume name you specify is already in the Volume database.
519 \item The Storage daemon has a tape already mounted on the device, in which
520 case you must {\bf unmount} the device, insert a blank tape, then do the
522 \item The tape in the device is already a Bacula labeled tape. (Bacula will
523 never relabel a Bacula labeled tape unless it is recycled and you use the
524 {\bf relabel} command).
525 \item There is no tape in the drive.
528 There are two ways to relabel a volume that already has a Bacula label. The
529 brute force method is to write an end of file mark on the tape using the
530 system {\bf mt} program, something like the following:
534 mt -f /dev/st0 rewind
539 Then you use the {\bf label} command to add a new label. However, this could
540 leave traces of the old volume in the catalog.
542 The preferable method to relabel a tape is to first {\bf purge} the volume,
543 either automatically, or explicitly with the {\bf purge} command, then use
544 the {\bf relabel} command described below.
546 If your autochanger has barcode labels, you can label all the Volumes in
547 your autochanger one after another by using the {\bf label barcodes}
548 command. For each tape in the changer containing a barcode, Bacula will
549 mount the tape and then label it with the same name as the barcode. An
550 appropriate Media record will also be created in the catalog. Any barcode
551 that begins with the same characters as specified on the
552 "CleaningPrefix=xxx" directive in the Director's Pool resource, will be
553 treated as a cleaning tape, and will not be labeled. However, an entry for
554 the cleaning tape will be created in the catalog. For example with:
560 Cleaning Prefix = "CLN"
566 Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
567 and will not be mounted. Note, the full form of the command is:
571 update storage=xxx pool=yyy slots=1-5,10 barcodes
576 \index[console]{list}
577 The list command lists the requested contents of the Catalog. The
578 various fields of each record are listed on a single line. The various
579 forms of the list command are:
584 list jobid=<id> (list jobid id)
586 list ujobid<unique job name> (list job with unique name)
588 list job=<job-name> (list all jobs with "job-name")
590 list jobname=<job-name> (same as above)
592 In the above, you can add "limit=nn" to limit the output to
597 list jobmedia jobid=<id>
599 list jobmedia job=<job-name>
601 list files jobid=<id>
603 list files job=<job-name>
613 list volumes jobid=<id>
615 list volumes pool=<pool-name>
617 list volumes job=<job-name>
619 list volume=<volume-name>
621 list nextvolume job=<job-name>
623 list nextvol job=<job-name>
625 list nextvol job=<job-name> days=nnn
630 What most of the above commands do should be more or less obvious. In
631 general if you do not specify all the command line arguments, the
632 command will prompt you for what is needed.
634 The {\bf list nextvol} command will print the Volume name to be used by
635 the specified job. You should be aware that exactly what Volume will be
636 used depends on a lot of factors including the time and what a prior job
637 will do. It may fill a tape that is not full when you issue this
638 command. As a consequence, this command will give you a good estimate
639 of what Volume will be used but not a definitive answer. In addition,
640 this command may have certain side effect because it runs through the
641 same algorithm as a job, which means it may automatically purge or
642 recycle a Volume. By default, the job specified must run within the
643 next two days or no volume will be found. You can, however, use the
644 {\bf days=nnn} specification to specify up to 50 days. For example,
645 if on Friday, you want to see what Volume will be needed on Monday,
646 for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
648 If you wish to add specialized commands that list the contents of the
649 catalog, you can do so by adding them to the {\bf query.sql} file.
650 However, this takes some knowledge of programming SQL. Please see the
651 {\bf query} command below for additional information. See below for
652 listing the full contents of a catalog record with the {\bf llist}
655 As an example, the command {\bf list pools} might produce the following
660 +------+---------+---------+---------+----------+-------------+
661 | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
662 +------+---------+---------+---------+----------+-------------+
663 | 1 | Default | 0 | 0 | Backup | * |
664 | 2 | Recycle | 0 | 8 | Backup | File |
665 +------+---------+---------+---------+----------+-------------+
669 As mentioned above, the {\bf list} command lists what is in the
670 database. Some things are put into the database immediately when Bacula
671 starts up, but in general, most things are put in only when they are
672 first used, which is the case for a Client as with Job records, etc.
674 Bacula should create a client record in the database the first time you
675 run a job for that client. Doing a {\bf status} will not cause a
676 database record to be created. The client database record will be
677 created whether or not the job fails, but it must at least start. When
678 the Client is actually contacted, additional info from the client will
679 be added to the client record (a "uname -a" output).
681 If you want to see what Client resources you have available in your conf
682 file, you use the Console command {\bf show clients}.
685 \index[console]{llist}
686 The llist or "long list" command takes all the same arguments that the
687 list command described above does. The difference is that the llist
688 command list the full contents of each database record selected. It
689 does so by listing the various fields of the record vertically, with one
690 field per line. It is possible to produce a very large number of output
691 lines with this command.
693 If instead of the {\bf list pools} as in the example above, you enter
694 {\bf llist pools} you might get the following output:
705 VolRetention: 1,296,000
706 VolUseDuration: 86,400
722 VolUseDuration: 3,600
734 \index[console]{messages}
735 This command causes any pending console messages to be immediately displayed.
739 \index[console]{mount}
740 The mount command is used to get Bacula to read a volume on a physical
741 device. It is a way to tell Bacula that you have mounted a tape and
742 that Bacula should examine the tape. This command is normally
743 used only after there was no Volume in a drive and Bacula requests you to mount a new
744 Volume or when you have specifically unmounted a Volume with the {\bf
745 unmount} console command, which causes Bacula to close the drive. If
746 you have an autoloader, the mount command will not cause Bacula to
747 operate the autoloader unless you specify a {\bf slot} and possibly a
748 {\bf drive}. The various forms of the mount command are:
750 mount storage=\lt{}storage-name\gt{} [ slot=\lt{}num\gt{} ] [
751 drive=\lt{}num\gt{} ]
753 mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
755 If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
756 Device resource, under most circumstances, Bacula will automatically access
757 the Volume unless you have explicitly {\bf unmount}ed it in the Console
761 \index[console]{python}
762 The python command takes a single argument {\bf restart}:
766 This causes the Python interpreter in the Director to be reinitialized.
767 This can be helpful for testing because once the Director starts and the
768 Python interpreter is initialized, there is no other way to make it
769 accept any changes to the startup script {\bf DirStartUp.py}. For more
770 details on Python scripting, please see the \ilink{Python
771 Scripting}{PythonChapter} chapter of this manual.
773 \label{ManualPruning}
775 \index[console]{prune}
776 The Prune command allows you to safely remove expired database records
777 from Jobs and Volumes. This command works only on the Catalog database
778 and does not affect data written to Volumes. In all cases, the Prune
779 command applies a retention period to the specified records. You can
780 Prune expired File entries from Job records; you can Prune expired Job
781 records from the database, and you can Prune both expired Job and File
782 records from specified Volumes.
784 prune files|jobs|volume client=\lt{}client-name\gt{}
785 volume=\lt{}volume-name\gt{}
787 For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
788 Append, otherwise the pruning will not take place.
791 \index[console]{purge}
792 The Purge command will delete associated Catalog database records from
793 Jobs and Volumes without considering the retention period. {\bf Purge}
794 works only on the Catalog database and does not affect data written to
795 Volumes. This command can be dangerous because you can delete catalog
796 records associated with current backups of files, and we recommend that
797 you do not use it unless you know what you are doing. The permitted
798 forms of {\bf purge} are:
800 purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
802 purge jobs client=\lt{}client-name\gt{} (of all jobs)
804 purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
806 For the {\bf purge} command to work on Volume Catalog database records the
807 {\bf VolStatus} must be Append, Full, Used, or Error.
809 The actual data written to the Volume will be unaffected by this command.
812 \index[console]{relabel}
813 \index[general]{relabel}
814 This command is used to label physical volumes. The full form of this
817 relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
818 volume=\lt{}newvolume-name\gt{}
820 If you leave out any part, you will be prompted for it. In order for
821 the Volume (old-volume-name) to be relabeled, it must be in the catalog,
822 and the volume status must be marked {\bf Purged} or {\bf Recycle}.
823 This happens automatically as a result of applying retention periods, or
824 you may explicitly purge the volume using the {\bf purge} command.
826 Once the volume is physically relabeled, the old data previously written
827 on the Volume is lost and cannot be recovered.
830 \index[console]{release}
831 This command is used to cause the Storage daemon to rewind (release) the
832 current tape in the drive, and to re-read the Volume label the next time
835 release storage=\lt{}storage-name\gt{}
837 After a release command, the device is still kept open by Bacula (unless
838 Always Open is set to No in the Storage Daemon's configuration) so it
839 cannot be used by another program. However, with some tape drives, the
840 operator can remove the current tape and to insert a different one, and
841 when the next Job starts, Bacula will know to re-read the tape label to
842 find out what tape is mounted. If you want to be able to use the drive
843 with another program (e.g. {\bf mt}), you must use the {\bf unmount}
844 command to cause Bacula to completely release (close) the device.
847 \index[console]{reload}
848 The reload command causes the Director to re-read its configuration
849 file and apply the new values. The new values will take effect
850 immediately for all new jobs. However, if you change schedules,
851 be aware that the scheduler pre-schedules jobs up to two hours in
852 advance, so any changes that are to take place during the next two
853 hours may be delayed. Jobs that have already been scheduled to run
854 (i.e. surpassed their requested start time) will continue with the
855 old values. New jobs will use the new values. Each time you issue
856 a reload command while jobs are running, the prior config values
857 will queued until all jobs that were running before issuing
858 the reload terminate, at which time the old config values will
859 be released from memory. The Directory permits keeping up to
860 ten prior set of configurations before it will refuse a reload
861 command. Once at least one old set of config values has been
862 released it will again accept new reload commands.
864 While it is possible to reload the Director's configuration on the fly,
865 even while jobs are executing, this is a complex operation and not
866 without side effects. Accordingly, if you have to reload the Director's
867 configuration while Bacula is running, it is advisable to restart the
868 Director at the next convenient opportunity.
870 \label{restore_command}
872 \index[console]{restore}
873 The restore command allows you to select one or more Jobs (JobIds) to be
874 restored using various methods. Once the JobIds are selected, the File
875 records for those Jobs are placed in an internal Bacula directory tree,
876 and the restore enters a file selection mode that allows you to
877 interactively walk up and down the file tree selecting individual files
878 to be restored. This mode is somewhat similar to the standard Unix {\bf
879 restore} program's interactive file selection mode.
881 restore storage=\lt{}storage-name\gt{} client=\lt{}backup-client-name\gt{}
882 where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
883 restoreclient=\lt{}restore-client-name\gt{}
884 select current all done
886 Where {\bf current}, if specified, tells the restore command to
887 automatically select a restore to the most current backup. If not
888 specified, you will be prompted. The {\bf all} specification tells the
889 restore command to restore all files. If it is not specified, you will
890 be prompted for the files to restore. For details of the {\bf restore}
891 command, please see the \ilink{Restore Chapter}{RestoreChapter} of this
894 The client keyword initially specifies the client from which the backup
895 was made and the client to which the restore will be make. However,
896 if the restoreclient keyword is specified, then the restore is written
901 This command allows you to schedule jobs to be run immediately. The full form
904 run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
905 fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
906 storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
907 when=\lt{}universal-time-specification\gt{} yes
909 Any information that is needed but not specified will be listed for
910 selection, and before starting the job, you will be prompted to accept,
911 reject, or modify the parameters of the job to be run, unless you have
912 specified {\bf yes}, in which case the job will be immediately sent to
915 On my system, when I enter a run command, I get the following prompt:
919 A job name must be specified.
920 The defined Job resources are:
930 Select Job resource (1-9):
935 If I then select number 5, I am prompted with:
941 FileSet: Minou Full Set
946 When: 2003-04-23 17:08:18
947 OK to run? (yes/mod/no):
952 If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
953 be presented with the following prompt.
957 Parameters to modify:
965 Select parameter to modify (1-7):
970 If you wish to start a job at a later time, you can do so by setting the When
971 time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
972 desired start time in YYYY-MM-DD HH:MM:SS format.
975 \index[console]{setdebug}
976 \index[dir]{setdebug}
977 \index[dir]{debugging}
978 \index[dir]{debugging Win32}
979 \index[dir]{Windows!debugging}
980 This command is used to set the debug level in each daemon. The form of this
983 setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
984 storage=\lt{}storage-name\gt{} | all]
986 If trace=1 is set, then tracing will be enabled, and the daemon will be
987 placed in trace mode, which means that all debug output as set by the
988 debug level will be directed to the file {\bf bacula.trace} in the
989 current directory of the daemon. Normally, tracing is needed only for
990 Win32 clients where the debug output cannot be written to a terminal or
991 redirected to a file. When tracing, each debug output message is
992 appended to the trace file. You must explicitly delete the file when
996 \index[console]{show}
998 The show command will list the Director's resource records as defined in
999 the Director's configuration file (normally {\bf bacula-dir.conf}).
1000 This command is used mainly for debugging purposes by developers.
1001 The following keywords are accepted on the
1002 show command line: catalogs, clients, counters, devices, directors,
1003 filesets, jobs, messages, pools, schedules, storages, all, help.
1004 Please don't confuse this command
1005 with the {\bf list}, which displays the contents of the catalog.
1008 \index[console]{sqlquery}
1009 The sqlquery command puts the Console program into SQL query mode where
1010 each line you enter is concatenated to the previous line until a
1011 semicolon (;) is seen. The semicolon terminates the command, which is
1012 then passed directly to the SQL database engine. When the output from
1013 the SQL engine is displayed, the formation of a new SQL command begins.
1014 To terminate SQL query mode and return to the Console command prompt,
1015 you enter a period (.) in column 1.
1017 Using this command, you can query the SQL catalog database directly.
1018 Note you should really know what you are doing otherwise you could
1019 damage the catalog database. See the {\bf query} command below for
1020 simpler and safer way of entering SQL queries.
1022 Depending on what database engine you are using (MySQL, PostgreSQL or
1023 SQLite), you will have somewhat different SQL commands available. For
1024 more detailed information, please refer to the MySQL, PostgreSQL or
1025 SQLite documentation.
1029 This command will display the status of the next jobs that are scheduled
1030 during the next 24 hours as well as the status of currently
1031 running jobs. The full form of this command is:
1033 status [all | dir=\lt{}dir-name\gt{} | director |
1034 client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} |
1037 If you do a {\bf status dir}, the console will list any currently
1038 running jobs, a summary of all jobs scheduled to be run in the next 24
1039 hours, and a listing of the last ten terminated jobs with their statuses.
1040 The scheduled jobs summary will include the Volume name to be used. You
1041 should be aware of two things: 1. to obtain the volume name, the code
1042 % TODO: use bullets here or be consistent with numbering items
1043 goes through the same code that will be used when the job runs, which
1044 means that it may prune or recycle a Volume; 2. The Volume listed is
1045 only a best guess. The Volume actually used may be different because of
1046 the time difference (more durations may expire when the job runs) and
1047 another job could completely fill the Volume requiring a new one.
1049 In the Running Jobs listing, you may find the following types of
1055 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
1056 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
1057 priority jobs to finish
1058 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
1059 5343 Full Rufus.2004-03-13_01.05.04 is running
1063 Looking at the above listing from bottom to top, obviously JobId 5343
1064 (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
1065 finish because it is using the Storage resource, hence the "waiting on
1066 max Storage jobs". JobId 5349 has a lower priority than all the other
1067 jobs so it is waiting for higher priority jobs to finish, and finally,
1068 JobId 2508 (MatouVerify) is waiting because only one job can run at a
1069 time, hence it is simply "waiting execution"
1071 If you do a {\bf status dir}, it will by default list the first
1072 occurrence of all jobs that are scheduled today and tomorrow. If you
1073 wish to see the jobs that are scheduled in the next three days (e.g. on
1074 Friday you want to see the first occurrence of what tapes are scheduled
1075 to be used on Friday, the weekend, and Monday), you can add the {\bf
1076 days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs
1077 scheduled today only. If you have multiple run statements, the first
1078 occurrence of each run statement for the job will be displayed for the
1081 If your job seems to be blocked, you can get a general idea of the
1082 problem by doing a {\bf status dir}, but you can most often get a
1083 much more specific indication of the problem by doing a
1084 {\bf status storage=xxx}. For example, on an idle test system, when
1085 I do {\bf status storage=File}, I get:
1089 Connecting to Storage daemon File at 192.168.68.112:8103
1091 rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
1092 Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
1098 Jobs waiting to reserve a drive:
1102 JobId Level Files Bytes Status Finished Name
1103 ======================================================================
1104 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
1108 utochanger "DDS-4-changer" with devices:
1110 Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
1112 Slot 2 is loaded in drive 0.
1113 Total Bytes Read=0 Blocks Read=0 Bytes/block=0
1114 Positioned at File=0 Block=0
1115 Device "Dummy" is not open or does not exist.
1116 No DEVICE structure.
1118 Device "DVD-Writer" (/dev/hdc) is not open.
1119 Device "File" (/tmp) is not open.
1122 In Use Volume status:
1127 Now, what this tells me is that no jobs are running and that none of
1128 the devices are in use. Now, if I {\bf unmount} the autochanger, which
1129 will not be used in this example, and then start a Job that uses the
1130 File device, the job will block. When I re-issue the status storage
1131 command, I get for the Device status:
1138 Autochanger "DDS-4-changer" with devices:
1140 Device "DDS-4" (/dev/nst0) is not open.
1141 Device is BLOCKED. User unmounted.
1142 Drive 0 is not loaded.
1143 Device "Dummy" is not open or does not exist.
1144 No DEVICE structure.
1146 Device "DVD-Writer" (/dev/hdc) is not open.
1147 Device "File" (/tmp) is not open.
1148 Device is BLOCKED waiting for media.
1154 Now, here it should be clear that if a job were running that wanted
1155 to use the Autochanger (with two devices), it would block because
1156 the user unmounted the device. The real problem for the Job I started
1157 using the "File" device is that the device is blocked waiting for
1158 media -- that is Bacula needs you to label a Volume.
1161 \index[console]{unmount}
1162 This command causes the indicated Bacula Storage daemon to unmount the
1163 specified device. The forms of the command are the same as the mount command:
1166 unmount storage=<storage-name> [ drive=<num> ]
1168 unmount [ jobid=<id> | job=<job-name> ]
1172 Once you unmount a storage device, Bacula will no longer be able to use
1173 it until you issue a mount command for that device. If Bacula needs to
1174 access that device, it will block and issue mount requests periodically
1177 If the device you are unmounting is an autochanger, it will unload
1178 the drive you have specified on the command line. If no drive is
1179 specified, it will assume drive 1.
1181 \label{UpdateCommand}
1183 \index[console]{update}
1184 This command will update the catalog for either a specific Pool record, a Volume
1185 record, or the Slots in an autochanger with barcode capability. In the case
1186 of updating a Pool record, the new information will be automatically taken
1187 from the corresponding Director's configuration resource record. It can be
1188 used to increase the maximum number of volumes permitted or to set a maximum
1189 number of volumes. The following main keywords may be specified:
1192 media, volume, pool, slots
1196 In the case of updating a Volume, you will be prompted for which value you
1197 wish to change. The following Volume parameters may be changed:
1203 Volume Retention Period
1206 Maximum Volume Files
1207 Maximum Volume Bytes
1215 All Volumes from Pool
1220 For slots {\bf update slots}, Bacula will obtain a list of slots and
1221 their barcodes from the Storage daemon, and for each barcode found, it
1222 will automatically update the slot in the catalog Media record to
1223 correspond to the new value. This is very useful if you have moved
1224 cassettes in the magazine, or if you have removed the magazine and
1225 inserted a different one. As the slot of each Volume is updated, the
1226 InChanger flag for that Volume will also be set, and any other Volumes
1227 in the Pool that were last mounted on the same Storage device
1228 will have their InChanger flag turned off. This permits
1229 Bacula to know what magazine (tape holder) is currently in the
1232 If you do not have barcodes, you can accomplish the same thing in
1233 version 1.33 and later by using the {\bf update slots scan} command.
1234 The {\bf scan} keyword tells Bacula to physically mount each tape and to
1235 read its VolumeName.
1237 For Pool {\bf update pool}, Bacula will move the Volume record from its
1238 existing pool to the pool specified.
1240 For {\bf Volume from Pool} and {\bf All Volumes from Pool}, the
1241 following values are updated from the Pool record: Recycle, RecyclePool,
1242 VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, and MaxVolBytes.
1243 (RecyclePool feature is available with bacula 2.1.4 or higher.)
1245 The full form of the update command with all command line arguments is:
1249 update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
1250 VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
1251 slot=nnn enabled=n recyclepool=zzz
1257 \index[console]{use}
1258 This command allows you to specify which Catalog database to use. Normally,
1259 you will be using only one database so this will be done automatically. In
1260 the case that you are using more than one database, you can use this command
1261 to switch from one to another.
1263 use \lt{}database-name\gt{}
1267 \index[console]{var name}
1268 This command takes a string or quoted string and does variable expansion on
1269 it the same way variable expansion is done on the {\bf LabelFormat} string.
1270 Thus, for the most part, you can test your LabelFormat strings. The
1271 difference between the {\bf var} command and the actual LabelFormat process
1272 is that during the var command, no job is running so "dummy" values are
1273 used in place of Job specific variables. Generally, however, you will get a
1274 good idea of what is going to happen in the real case.
1277 \index[console]{version}
1278 The command prints the Director's version.
1281 \index[console]{quit}
1282 This command terminates the console program. The console program sends the
1283 {\bf quit} request to the Director and waits for acknowledgment. If the
1284 Director is busy doing a previous command for you that has not terminated, it
1285 may take some time. You may quit immediately by issuing the {\bf .quit}
1286 command (i.e. quit preceded by a period).
1289 \index[console]{query}
1290 This command reads a predefined SQL query from the query file (the name and
1291 location of the query file is defined with the QueryFile resource record in
1292 the Director's configuration file). You are prompted to select a query from
1293 the file, and possibly enter one or more parameters, then the command is
1294 submitted to the Catalog database SQL engine.
1296 The following queries are currently available (version 1.24):
1302 2: List where a file is saved:
1303 3: List where the most recent copies of a file are saved:
1304 4: List total files/bytes by Job:
1305 5: List total files/bytes by Volume:
1306 6: List last 20 Full Backups for a Client:
1307 7: List Volumes used by selected JobId:
1308 8: List Volumes to Restore All Files:
1309 9: List where a File is saved:
1310 Choose a query (1-9):
1316 \index[console]{exit}
1317 This command terminates the console program.
1320 \index[console]{wait}
1321 The wait command causes the Director to pause until there are no jobs
1322 running. This command is useful in a batch situation such as regression
1323 testing where you wish to start a job and wait until that job completes
1324 before continuing. This command now has the following options:
1327 wait [jobid=nn] [jobuid=unique id] [job=job name]
1330 If specified with a specific JobId, ... the wait command will wait
1331 for that particular job to terminate before continuing.
1336 \section{Special dot Commands}
1337 \index[general]{Commands!Special dot}
1338 \index[general]{Special dot Commands}
1340 There is a list of commands that are prefixed with a period (.). These
1341 commands are intended to be used either by batch programs or graphical user
1342 interface front-ends. They are not normally used by interactive users. Once
1343 GUI development begins, this list will be considerably expanded. The following
1344 is the list of dot commands:
1348 .backups job=xxx list backups for specified job
1349 .clients list all client names
1350 .defaults client=xxx fileset=yyy list defaults for specified client
1351 .die cause the Director to segment fault (for debugging)
1352 .dir when in tree mode prints the equivalent to the dir command,
1353 but with fields separated by commas rather than spaces.
1355 .filesets list all fileset names
1356 .help help command output
1357 .jobs list all job names
1358 .levels list all levels
1359 .messages get quick messages
1360 .msgs return any queued messages
1361 .pools list all pool names
1363 .status get status output
1364 .storage return storage resource names
1365 .types list job types
1371 \section{Special At (@) Commands}
1372 \index[general]{Commands!Special At @}
1373 \index[general]{Special At (@) Commands}
1375 Normally, all commands entered to the Console program are immediately
1376 forwarded to the Director, which may be on another machine, to be executed.
1377 However, there is a small list of {\bf at} commands, all beginning with an at
1378 character (@), that will not be sent to the Director, but rather interpreted
1379 by the Console program directly. Note, these commands are implemented only in
1380 the tty console program and not in the GNOME Console. These commands are:
1384 \item [@input \lt{}filename\gt{}]
1385 \index[console]{@input \lt{}filename\gt{}}
1386 Read and execute the commands contained in the file specified.
1388 \item [@output \lt{}filename\gt{} w/a]
1389 \index[console]{@output \lt{}filename\gt{} w/a}
1390 Send all following output to the filename specified either overwriting the
1391 file (w) or appending to the file (a). To redirect the output to the
1392 terminal, simply enter {\bf @output} without a filename specification.
1393 WARNING: be careful not to overwrite a valid file. A typical example during a
1394 regression test might be:
1405 \item [@tee \lt{}filename\gt{} w/a]
1406 \index[console]{@tee \lt{}filename\gt{} w/a}
1407 Send all subsequent output to both the specified file and the terminal. It is
1408 turned off by specifying {\bf @tee} or {\bf @output} without a filename.
1410 \item [@sleep \lt{}seconds\gt{}]
1411 \index[console]{@sleep \lt{}seconds\gt{}}
1412 Sleep the specified number of seconds.
1415 \index[console]{@time}
1416 Print the current time and date.
1419 \index[console]{@version}
1420 Print the console's version.
1423 \index[console]{@quit}
1427 \index[console]{@exit}
1430 \item [@\# anything]
1431 \index[console]{anything}
1437 \section{Running the Console from a Shell Script}
1438 \index[general]{Script!Running the Console Program from a Shell}
1439 \index[general]{Running the Console Program from a Shell Script}
1441 You can automate many Console tasks by running the console program from a
1442 shell script. For example, if you have created a file containing the following
1447 ./bconsole -c ./bconsole.conf <<END_OF_DATA
1448 unmount storage=DDS-4
1454 when that file is executed, it will unmount the current DDS-4 storage device.
1455 You might want to run this command during a Job by using the {\bf
1456 RunBeforeJob} or {\bf RunAfterJob} records.
1458 It is also possible to run the Console program from file input where the file
1459 contains the commands as follows:
1463 ./bconsole -c ./bconsole.conf <filename
1467 where the file named {\bf filename} contains any set of console commands.
1469 As a real example, the following script is part of the Bacula regression
1470 tests. It labels a volume (a disk volume), runs a backup, then does a restore
1475 bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
1478 @output /tmp/log1.out
1479 label volume=TestVolume001
1486 @output /tmp/log2.out
1497 The output from the backup is directed to /tmp/log1.out and the output from
1498 the restore is directed to /tmp/log2.out. To ensure that the backup and
1499 restore ran correctly, the output files are checked with:
1503 grep "^Termination: *Backup OK" /tmp/log1.out
1505 grep "^Termination: *Restore OK" /tmp/log2.out
1510 \section{Adding Volumes to a Pool}
1511 \index[general]{Adding Volumes to a Pool}
1512 \index[general]{Pool!Adding Volumes to a}
1514 If you have used the {\bf label} command to label a Volume, it will be
1515 automatically added to the Pool, and you will not need to add any media to the
1518 Alternatively, you may choose to add a number of Volumes to the pool without
1519 labeling them. At a later time when the Volume is requested by {\bf Bacula}
1520 you will need to label it.
1522 Before adding a volume, you must know the following information:
1525 \item The name of the Pool (normally "Default")
1526 \item The Media Type as specified in the Storage Resource in the Director's
1527 configuration file (e.g. "DLT8000")
1528 \item The number and names of the Volumes you wish to create.
1531 For example, to add media to a Pool, you would issue the following commands to
1532 the console program:
1537 Enter name of Pool to add Volumes to: Default
1538 Enter the Media Type: DLT8000
1539 Enter number of Media volumes to create. Max=1000: 10
1540 Enter base volume name: Save
1541 Enter the starting number: 1
1542 10 Volumes created in pool Default
1547 To see what you have added, enter:
1551 *list media pool=Default
1552 +-------+----------+---------+---------+-------+------------------+
1553 | MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
1554 +-------+----------+---------+---------+-------+------------------+
1555 | 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1556 | 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1557 | 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1558 | 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1559 | 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1560 | 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1561 | 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1562 | 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1563 | 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1564 | 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1565 +-------+----------+---------+---------+-------+------------------+
1570 Notice that the console program automatically appended a number to the base
1571 Volume name that you specify (Save in this case). If you don't want it to
1572 append a number, you can simply answer 0 (zero) to the question "Enter number
1573 of Media volumes to create. Max=1000:", and in this case, it will create a
1574 single Volume with the exact name you specify.