4 \section*{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}
10 \addcontentsline{toc}{section}{Bacula Console}
13 \index[general]{General}
14 \addcontentsline{toc}{subsection}{General}
16 The {\bf Bacula Console} (sometimes called the User Agent) is a program that
17 allows the user or the System Administrator, to interact with the Bacula
18 Director daemon while the daemon is running.
20 The current Bacula Console comes in two versions: a shell interface (TTY
21 style), and a GNOME GUI interface. Both permit the administrator or authorized
22 users to interact with Bacula. You can determine the status of a particular
23 job, examine the contents of the Catalog as well as perform certain tape
24 manipulations with the Console program.
26 In addition, there is a wx-console built with wxWidgets that allows a graphic
27 restore of files. As of version 1.34.1 it is in an early stage of development,
28 but it already is quite useful.
30 Since the Console program interacts with the Director through the network, your
31 Console and Director programs do not necessarily need to run on the same
34 In fact, a certain minimal knowledge of the Console program is needed in order
35 for Bacula to be able to write on more than one tape, because when Bacula
36 requests a new tape, it waits until the user, via the Console program,
37 indicates that the new tape is mounted.
39 \subsection*{Console Configuration}
40 \index[general]{Console Configuration}
41 \index[general]{Configuration!Console}
42 \index[console]{Console Configuration}
43 \index[console]{Configuration!Console}
44 \addcontentsline{toc}{subsection}{Console Configuration}
46 When the Console starts, it reads a standard Bacula configuration file named
47 {\bf bconsole.conf} or {\bf gnome-console.conf} in the case of the GNOME
48 Console version. This file allows default configuration of the Console, and at
49 the current time, the only Resource Record defined is the Director resource,
50 which gives the Console the name and address of the Director. For more
51 information on configuration of the Console program, please see the
52 \ilink{Console Configuration File}{_ChapterStart36} Chapter of
55 \subsection*{Running the Console Program}
56 \index[general]{Running the Console Program}
57 \index[general]{Program!Running the Console}
58 \index[console]{Running the Console Program}
59 \index[console]{Program!Running the Console}
60 \addcontentsline{toc}{subsection}{Running the Console Program}
62 The console program can be run with the following options:
65 Usage: bconsole [-s] [-c config_file] [-d debug_level]
66 -c <file> set configuration file to file
67 -dnn set debug level to nn
70 -t test - read configuration and exit
71 -? print this message.
76 After launching the Console program (bconsole), it will prompt you for the
77 next command with an asterisk (*). (Note, in the GNOME version, the prompt is
78 not present; you simply enter the commands you want in the command text box at
79 the bottom of the screen.) Generally, for all commands, you can simply enter
80 the command name and the Console program will prompt you for the necessary
81 arguments. Alternatively, in most cases, you may enter the command followed by
82 arguments. The general format is:
86 <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
90 where {\bf command} is one of the commands listed below; {\bf keyword} is one
91 of the keywords listed below (usually followed by an argument); and {\bf
92 argument} is the value. The command may be abbreviated to the shortest unique
93 form. If two commands have the same starting letters, the one that will be
94 selected is the one that appears first in the {\bf help} listing. If you want
95 the second command, simply spell out the full command. None of the keywords
96 following the command may be abbreviated.
106 will list all files saved for JobId 23. Or:
114 will display all the Pool resource records.
116 \subsection*{Stopping the Console Program}
117 \index[general]{Program!Stopping the Console}
118 \index[general]{Stopping the Console Program}
119 \index[console]{Program!Stopping the Console}
120 \index[console]{Stopping the Console Program}
121 \addcontentsline{toc}{subsection}{Stopping the Console Program}
123 Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
124 will terminate. However, it waits until the Director acknowledges the command.
125 If the Director is already doing a lengthy command (e.g. prune), it may take
126 some time. If you want to immediately terminate the Console program, enter the
129 There is currently no way to interrupt a Console command once issued (i.e.
130 Ctrl-C does not work). However, if you are at a prompt that is asking you to
131 select one of several possibilities and you would like to abort the command,
132 you can enter a period ({\bf .}), and in most cases, you will either be
133 returned to the main command prompt or if appropriate the previous prompt (in
134 the case of nested prompts). In a few places such as where it is asking for a
135 Volume name, the period will be taken to be the Volume name. In that case, you
136 will most likely be able to cancel at the next prompt.
139 \subsection*{Alphabetic List of Console Keywords}
140 \index[general]{Keywords!Alphabetic List of Console}
141 \index[general]{Alphabetic List of Console Keywords}
142 \index[console]{Keywords!Alphabetic List of Console}
143 \index[console]{Alphabetic List of Console Keywords}
144 \addcontentsline{toc}{subsection}{Alphabetic List of Console Keywords}
145 Unless otherwise specified, each of the following keywords
146 takes an argument, which is specified after the keyword following
147 an equal sign. For example:
153 Please note, this list is incomplete as it is currently in
154 the process of being created and is not currently totally in
160 Permitted on the python command, and causes the Python
161 interpreter to be restarted. Takes no argument.
163 Permitted on the status and show commands to specify all components or
164 resources respectively.
166 Used in the restore command.
168 Used in the restore command.
170 Allowed in the use command to specify the catalog name
173 Used in the show command. Takes no arguments.
176 Used in the show, list, and llist commands. Takes no arguments.
178 Used in the show command. Takes no arguments.
180 Used in the restore command. Takes no argument.
182 Used to define the number of days the "list nextvol" command
183 should consider when looking for jobs to be run. The days keyword
184 can also be used on the "status dir" command so that it will display
185 jobs scheduled for the number of days you want.
187 Used in the show command. Takes no arguments.
188 \item [dir | director]
190 Used in the show command. Takes no arguments.
192 Used in the restore command.
194 Used in the restore command. Takes no argument.
196 Used in the restore command.
198 Used in the list and llist commands. Takes no arguments.
201 Used in the show command. Takes no arguments.
203 Used in the show command. Takes no arguments.
205 Used in the show, list and llist commands. Takes no arguments.
207 Used in the list and llist commands. Takes no arguments.
209 Used in the list and llist commands. Takes no arguments.
211 The JobId is the numeric jobid that is printed in the Job
212 Report output. It is the index of the database record for the
213 given job. While it is unique for all the existing Job records
214 in the catalog database, the same JobId can be reused once a
215 Job is removed from the catalog. Probably you will refer
216 specific Jobs that ran using their numeric JobId.
217 \item [job | jobname]
218 The Job or Jobname keyword refers to the name you specified
219 in the Job resource, and hence it refers to any number of
220 Jobs that ran. It is typically useful if you want to list
221 all jobs of a particular name.
224 Permitted on the estimate command. Takes no argument.
227 Used in the show command. Takes no arguments.
229 Used in the list and llist commands. Takes no arguments.
230 \item [nextvol | nextvolume]
231 Used in the list and llist commands. Takes no arguments.
238 Used in the show, list, and llist commands. Takes no arguments.
240 Used in the restore command. Takes no argument.
242 Used in the show command. Takes no arguments.
244 Used in the show command. Takes no arguments.
245 \item [sd | store | storage]
247 The ujobid is a unique job identification that is printed
248 in the Job Report output. At the current time, it consists
249 of the Job name (from the Name directive for the job) appended
250 with the date and time the job was run. This keyword is useful
251 if you want to completely identify the Job instance run.
254 Used in the list and llist commands. Takes no arguments.
256 Used in the restore command.
258 Used in the restore command. Takes no argument.
262 \subsection*{Alphabetic List of Console Commands}
263 \index[general]{Commands!Alphabetic List of Console}
264 \index[general]{Alphabetic List of Console Commands}
265 \index[console]{Commands!Alphabetic List of Console}
266 \index[console]{Alphabetic List of Console Commands}
267 \addcontentsline{toc}{subsection}{Alphabetic List of Console Commands}
269 The following commands are currently implemented:
272 \item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
273 jobid=\lt{}JobId\gt{}]} ]
275 This command is not normally used since Bacula will normally
276 do it automatically as Volumes are labeled. However, if you need it,
277 this command is used to add Volumes to an existing Pool. The Volume names
278 entered are placed in the Catalog and thus become available for backup
279 operations. Normally, the {\bf label} command is used rather than this
280 command because the {\bf label} command labels the physical media (tape) and
281 does the equivalent of the {\bf add} command. This command affects only the
282 Catalog and not the physical media (data on Volumes). The physical media must
283 exist and be labeled before use (usually with the {\bf label} command). This
284 command can, however, be useful if you wish to add a number of Volumes to the
285 Pool that will be physically labeled at a later time. It can also be useful
286 if you are importing a tape from another site. Please see the {\bf label}
287 command below for the list of legal characters in a Volume name.
289 \item [autodisplay on/off]
290 \index[console]{autodisplay on/off}
291 This command accepts {\bf on} or {\bf off} as an argument, and turns
292 auto-display of messages on or off respectively. The default for the
293 console program is {\bf off}, which means that you will be notified when
294 there are console messages pending, but they will not automatically be
295 displayed. The default for the gnome-console program is {\bf on}, which
296 means that messages will be displayed when they are received (usually
297 within 5 seconds of them being generated).
299 When autodisplay is turned off, you must explicitly retrieve the
300 messages with the {\bf messages} command. When autodisplay is turned
301 on, the messages will be displayed on the console as they are received.
303 \item [automount on/off]
304 \index[console]{automount on/off}
305 This command accepts {\bf on} or {\bf off} as the argument, and turns
306 auto-mounting of the tape after a {\bf label} command on or off
307 respectively. The default is {\bf on}. If {\bf automount} is turned
308 off, you must explicitly {\bf mount} the tape after a label command to
311 \item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
312 \index[console]{cancel jobid}
313 This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
314 job=xxx} as an argument where nnn is replaced by the JobId and xxx is
315 replaced by the job name. If you do not specify a keyword, the Console
316 program will prompt you with the names of all the active jobs allowing
319 Once a Job is marked to be canceled, it may take a bit of time
320 (generally within a minute) before it actually terminates, depending on
321 what operations it is doing.
323 \item [{create [pool=\lt{}pool-name\gt{}]}]
324 \index[console]{create pool}
325 This command is not normally used as the Pool records are automatically
326 created by the Director when it starts based on what it finds in
327 the conf file. If needed, this command can be
328 to create a Pool record in the database using the
329 Pool resource record defined in the Director's configuration file. So
330 in a sense, this command simply transfers the information from the Pool
331 resource in the configuration file into the Catalog. Normally this
332 command is done automatically for you when the Director starts providing
333 the Pool is referenced within a Job resource. If you use this command
334 on an existing Pool, it will automatically update the Catalog to have
335 the same information as the Pool resource. After creating a Pool, you
336 will most likely use the {\bf label} command to label one or more
337 volumes and add their names to the Media database.
339 When starting a Job, if Bacula determines that there is no Pool record
340 in the database, but there is a Pool resource of the appropriate name,
341 it will create it for you. If you want the Pool record to appear in the
342 database immediately, simply use this command to force it to be created.
344 \item [{delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
345 jobid=\lt{}id\gt{}]}]
346 \index[console]{delete}
347 The delete command is used to delete a Volume, Pool or Job record from
348 the Catalog as well as all associated catalog Volume records that were
349 created. This command operates only on the Catalog database and has no
350 effect on the actual data written to a Volume. This command can be
351 dangerous and we strongly recommend that you do not use it unless you
352 know what you are doing.
354 If the keyword {\bf Volume} appears on the command line, the named
355 Volume will be deleted from the catalog, if the keyword {\bf Pool}
356 appears on the command line, a Pool will be deleted, and if the keyword
357 {\bf Job} appears on the command line, a Job and all its associated
358 records (File and JobMedia) will be deleted from the catalog. The full
359 form of this command is:
362 delete pool=\lt{}pool-name\gt{}
368 delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{} or
372 delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ... or
376 delete Job JobId=n,m,o-r,t ...
379 The first form deletes a Pool record from the catalog database. The
380 second form deletes a Volume record from the specified pool in the
381 catalog database. The third form deletes the specified Job record from
382 the catalog database. The last form deletes JobId records for JobIds
383 n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
384 number. That is a "delete jobid" accepts lists and ranges of
387 \item [disable job\lt{}job-name\gt{}]
388 \index[console]{enable}
389 This command permits you to disable a Job for automatic scheduling.
390 The job may have been previously enabled with the Job resource
391 {\bf Enabled} directive or using the console {\bf enable} command.
392 The next time the Director is restarted or the conf file is reloaded,
393 the Enable/Disable state will be set to the value in the Job resource
396 \item [enable job\lt{}job-name\gt{}]
397 \index[console]{enable}
398 This command permits you to enable a Job for automatic scheduling.
399 The job may have been previously disabled with the Job resource
400 {\bf Enabled} directive or using the console {\bf disable} command.
401 The next time the Director is restarted or the conf file is reloaded,
402 the Enable/Disable state will be set to the value in the Job resource
407 \index[console]{estimate}
408 Using this command, you can get an idea how many files will be backed
409 up, or if you are unsure about your Include statements in your FileSet,
410 you can test them without doing an actual backup. The default is to
411 assume a Full backup. However, you can override this by specifying a
412 {\bf level=Incremental} or {\bf level=Differential} on the command line.
413 A Job name must be specified or you will be prompted for one, and
414 optionally a Client and FileSet may be specified on the command line.
415 It then contacts the client which computes the number of files and bytes
416 that would be backed up. Please note that this is an estimate
417 calculated from the number of blocks in the file rather than by reading
418 the actual bytes. As such, the estimated backup size will generally be
419 larger than an actual backup.
421 Optionally you may specify the keyword {\bf listing} in which case, all the
422 files to be backed up will be listed. Note, it could take quite some time to
423 display them if the backup is large. The full form is:
427 estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{}
428 fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{}
431 Specification of the {\bf job} is sufficient, but you can also override
432 the client, fileset and/or level by specifying them on the estimate
436 As an example, you might do:
441 estimate job=NightlySave listing level=Incremental
446 which will do a full listing of all files to be backed up for the Job {\bf
447 NightlySave} during an Incremental save and put it in the file {\bf
448 /tmp/listing}. Note, the byte estimate provided by this command is
449 based on the file size contained in the directory item. This can give
450 wildly incorrect estimates of the actual storage used if there are
451 sparse files on your systems. Sparse files are often found on 64 bit
452 systems for certain system files. The size that is returned is the size
453 Bacula will backup if the sparse option is not specified in the FileSet.
454 There is currently no way to get an estimate of the real file size that
455 would be found should the sparse option be enabled.
459 \index[console]{help}
460 This command displays the list of commands available.
463 \index[console]{label}
464 \index[console]{relabel}
465 \index[general]{label}
466 \index[general]{relabel}
467 This command is used to label physical volumes. The full form of this command
471 label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{}
475 If you leave out any part, you will be prompted for it. The media type
476 is automatically taken from the Storage resource definition that you
477 supply. Once the necessary information is obtained, the Console program
478 contacts the specified Storage daemon and requests that the tape be
479 labeled. If the tape labeling is successful, the Console program will
480 create a Volume record in the appropriate Pool.
482 The Volume name is restricted to letters, numbers, and the special
483 characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
484 period ({\bf .}). All other characters including a space are illegal.
485 This restriction is to ensure good readability of Volume names to reduce
488 Please note, when labeling a blank tape, Bacula will get {\bf read I/O
489 error} when it attempts to ensure that the tape is already labeled. If
490 you wish to avoid getting these messages, please write an EOF mark on
491 your tape before attempting to label it:
501 The label command can fail for a number of reasons:
504 \item The Volume name you specify is already in the Volume database.
505 \item The Storage daemon has a tape already mounted on the device, in which
506 case you must {\bf unmount} the device, insert a blank tape, then do the
508 \item The tape in the device is already a Bacula labeled tape. (Bacula will
509 never relabel a Bacula labeled tape unless it is recycled and you use the
510 {\bf relabel} command).
511 \item There is no tape in the drive.
514 There are two ways to relabel a volume that already has a Bacula label. The
515 brute force method is to write an end of file mark on the tape using the
516 system {\bf mt} program, something like the following:
520 mt -f /dev/st0 rewind
525 Then you use the {\bf label} command to add a new label. However, this could
526 leave traces of the old volume in the catalog.
528 The preferable method to relabel a tape is to first {\bf purge} the volume,
529 either automatically, or explicitly with the {\bf purge} command, then use
530 the {\bf relabel} command described below.
532 If your autochanger has barcode labels, you can label all the Volumes in your
533 autochanger one after another by using the {\bf label barcodes} command. For
534 each tape in the changer containing a barcode, Bacula will mount the tape and
535 then label it with the same name as the barcode. An appropriate Media record
536 will also be created in the catalog. Any barcode that begins with the same
537 characters as specified on the "CleaningPrefix=xxx" directive in the
538 Director's Pool resource, will be
539 treated as a cleaning tape, and will not be labeled. However,
540 an entry for the cleaning tape will be created in
541 the catalog. For example with:
547 Cleaning Prefix = "CLN"
553 Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
554 and will not be mounted. Note, the full form of the command is:
558 update storage=xxx pool=yyy slots=1-5,10 barcodes
563 \index[console]{list}
564 The list command lists the requested contents of the Catalog. The
565 various fields of each record are listed on a single line. The various
566 forms of the list command are:
571 list jobid=<id> (list jobid id)
573 list ujobid<unique job name> (list job with unique name)
575 list job=<job-name> (list all jobs with "job-name")
577 list jobname=<job-name> (same as above)
579 In the above, you can add "limit=nn" to limit the output to
584 list jobmedia jobid=<id>
586 list jobmedia job=<job-name>
588 list files jobid=<id>
590 list files job=<job-name>
600 list volumes jobid=<id>
602 list volumes pool=<pool-name>
604 list volumes job=<job-name>
606 list volume=<volume-name>
608 list nextvolume job=<job-name>
610 list nextvol job=<job-name>
612 list nextvol job=<job-name> days=nnn
617 What most of the above commands do should be more or less obvious. In
618 general if you do not specify all the command line arguments, the
619 command will prompt you for what is needed.
621 The {\bf list nextvol} command will print the Volume name to be used by
622 the specified job. You should be aware that exactly what Volume will be
623 used depends on a lot of factors including the time and what a prior job
624 will do. It may fill a tape that is not full when you issue this
625 command. As a consequence, this command will give you a good estimate
626 of what Volume will be used but not a definitive answer. In addition,
627 this command may have certain side effect because it runs through the
628 same algorithm as a job, which means it may automatically purge or
629 recycle a Volume. By default, the job specified must run within the
630 next two days or no volume will be found. You can, however, use the
631 {\bf days=nnn} specification to specify up to 50 days. For example,
632 if on Friday, you want to see what Volume will be needed on Monday,
633 for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
635 If you wish to add specialized commands that list the contents of the
636 catalog, you can do so by adding them to the {\bf query.sql} file.
637 However, this takes some knowledge of programming SQL. Please see the
638 {\bf query} command below for additional information. See below for
639 listing the full contents of a catalog record with the {\bf llist}
642 As an example, the command {\bf list pools} might produce the following
647 +------+---------+---------+---------+----------+-------------+
648 | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
649 +------+---------+---------+---------+----------+-------------+
650 | 1 | Default | 0 | 0 | Backup | * |
651 | 2 | Recycle | 0 | 8 | Backup | File |
652 +------+---------+---------+---------+----------+-------------+
656 As mentioned above, the {\bf list} command lists what is in the
657 database. Some things are put into the database immediately when Bacula
658 starts up, but in general, most things are put in only when they are
659 first used, which is the case for a Client as with Job records, etc.
661 Bacula should create a client record in the database the first time you
662 run a job for that client. Doing a {\bf status} will not cause a
663 database record to be created. The client database record will be
664 created whether or not the job fails, but it must at least start. When
665 the Client is actually contacted, additional info from the client will
666 be added to the client record (a "uname -a" output).
668 If you want to see what Client resources you have available in your conf
669 file, you use the Console command {\bf show clients}.
672 \index[console]{llist}
673 The llist or "long list" command takes all the same arguments that the
674 list command described above does. The difference is that the llist
675 command list the full contents of each database record selected. It
676 does so by listing the various fields of the record vertically, with one
677 field per line. It is possible to produce a very large number of output
678 lines with this command.
680 If instead of the {\bf list pools} as in the example above, you enter
681 {\bf llist pools} you might get the following output:
692 VolRetention: 1,296,000
693 VolUseDuration: 86,400
709 VolUseDuration: 3,600
721 \index[console]{messages}
722 This command causes any pending console messages to be immediately displayed.
726 \index[console]{mount}
727 The mount command is used to get Bacula to read a volume on a physical
728 device. It is a way to tell Bacula that you have mounted a tape and
729 that Bacula should examine the tape. This command is used only after
730 there was no Volume in a drive and Bacula requests you to mount a new
731 Volume or when you have specifically unmounted a Volume with the {\bf
732 unmount} console command, which causes Bacula to close the drive. If
733 you have an autoloader, the mount command will not cause Bacula to
734 operate the autoloader. The various forms of the mount command are:
736 mount storage=\lt{}storage-name\gt{}
738 mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
740 If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
741 Device resource, under most circumstances, Bacula will automatically access
742 the Volume unless you have explicitly {\bf unmount}ed it in the Console
746 \index[console]{python}
747 The python command takes a single argument {\bf restart}:
751 This causes the Python interpreter in the Director to be reinitialized.
752 This can be helpful for testing because once the Director starts and the
753 Python interpreter is initialized, there is no other way to make it
754 accept any changes to the startup script {\bf DirStartUp.py}. For more
755 details on Python scripting, please see the \ilink{Python
756 Scripting}{_ChapterStart60} chapter of this manual.
758 \label{ManualPruning}
760 \index[console]{prune}
761 The Prune command allows you to safely remove expired database records
762 from Jobs and Volumes. This command works only on the Catalog database
763 and does not affect data written to Volumes. In all cases, the Prune
764 command applies a retention period to the specified records. You can
765 Prune expired File entries from Job records; you can Prune expired Job
766 records from the database, and you can Prune both expired Job and File
767 records from specified Volumes.
769 prune files|jobs|volume client=\lt{}client-name\gt{}
770 volume=\lt{}volume-name\gt{}
772 For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
773 Append, otherwise the pruning will not take place.
776 \index[console]{purge}
777 The Purge command will delete associated Catalog database records from
778 Jobs and Volumes without considering the retention period. {\bf Purge}
779 works only on the Catalog database and does not affect data written to
780 Volumes. This command can be dangerous because you can delete catalog
781 records associated with current backups of files, and we recommend that
782 you do not use it unless you know what you are doing. The permitted
783 forms of {\bf purge} are:
785 purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
787 purge jobs client=\lt{}client-name\gt{} (of all jobs)
789 purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
791 For the {\bf purge} command to work on Volume Catalog database records the
792 {\bf VolStatus} must be Append, Full, Used, or Error.
794 The actual data written to the Volume will be unaffected by this command.
797 \index[console]{relabel}
798 \index[general]{relabel}
799 This command is used to label physical volumes. The full form of this
802 relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
803 volume=\lt{}newvolume-name\gt{}
805 If you leave out any part, you will be prompted for it. In order for
806 the Volume (old-volume-name) to be relabeled, it must be in the catalog,
807 and the volume status must be marked {\bf Purged} or {\bf Recycle}.
808 This happens automatically as a result of applying retention periods, or
809 you may explicitly purge the volume using the {\bf purge} command.
811 Once the volume is physically relabeled, the old data previously written
812 on the Volume is lost and cannot be recovered.
815 \index[console]{release}
816 This command is used to cause the Storage daemon to rewind (release) the
817 current tape in the drive, and to re-read the Volume label the next time
820 release storage=\lt{}storage-name\gt{}
822 After a release command, the device is still kept open by Bacula (unless
823 Always Open is set to No in the Storage Daemon's configuration) so it
824 cannot be used by another program. However, with some tape drives, the
825 operator can remove the current tape and to insert a different one, and
826 when the next Job starts, Bacula will know to re-read the tape label to
827 find out what tape is mounted. If you want to be able to use the drive
828 with another program (e.g. {\bf mt}), you must use the {\bf unmount}
829 command to cause Bacula to completely release (close) the device.
832 \index[console]{reload}
833 The reload command causes the Director to re-read its configuration
834 file and apply the new values. The new values will take effect
835 immediately for all new jobs. However, if you change schedules,
836 be aware that the scheduler pre-schedules jobs up to two hours in
837 advance, so any changes that are to take place during the next two
838 hours may be delayed. Jobs that have already been scheduled to run
839 (i.e. surpassed their requested start time) will continue with the
840 old values. New jobs will use the new values. Each time you issue
841 a reload command while jobs are running, the prior config values
842 will queued until all jobs that were running before issuing
843 the reload terminate, at which time the old config values will
844 be released from memory. The Directory permits keeping up to
845 10 prior set of configurations before it will refuse a reload
846 command. Once at least one old set of config values has been
847 released it will again accept new reload commands.
849 While it is possible to reload the Director's configuration on the fly,
850 even while jobs are executing, this is a complex operation and not
851 without side effects. Accordingly, if you have to reload the Director's
852 configuration while Bacula is running, it is advisable to restart the
853 Director at the next convenient opportunity.
855 \label{restore_command}
857 \index[console]{restore}
858 The restore command allows you to select one or more Jobs (JobIds) to be
859 restored using various methods. Once the JobIds are selected, the File
860 records for those Jobs are placed in an internal Bacula directory tree,
861 and the restore enters a file selection mode that allows you to
862 interactively walk up and down the file tree selecting individual files
863 to be restored. This mode is somewhat similar to the standard Unix {\bf
864 restore} program's interactive file selection mode.
866 restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{}
867 where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
868 select current all done
870 Where {\bf current}, if specified, tells the restore command to
871 automatically select a restore to the most current backup. If not
872 specified, you will be prompted. The {\bf all} specification tells the
873 restore command to restore all files. If it is not specified, you will
874 be prompted for the files to restore. For details of the {\bf restore}
875 command, please see the \ilink{Restore Chapter}{_ChapterStart13} of this
880 This command allows you to schedule jobs to be run immediately. The full form
883 run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
884 fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
885 storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
886 when=\lt{}universal-time-specification\gt{} yes
888 Any information that is needed but not specified will be listed for
889 selection, and before starting the job, you will be prompted to accept,
890 reject, or modify the parameters of the job to be run, unless you have
891 specified {\bf yes}, in which case the job will be immediately sent to
894 On my system, when I enter a run command, I get the following prompt:
898 A job name must be specified.
899 The defined Job resources are:
909 Select Job resource (1-9):
914 If I then select number 5, I am prompted with:
920 FileSet: Minou Full Set
925 When: 2003-04-23 17:08:18
926 OK to run? (yes/mod/no):
931 If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
932 be presented with the following prompt.
936 Parameters to modify:
944 Select parameter to modify (1-7):
949 If you wish to start a job at a later time, you can do so by setting the When
950 time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
951 desired start time in YYYY-MM-DD HH:MM:SS format.
954 \index[console]{setdebug}
955 \index[dir]{setdebug}
956 \index[dir]{debugging}
957 \index[dir]{debugging Win32}
958 \index[dir]{Windows!debugging}
959 This command is used to set the debug level in each daemon. The form of this
962 setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
963 storage=\lt{}storage-name\gt{} | all]
965 If trace=1 is set, then tracing will be enabled, and the daemon will be
966 placed in trace mode, which means that all debug output as set by the
967 debug level will be directed to the file {\bf bacula.trace} in the
968 current directory of the daemon. Normally, tracing is needed only for
969 Win32 clients where the debug output cannot be written to a terminal or
970 redirected to a file. When tracing, each debug output message is
971 appended to the trace file. You must explicitly delete the file when
975 \index[console]{show}
977 The show command will list the Director's resource records as defined in
978 the Director's configuration file (normally {\bf bacula-dir.conf}).
979 This command is used mainly for debugging purposes by developers.
980 The following keywords are accepted on the
981 show command line: catalogs, clients, counters, devices, directors,
982 filesets, jobs, messages, pools, schedules, storages, all, help.
983 Please don't confuse this command
984 with the {\bf list}, which displays the contents of the catalog.
987 \index[console]{sqlquery}
988 The sqlquery command puts the Console program into SQL query mode where
989 each line you enter is concatenated to the previous line until a
990 semicolon (;) is seen. The semicolon terminates the command, which is
991 then passed directly to the SQL database engine. When the output from
992 the SQL engine is displayed, the formation of a new SQL command begins.
993 To terminate SQL query mode and return to the Console command prompt,
994 you enter a period (.) in column 1.
996 Using this command, you can query the SQL catalog database directly.
997 Note you should really know what you are doing otherwise you could
998 damage the catalog database. See the {\bf query} command below for
999 simpler and safer way of entering SQL queries.
1001 Depending on what database engine you are using (MySQL, PostgreSQL or
1002 SQLite), you will have somewhat different SQL commands available. For
1003 more detailed information, please refer to the MySQL, PostgreSQL or
1004 SQLite documentation.
1008 This command will display the status of the next jobs that are scheduled
1009 during the next twenty-four hours as well as the status of currently
1010 running jobs. The full form of this command is:
1012 status [all | dir=\lt{}dir-name\gt{} | director |
1013 client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} |
1016 If you do a {\bf status dir}, the console will list any currently
1017 running jobs, a summary of all jobs scheduled to be run in the next 24
1018 hours, and a listing of the last 10 terminated jobs with their statuses.
1019 The scheduled jobs summary will include the Volume name to be used. You
1020 should be aware of two things: 1. to obtain the volume name, the code
1021 goes through the same code that will be used when the job runs, which
1022 means that it may prune or recycle a Volume; 2. The Volume listed is
1023 only a best guess. The Volume actually used may be different because of
1024 the time difference (more durations may expire when the job runs) and
1025 another job could completely fill the Volume requiring a new one.
1027 In the Running Jobs listing, you may find the following types of
1033 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
1034 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
1035 priority jobs to finish
1036 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
1037 5343 Full Rufus.2004-03-13_01.05.04 is running
1041 Looking at the above listing from bottom to top, obviously JobId 5343
1042 (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
1043 finish because it is using the Storage resource, hence the "waiting on
1044 max Storage jobs". JobId 5349 has a lower priority than all the other
1045 jobs so it is waiting for higher priority jobs to finish, and finally,
1046 JobId 2508 (MatouVerify) is waiting because only one job can run at a
1047 time, hence it is simply "waiting execution"
1049 If you do a {\bf status dir}, it will by default list the first
1050 occurrence of all jobs that are scheduled today and tomorrow. If you
1051 wish to see the jobs that are scheduled in the next 3 days (e.g. on
1052 Friday you want to see the first occurrence of what tapes are scheduled
1053 to be used on Friday, the weekend, and Monday), you can add the {\bf
1054 days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs
1055 scheduled today only. If you have multiple run statements, the first
1056 occurrence of each run statement for the job will be displayed for the
1059 If your job seems to be blocked, you can get a general idea of the
1060 problem by doing a {\bf status dir}, but you can most often get a
1061 much more specific indication of the problem by doing a
1062 {\bf status storage=xxx}. For example, on an idle test system, when
1063 I do {\bf status storage=File}, I get:
1067 Connecting to Storage daemon File at 192.168.68.112:8103
1069 rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
1070 Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
1076 Jobs waiting to reserve a drive:
1080 JobId Level Files Bytes Status Finished Name
1081 ======================================================================
1082 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
1086 utochanger "DDS-4-changer" with devices:
1088 Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
1090 Slot 2 is loaded in drive 0.
1091 Total Bytes Read=0 Blocks Read=0 Bytes/block=0
1092 Positioned at File=0 Block=0
1093 Device "Dummy" is not open or does not exist.
1094 No DEVICE structure.
1096 Device "DVD-Writer" (/dev/hdc) is not open.
1097 Device "File" (/tmp) is not open.
1100 In Use Volume status:
1105 Now, what this tells me is that no jobs are running and that none of
1106 the devices are in use. Now, if I {\bf unmount} the autochanger, which
1107 will not be used in this example, and then start a Job that uses the
1108 File device, the job will block. When I re-issue the status storage
1109 command, I get for the Device status:
1116 Autochanger "DDS-4-changer" with devices:
1118 Device "DDS-4" (/dev/nst0) is not open.
1119 Device is BLOCKED. User unmounted.
1120 Drive 0 is not loaded.
1121 Device "Dummy" is not open or does not exist.
1122 No DEVICE structure.
1124 Device "DVD-Writer" (/dev/hdc) is not open.
1125 Device "File" (/tmp) is not open.
1126 Device is BLOCKED waiting for media.
1132 Now, here it should be clear that if a job were running that wanted
1133 to use the Autochanger (with two devices), it would block because
1134 the user unmounted the device. The real problem for the Job I started
1135 using the "File" device is that the device is blocked waiting for
1136 media -- that is Bacula needs you to label a Volume.
1139 \index[console]{unmount}
1140 This command causes the indicated Bacula Storage daemon to unmount the
1141 specified device. The forms of the command are the same as the mount command:
1144 unmount storage=<storage-name>
1146 unmount [ jobid=<id> | job=<job-name> ]
1150 \label{UpdateCommand}
1152 \index[console]{update}
1153 This command will update the catalog for either a specific Pool record, a Volume
1154 record, or the Slots in an autochanger with barcode capability. In the case
1155 of updating a Pool record, the new information will be automatically taken
1156 from the corresponding Director's configuration resource record. It can be
1157 used to increase the maximum number of volumes permitted or to set a maximum
1158 number of volumes. The following main keywords may be specified:
1161 media, volume, pool, slots
1165 In the case of updating a Volume, you will be prompted for which value you
1166 wish to change. The following Volume parameters may be changed:
1172 Volume Retention Period
1175 Maximum Volume Files
1176 Maximum Volume Bytes
1183 All Volumes from Pool
1188 For slots {\bf update slots}, Bacula will obtain a list of slots and
1189 their barcodes from the Storage daemon, and for each barcode found, it
1190 will automatically update the slot in the catalog Media record to
1191 correspond to the new value. This is very useful if you have moved
1192 cassettes in the magazine, or if you have removed the magazine and
1193 inserted a different one. As the slot of each Volume is updated, the
1194 InChanger flag for that Volume will also be set, and any other Volumes
1195 in the Pool that were last mounted on the same Storage device
1196 will have their InChanger flag turned off. This permits
1197 Bacula to know what magazine (tape holder) is currently in the
1200 If you do not have barcodes, you can accomplish the same thing in
1201 version 1.33 and later by using the {\bf update slots scan} command.
1202 The {\bf scan} keyword tells Bacula to physically mount each tape and to
1203 read its VolumeName.
1205 For Pool {\bf update pool}, Bacula will move the Volume record from its
1206 existing pool to the pool specified.
1208 For {\bf Volume from Pool} and {\bf All Volumes from Pool}, the
1209 following values are updated from the Pool record: Recycle,
1210 VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, and MaxVolBytes.
1212 The full form of the update command with all command line arguments is:
1216 update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
1217 VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
1224 \index[console]{use}
1225 This command allows you to specify which Catalog database to use. Normally,
1226 you will be using only one database so this will be done automatically. In
1227 the case that you are using more than one database, you can use this command
1228 to switch from one to another.
1230 use \lt{}database-name\gt{}
1234 \index[console]{var name}
1235 This command takes a string or quoted string and does variable expansion on
1236 it the same way variable expansion is done on the {\bf LabelFormat} string.
1237 Thus, for the most part, you can test your LabelFormat strings. The
1238 difference between the {\bf var} command and the actual LabelFormat process
1239 is that during the var command, no job is running so "dummy" values are
1240 used in place of Job specific variables. Generally, however, you will get a
1241 good idea of what is going to happen in the real case.
1244 \index[console]{version}
1245 The command prints the Director's version.
1248 \index[console]{quit}
1249 This command terminates the console program. The console program sends the
1250 {\bf quit} request to the Director and waits for acknowledgment. If the
1251 Director is busy doing a previous command for you that has not terminated, it
1252 may take some time. You may quit immediately by issuing the {\bf .quit}
1253 command (i.e. quit preceded by a period).
1256 \index[console]{query}
1257 This command reads a predefined SQL query from the query file (the name and
1258 location of the query file is defined with the QueryFile resource record in
1259 the Director's configuration file). You are prompted to select a query from
1260 the file, and possibly enter one or more parameters, then the command is
1261 submitted to the Catalog database SQL engine.
1263 The following queries are currently available (version 1.24):
1269 2: List where a file is saved:
1270 3: List where the most recent copies of a file are saved:
1271 4: List total files/bytes by Job:
1272 5: List total files/bytes by Volume:
1273 6: List last 20 Full Backups for a Client:
1274 7: List Volumes used by selected JobId:
1275 8: List Volumes to Restore All Files:
1276 9: List where a File is saved:
1277 Choose a query (1-9):
1283 \index[console]{exit}
1284 This command terminates the console program.
1287 \index[console]{wait}
1288 The wait command causes the Director to pause until there are no jobs
1289 running. This command is useful in a batch situation such as regression
1290 testing where you wish to start a job and wait until that job completes
1291 before continuing. This command now has the following options:
1294 wait [jobid=nn] [jobuid=unique id] [job=job name]
1297 If specified with a specific JobId, ... the wait command will wait
1298 for that particular job to terminate before continuing.
1303 \subsection*{Special dot Commands}
1304 \index[general]{Commands!Special dot}
1305 \index[general]{Special dot Commands}
1306 \addcontentsline{toc}{subsection}{Special dot Commands}
1308 There is a list of commands that are prefixed with a period (.). These
1309 commands are intended to be used either by batch programs or graphical user
1310 interface front-ends. They are not normally used by interactive users. Once
1311 GUI development begins, this list will be considerably expanded. The following
1312 is the list of dot commands:
1316 .backups job=xxx list backups for specified job
1317 .clients list all client names
1318 .defaults client=xxx fileset=yyy list defaults for specified client
1319 .die cause the Director to segment fault (for debugging)
1320 .dir when in tree mode prints the equivalent to the dir command,
1321 but with fields separated by commas rather than spaces.
1323 .filesets list all fileset names
1324 .help help command output
1325 .jobs list all job names
1326 .levels list all levels
1327 .messages get quick messages
1328 .msgs return any queued messages
1329 .pools list all pool names
1331 .status get status output
1332 .storage return storage resource names
1333 .types list job types
1339 \subsection*{Special At (@) Commands}
1340 \index[general]{Commands!Special At @}
1341 \index[general]{Special At (@) Commands}
1342 \addcontentsline{toc}{subsection}{Special At (@) Commands}
1344 Normally, all commands entered to the Console program are immediately
1345 forwarded to the Director, which may be on another machine, to be executed.
1346 However, there is a small list of {\bf at} commands, all beginning with an at
1347 character (@), that will not be sent to the Director, but rather interpreted
1348 by the Console program directly. Note, these commands are implemented only in
1349 the tty console program and not in the GNOME Console. These commands are:
1353 \item [@input \lt{}filename\gt{}]
1354 \index[console]{@input \lt{}filename\gt{}}
1355 Read and execute the commands contained in the file specified.
1357 \item [@output \lt{}filename\gt{} w/a]
1358 \index[console]{@output \lt{}filename\gt{} w/a}
1359 Send all following output to the filename specified either overwriting the
1360 file (w) or appending to the file (a). To redirect the output to the
1361 terminal, simply enter {\bf @output} without a filename specification.
1362 WARNING: be careful not to overwrite a valid file. A typical example during a
1363 regression test might be:
1374 \item [@tee \lt{}filename\gt{} w/a]
1375 \index[console]{@tee \lt{}filename\gt{} w/a}
1376 Send all subsequent output to both the specified file and the terminal. It is
1377 turned off by specifying {\bf @tee} or {\bf @output} without a filename.
1379 \item [@sleep \lt{}seconds\gt{}]
1380 \index[console]{@sleep \lt{}seconds\gt{}}
1381 Sleep the specified number of seconds.
1384 \index[console]{@time}
1385 Print the current time and date.
1388 \index[console]{@version}
1389 Print the console's version.
1392 \index[console]{@quit}
1396 \index[console]{@exit}
1399 \item [@\# anything]
1400 \index[console]{anything}
1406 \subsection*{Running the Console Program from a Shell Script}
1407 \index[general]{Script!Running the Console Program from a Shell}
1408 \index[general]{Running the Console Program from a Shell Script}
1409 \addcontentsline{toc}{subsection}{Running the Console Program from a Shell
1412 You can automate many Console tasks by running the console program from a
1413 shell script. For example, if you have created a file containing the following
1418 ./bconsole -c ./bconsole.conf <<END_OF_DATA
1419 unmount storage=DDS-4
1425 when that file is executed, it will unmount the current DDS-4 storage device.
1426 You might want to run this command during a Job by using the {\bf
1427 RunBeforeJob} or {\bf RunAfterJob} records.
1429 It is also possible to run the Console program from file input where the file
1430 contains the commands as follows:
1434 ./bconsole -c ./bconsole.conf <filename
1438 where the file named {\bf filename} contains any set of console commands.
1440 As a real example, the following script is part of the Bacula regression
1441 tests. It labels a volume (a disk volume), runs a backup, then does a restore
1446 bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
1449 @output /tmp/log1.out
1450 label volume=TestVolume001
1457 @output /tmp/log2.out
1468 The output from the backup is directed to /tmp/log1.out and the output from
1469 the restore is directed to /tmp/log2.out. To ensure that the backup and
1470 restore ran correctly, the output files are checked with:
1474 grep "^Termination: *Backup OK" /tmp/log1.out
1476 grep "^Termination: *Restore OK" /tmp/log2.out
1481 \subsection*{Adding Volumes to a Pool}
1482 \index[general]{Adding Volumes to a Pool}
1483 \index[general]{Pool!Adding Volumes to a}
1484 \addcontentsline{toc}{subsection}{Adding Volumes to a Pool}
1486 If you have used the {\bf label} command to label a Volume, it will be
1487 automatically added to the Pool, and you will not need to add any media to the
1490 Alternatively, you may choose to add a number of Volumes to the pool without
1491 labeling them. At a later time when the Volume is requested by {\bf Bacula}
1492 you will need to label it.
1494 Before adding a volume, you must know the following information:
1497 \item The name of the Pool (normally "Default")
1498 \item The Media Type as specified in the Storage Resource in the Director's
1499 configuration file (e.g. "DLT8000")
1500 \item The number and names of the Volumes you wish to create.
1503 For example, to add media to a Pool, you would issue the following commands to
1504 the console program:
1509 Enter name of Pool to add Volumes to: Default
1510 Enter the Media Type: DLT8000
1511 Enter number of Media volumes to create. Max=1000: 10
1512 Enter base volume name: Save
1513 Enter the starting number: 1
1514 10 Volumes created in pool Default
1519 To see what you have added, enter:
1523 *list media pool=Default
1524 +-------+----------+---------+---------+-------+------------------+
1525 | MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
1526 +-------+----------+---------+---------+-------+------------------+
1527 | 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1528 | 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1529 | 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1530 | 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1531 | 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1532 | 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1533 | 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1534 | 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1535 | 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1536 | 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1537 +-------+----------+---------+---------+-------+------------------+
1542 Notice that the console program automatically appended a number to the base
1543 Volume name that you specify (Save in this case). If you don't want it to
1544 append a number, you can simply answer 0 (zero) to the question "Enter number
1545 of Media volumes to create. Max=1000:", and in this case, it will create a
1546 single Volume with the exact name you specify.