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 After launching the Console program (bconsole), it will prompt you for the
63 next command with an asterisk (*). (Note, in the GNOME version, the prompt is
64 not present; you simply enter the commands you want in the command text box at
65 the bottom of the screen.) Generally, for all commands, you can simply enter
66 the command name and the Console program will prompt you for the necessary
67 arguments. Alternatively, in most cases, you may enter the command followed by
68 arguments. The general format is:
72 <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
76 where {\bf command} is one of the commands listed below; {\bf keyword} is one
77 of the keywords listed below (usually followed by an argument); and {\bf
78 argument} is the value. The command may be abbreviated to the shortest unique
79 form. If two commands have the same starting letters, the one that will be
80 selected is the one that appears first in the {\bf help} listing. If you want
81 the second command, simply spell out the full command. None of the keywords
82 following the command may be abbreviated.
92 will list all files saved for JobId 23. Or:
100 will display all the Pool resource records.
102 \subsection*{Stopping the Console Program}
103 \index[general]{Program!Stopping the Console }
104 \index[general]{Stopping the Console Program }
105 \index[console]{Program!Stopping the Console }
106 \index[console]{Stopping the Console Program }
107 \addcontentsline{toc}{subsection}{Stopping the Console Program}
109 Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
110 will terminate. However, it waits until the Director acknowledges the command.
111 If the Director is already doing a lengthy command (e.g. prune), it may take
112 some time. If you want to immediately terminate the Console program, enter the
115 There is currently no way to interrupt a Console command once issued (i.e.
116 Ctrl-C does not work). However, if you are at a prompt that is asking you to
117 select one of several possibilities and you would like to abort the command,
118 you can enter a period ({\bf .}), and in most cases, you will either be
119 returned to the main command prompt or if appropriate the previous prompt (in
120 the case of nested prompts). In a few places such as where it is asking for a
121 Volume name, the period will be taken to be the Volume name. In that case, you
122 will most likely be able to cancel at the next prompt.
125 \subsection*{Alphabetic List of Console Commands}
126 \index[general]{Commands!Alphabetic List of Console }
127 \index[general]{Alphabetic List of Console Commands }
128 \index[console]{Commands!Alphabetic List of Console }
129 \index[console]{Alphabetic List of Console Commands }
130 \addcontentsline{toc}{subsection}{Alphabetic List of Console Commands}
132 The following commands are currently implemented:
135 \item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
136 jobid=\lt{}JobId\gt{}]} ]
138 This command is used to add Volumes to an existing Pool. The Volume names
139 entered are placed in the Catalog and thus become available for backup
140 operations. Normally, the {\bf label} command is used rather than this
141 command because the {\bf label} command labels the physical media (tape) and
142 does the equivalent of the {\bf add} command. This command affects only the
143 Catalog and not the physical media (data on Volumes). The physical media must
144 exist and be labeled before use (usually with the {\bf label} command). This
145 command can, however, be useful if you wish to add a number of Volumes to the
146 Pool that will be physically labeled at a later time. It can also be useful
147 if you are importing a tape from another site. Please see the {\bf label}
148 command below for the list of legal characters in a Volume name.
150 \item [autodisplay on/off]
151 \index[console]{autodisplay on/off}
152 This command accepts {\bf on} or {\bf off} as an argument, and turns
153 auto-display of messages on or off respectively. The default for the
154 console program is {\bf off}, which means that you will be notified when
155 there are console messages pending, but they will not automatically be
156 displayed. The default for the gnome-console program is {\bf on}, which
157 means that messages will be displayed when they are received (usually
158 within 5 seconds of them being generated).
160 When autodisplay is turned off, you must explicitly retrieve the
161 messages with the {\bf messages} command. When autodisplay is turned
162 on, the messages will be displayed on the console as they are received.
164 \item [automount on/off]
165 \index[console]{automount on/off}
166 This command accepts {\bf on} or {\bf off} as the argument, and turns
167 auto-mounting of the tape after a {\bf label} command on or off
168 respectively. The default is {\bf on}. If {\bf automount} is turned
169 off, you must explicitly {\bf mount} the tape after a label command to
172 \item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{}]}]
173 \index[console]{cancel jobid}
174 This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
175 job=xxx} as an argument where nnn is replaced by the JobId and xxx is
176 replaced by the job name. If you do not specify a keyword, the Console
177 program will prompt you with the names of all the active jobs allowing
180 Once a Job is marked to be canceled, it may take a bit of time
181 (generally within a minute) before it actually terminates, depending on
182 what operations it is doing.
184 \item [{ create [pool=\lt{}pool-name\gt{}]}]
185 \index[console]{create pool}
186 This command is used to create a Pool record in the database using the
187 Pool resource record defined in the Director's configuration file. So
188 in a sense, this command simply transfers the information from the Pool
189 resource in the configuration file into the Catalog. Normally this
190 command is done automatically for you when the Director starts providing
191 the Pool is referenced within a Job resource. If you use this command
192 on an existing Pool, it will automatically update the Catalog to have
193 the same information as the Pool resource. After creating a Pool, you
194 will most likely use the {\bf label} command to label one or more
195 volumes and add their names to the Media database.
197 When starting a Job, if Bacula determines that there is no Pool record
198 in the database, but there is a Pool resource of the appropriate name,
199 it will create it for you. If you want the Pool record to appear in the
200 database immediately, simply use this command to force it to be created.
202 \item [{ delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
203 jobid=\lt{}id\gt{}] }]
204 \index[console]{delete}
205 The delete command is used to delete a Volume, Pool or Job record from
206 the Catalog as well as all associated catalog Volume records that were
207 created. This command operates only on the Catalog database and has no
208 effect on the actual data written to a Volume. This command can be
209 dangerous and we strongly recommend that you do not use it unless you
210 know what you are doing.
212 If the keyword {\bf Volume} appears on the command line, the named
213 Volume will be deleted from the catalog, if the keyword {\bf Pool}
214 appears on the command line, a Pool will be deleted, and if the keyword
215 {\bf Job} appears on the command line, a Job and all its associated
216 records (File and JobMedia) will be deleted from the catalog. The full
217 form of this command is:
219 delete pool=\lt{}pool-name\gt{}
223 delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{} or
225 delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ... or
227 delete Job JobId=n,m,o-r,t ...
229 The first form deletes a Pool record from the catalog database. The
230 second form deletes a Volume record from the specified pool in the
231 catalog database. The third form deletes the specified Job record from
232 the catalog database. The last form deletes JobId records for JobIds
233 n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
234 number. That is a "delete jobid" accepts lists and ranges of
239 \index[console]{estimate}
240 Using this command, you can get an idea how many files will be backed
241 up, or if you are unsure about your Include statements in your FileSet,
242 you can test them without doing an actual backup. The default is to
243 assume a Full backup. However, you can override this by specifying a
244 {\bf level=Incremental} or {\bf level=Differential} on the command line.
245 A Job name must be specified or you will be prompted for one, and
246 optionally a Client and FileSet may be specified on the command line.
247 It then contacts the client which computes the number of files and bytes
248 that would be backed up. Please note that this is an estimate
249 calculated from the number of blocks in the file rather than by reading
250 the actual bytes. As such, the estimated backup size will generally be
251 larger than an actual backup.
253 Optionally you may specify the keyword {\bf listing} in which case, all the
254 files to be backed up will be listed. Note, it could take quite some time to
255 display them if the backup is large. The full form is:
257 estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{}
258 fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{}
260 Specification of the {\bf job} is sufficient, but you can also override
261 the client, fileset and/or level by specifying them on the estimate
265 As an example, you might do:
270 estimate job=NightlySave listing level=Incremental
275 which will do a full listing of all files to be backed up for the Job {\bf
276 NightlySave} during an Incremental save and put it in the file {\bf
280 \index[console]{help}
281 This command displays the list of commands available.
284 \index[console]{label}
285 \index[console]{relabel}
286 \index[general]{label}
287 \index[general]{relabel}
288 This command is used to label physical volumes. The full form of this command
291 label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{}
294 If you leave out any part, you will be prompted for it. The media type
295 is automatically taken from the Storage resource definition that you
296 supply. Once the necessary information is obtained, the Console program
297 contacts the specified Storage daemon and requests that the tape be
298 labeled. If the tape labeling is successful, the Console program will
299 create a Volume record in the appropriate Pool.
301 The Volume name is restricted to letters, numbers, and the special
302 characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
303 period ({\bf .}). All other characters including a space are illegal.
304 This restriction is to ensure good readability of Volume names to reduce
307 Please note, when labeling a blank tape, Bacula will get {\bf read I/O
308 error} when it attempts to ensure that the tape is already labeled. If
309 you wish to avoid getting these messages, please write and EOF mark on
310 your tape before attempting to label it:
320 The label command can fail for a number of reasons:
323 \item The Volume name you specify is already in the Volume database.
324 \item The Storage daemon has a tape already mounted on the device, in which
325 case you must {\bf unmount} the device, insert a blank tape, then do the
327 \item The tape in the device is already a Bacula labeled tape. (Bacula will
328 never relabel a Bacula labeled tape unless it is recycled and you use the
329 {\bf relabel} command).
330 \item There is no tape in the drive.
333 There are two ways to relabel a volume that already has a Bacula label. The
334 brute force method is to write an end of file mark on the tape using the
335 system {\bf mt} program, something like the following:
339 mt -f /dev/st0 rewind
344 Then you use the {\bf label} command to add a new label. However, this could
345 leave traces of the old volume in the catalog.
347 The preferable method to relabel a tape is to first {\bf purge} the volume,
348 either automatically, or explicitly with the {\bf purge} command, then use
349 the {\bf relabel} command described below.
351 If your autochanger has barcode labels, you can label all the Volumes in your
352 autochanger one after another by using the {\bf label barcodes} command. For
353 each tape in the changer containing a barcode, Bacula will mount the tape and
354 then label it with the same name as the barcode. An appropriate Media record
355 will also be created in the catalog. Any barcode that begins with the same
356 characters as specified on the "CleaningPrefix=xxx" directive in the
357 Director's Pool resource, will be
358 treated as a cleaning tape, and will not be labeled. However,
359 an entry for the cleaning tape will be created in
360 the catalog. For example with:
366 Cleaning Prefix = "CLN"
372 Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
373 and will not be mounted. Note, the full form of the command is:
377 update storage=xxx pool=yyy slots=1-5,10 barcodes
382 \index[console]{list}
383 The list command lists the requested contents of the Catalog. The
384 various fields of each record are listed on a single line. The various
385 forms of the list command are:
390 list jobid=\lt{}id\gt{}
392 list job=\lt{}job-name\gt{}
396 list jobmedia jobid=\lt{}id\gt{}
398 list jobmedia job=\lt{}job-name\gt{}
400 list files jobid=\lt{}id\gt{}
402 list files job=\lt{}job-name\gt{}
412 list volumes jobid=\lt{}id\gt{}
414 list volumes pool=\lt{}pool-name\gt{}
416 list volumes job=\lt{}job-name\gt{}
418 list volume=\lt{}volume-name\gt{}
420 list nextvolume job=\lt{}job-name\gt{}
422 list nextvol job=\lt{}job-name\gt{}
424 list nextvol job=\lt{}job-name\gt{} days=nnn
431 What most of the above commands do should be more or less obvious. In
432 general if you do not specify all the command line arguments, the
433 command will prompt you for what is needed.
435 The {\bf list nextvol} command will print the Volume name to be used by
436 the specified job. You should be aware that exactly what Volume will be
437 used depends on a lot of factors including the time and what a prior job
438 will do. It may fill a tape that is not full when you issue this
439 command. As a consequence, this command will give you a good estimate
440 of what Volume will be used but not a definitive answer. In addition,
441 this command may have certain side effect because it runs through the
442 same algorithm as a job, which means it may automatically purge or
443 recycle a Volume. By default, the job specified must run within the
444 next two days or no volume will be found. You can, however, use the
445 {\bf days=nnn} specification to specify up to 50 days. For example,
446 if on Friday, you want to see what Volume will be needed on Monday,
447 for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
449 If you wish to add specialized commands that list the contents of the
450 catalog, you can do so by adding them to the {\bf query.sql} file.
451 However, this takes some knowledge of programming SQL. Please see the
452 {\bf query} command below for additional information. See below for
453 listing the full contents of a catalog record with the {\bf llist}
456 As an example, the command {\bf list pools} might produce the following
461 +------+---------+---------+---------+----------+-------------+
462 | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
463 +------+---------+---------+---------+----------+-------------+
464 | 1 | Default | 0 | 0 | Backup | * |
465 | 2 | Recycle | 0 | 8 | Backup | File |
466 +------+---------+---------+---------+----------+-------------+
470 As mentioned above, the {\bf list} command lists what is in the
471 database. Some things are put into the database immediately when Bacula
472 starts up, but in general, most things are put in only when they are
473 first used, which is the case for a Client as with Job records, etc.
475 Bacula should create a client record in the database the first time you
476 run a job for that client. Doing a {\bf status} will not cause a
477 database record to be created. The client database record will be
478 created whether or not the job fails, but it must at least start. When
479 the Client is actually contacted, additional info from the client will
480 be added to the client record (a "uname -a" output).
482 If you want to see what Client resources you have available in your conf
483 file, you use the Console command {\bf show clients}.
486 \index[console]{llist}
487 The llist or "long list" command takes all the same arguments that the
488 list command described above does. The difference is that the llist
489 command list the full contents of each database record selected. It
490 does so by listing the various fields of the record vertically, with one
491 field per line. It is possible to produce a very large number of output
492 lines with this command.
494 If instead of the {\bf list pools} as in the example above, you enter
495 {\bf llist pools} you might get the following output:
506 VolRetention: 1,296,000
507 VolUseDuration: 86,400
522 VolUseDuration: 3,600
534 \index[console]{messages}
535 This command causes any pending console messages to be immediately displayed.
539 \index[console]{mount}
540 The mount command is used to get Bacula to read a volume on a physical
541 device. It is a way to tell Bacula that you have mounted a tape and
542 that Bacula should examine the tape. This command is used only after
543 there was no Volume in a drive and Bacula requests you to mount a new
544 Volume or when you have specifically unmounted a Volume with the {\bf
545 unmount} console command, which causes Bacula to close the drive. If
546 you have an autoloader, the mount command will not cause Bacula to
547 operate the autoloader. The various forms of the mount command are:
549 mount storage=\lt{}storage-name\gt{}
551 mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
553 If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
554 Device resource, under most circumstances, Bacula will automatically access
555 the Volume unless you have explicitly {\bf unmount}ed it in the Console
559 \index[console]{python}
560 The python command takes a single argument {\bf restart}:
564 This causes the Python interpreter in the Director to be reinitialized.
565 This can be helpful for testing because once the Director starts and the
566 Python interpreter is initialized, there is no other way to make it
567 accept any changes to the startup script {\bf DirStartUp.py}. For more
568 details on Python scripting, please see the \ilink{Python
569 Scripting}{_ChapterStart60} chapter of this manual.
571 \label{ManualPruning}
573 \index[console]{prune}
574 The Prune command allows you to safely remove expired database records
575 from Jobs and Volumes. This command works only on the Catalog database
576 and does not affect data written to Volumes. In all cases, the Prune
577 command applies a retention period to the specified records. You can
578 Prune expired File entries from Job records; you can Prune expired Job
579 records from the database, and you can Prune both expired Job and File
580 records from specified Volumes.
582 prune files|jobs|volume client=\lt{}client-name\gt{}
583 volume=\lt{}volume-name\gt{}
585 For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
586 Append, otherwise the pruning will not take place.
589 \index[console]{purge}
590 The Purge command will delete associated Catalog database records from
591 Jobs and Volumes without considering the retention period. {\bf Purge}
592 works only on the Catalog database and does not affect data written to
593 Volumes. This command can be dangerous because you can delete catalog
594 records associated with current backups of files, and we recommend that
595 you do not use it unless you know what you are doing. The permitted
596 forms of {\bf purge} are:
598 purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
600 purge jobs client=\lt{}client-name\gt{} (of all jobs)
602 purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
604 For the {\bf purge} command to work on Volume Catalog database records the
605 {\bf VolStatus} must be Append, Full, Used, or Error.
607 The actual data written to the Volume will be unaffected by this command.
610 \index[console]{relabel}
611 \index[general]{relabel}
612 This command is used to label physical volumes. The full form of this
615 relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
616 volume=\lt{}newvolume-name\gt{}
618 If you leave out any part, you will be prompted for it. In order for
619 the Volume (old-volume-name) to be relabeled, it must be in the catalog,
620 and the volume status must be marked {\bf Purged} or {\bf Recycle}.
621 This happens automatically as a result of applying retention periods, or
622 you may explicitly purge the volume using the {\bf purge} command.
624 Once the volume is physically relabeled, the old data previously written
625 on the Volume is lost and cannot be recovered.
628 \index[console]{release}
629 This command is used to cause the Storage daemon to rewind (release) the
630 current tape in the drive, and to re-read the Volume label the next time
633 release storage=\lt{}storage-name\gt{}
635 After a release command, the device is still kept open by Bacula (unless
636 Always Open is set to No in the Storage Daemon's configuration) so it
637 cannot be used by another program. However, with some tape drives, the
638 operator can remove the current tape and to insert a different one, and
639 when the next Job starts, Bacula will know to re-read the tape label to
640 find out what tape is mounted. If you want to be able to use the drive
641 with another program (e.g. {\bf mt}), you must use the {\bf unmount}
642 command to cause Bacula to completely release (close) the device.
645 \index[console]{reload}
646 The reload command causes the Director to re-read its configuration
647 file and apply the new values. The new values will take effect
648 immediately for all new jobs. However, if you change schedules,
649 be aware that the scheduler pre-schedules jobs up to two hours in
650 advance, so any changes that are to take place during the next two
651 hours may be delayed. Jobs that have already been scheduled to run
652 (i.e. surpassed their requested start time) will continue with the
653 old values. New jobs will use the new values. Each time you issue
654 a reload command while jobs are running, the prior config values
655 will queued until all jobs that were running before issuing
656 the reload terminate, at which time the old config values will
657 be released from memory. The Directory permits keeping up to
658 10 prior set of configurations before it will refuse a reload
659 command. Once at least one old set of config values has been
660 released it will again accept new reload commands.
662 While it is possible to reload the Director's configuration on the fly,
663 even while jobs are executing, this is a complex operation and not
664 without side effects. Accordingly, if you have to reload the Director's
665 configuration while Bacula is running, it is advisable to restart the
666 Director at the next convenient opportunity.
668 \label{restore_command}
670 \index[console]{restore}
671 The restore command allows you to select one or more Jobs (JobIds) to be
672 restored using various methods. Once the JobIds are selected, the File
673 records for those Jobs are placed in an internal Bacula directory tree,
674 and the restore enters a file selection mode that allows you to
675 interactively walk up and down the file tree selecting individual files
676 to be restored. This mode is somewhat similar to the standard Unix {\bf
677 restore} program's interactive file selection mode.
679 restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{}
680 where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
681 select current all done
683 Where {\bf current}, if specified, tells the restore command to
684 automatically select a restore to the most current backup. If not
685 specified, you will be prompted. The {\bf all} specification tells the
686 restore command to restore all files. If it is not specified, you will
687 be prompted for the files to restore. For details of the {\bf restore}
688 command, please see the \ilink{Restore Chapter}{_ChapterStart13} of this
693 This command allows you to schedule jobs to be run immediately. The full form
696 run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
697 fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
698 storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
699 when=\lt{}universal-time-specification\gt{} yes
701 Any information that is needed but not specified will be listed for
702 selection, and before starting the job, you will be prompted to accept,
703 reject, or modify the parameters of the job to be run, unless you have
704 specified {\bf yes}, in which case the job will be immediately sent to
707 On my system, when I enter a run command, I get the following prompt:
711 A job name must be specified.
712 The defined Job resources are:
722 Select Job resource (1-9):
727 If I then select number 5, I am prompted with:
733 FileSet: Minou Full Set
738 When: 2003-04-23 17:08:18
739 OK to run? (yes/mod/no):
744 If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
745 be presented with the following prompt.
749 Parameters to modify:
757 Select parameter to modify (1-7):
762 If you wish to start a job at a later time, you can do so by setting the When
763 time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
764 desired start time in YYYY-MM-DD HH:MM:SS format.
767 \index[dir]{setdebug}
768 This command is used to set the debug level in each daemon. The form of this
771 setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
772 storage=\lt{}storage-name\gt{} | all]
774 If trace=1 is set, then the tracing will be enabled, and the daemon
775 where the setdebug applies will be placed in trace mode, and all debug
776 output will go to the file {\bf bacula.trace} in the current directory
777 of the daemon. Normally, tracing is used only for Win32 clients where
778 the debug output cannot be written to a terminal or redirected to a
779 file. When tracing, each debug output message is appended to the trace
780 file. You must explicitly delete the file when you are done.
783 \index[console]{show}
784 The show command will list the Director's resource records as defined in
785 the Director's configuration file (normally {\bf bacula-dir.conf}).
786 This command is used mainly for debugging purposes by developers. The
787 following keywords are accepted on the show command line: directors,
788 clients, counters, jobs, storages, catalogs, schedules, filesets,
789 groups, pools, messages, all, help. Please don't confuse this command
790 with the {\bf list}, which displays the contents of the catalog.
793 \index[dir]{sqlquery}
794 The sqlquery command puts the Console program into SQL query mode where
795 each line you enter is concatenated to the previous line until a
796 semicolon (;) is seen. The semicolon terminates the command, which is
797 then passed directly to the SQL database engine. When the output from
798 the SQL engine is displayed, the formation of a new SQL command begins.
799 To terminate SQL query mode and return to the Console command prompt,
800 you enter a period (.) in column 1.
802 Using this command, you can query the SQL catalog database directly.
803 Note you should really know what you are doing otherwise you could
804 damage the catalog database. See the {\bf query} command below for
805 simpler and safer way of entering SQL queries.
807 Depending on what database engine you are using (MySQL, PostgreSQL or
808 SQLite), you will have somewhat different SQL commands available. For
809 more detailed information, please refer to the MySQL, PostgreSQL or
810 SQLite documentation.
814 This command will display the status of the next jobs that are scheduled
815 during the next twenty-four hours as well as the status of currently
816 running jobs. The full form of this command is:
818 status [all | dir=\lt{}dir-name\gt{} | director |
819 client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} |
822 If you do a {\bf status dir}, the console will list any currently
823 running jobs, a summary of all jobs scheduled to be run in the next 24
824 hours, and a listing of the last 10 terminated jobs with their statuses.
825 The scheduled jobs summary will include the Volume name to be used. You
826 should be aware of two things: 1. to obtain the volume name, the code
827 goes through the same code that will be used when the job runs, which
828 means that it may prune or recycle a Volume; 2. The Volume listed is
829 only a best guess. The Volume actually used may be different because of
830 the time difference (more durations may expire when the job runs) and
831 another job could completely fill the Volume requiring a new one.
833 In the Running Jobs listing, you may find the following types of
839 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
840 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
841 priority jobs to finish
842 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
843 5343 Full Rufus.2004-03-13_01.05.04 is running
847 Looking at the above listing from bottom to top, obviously JobId 5343
848 (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
849 finish because it is using the Storage resource, hence the "waiting on
850 max Storage jobs". JobId 5349 has a lower priority than all the other
851 jobs so it is waiting for higher priority jobs to finish, and finally,
852 JobId 2508 (MatouVerify) is waiting because only one job can run at a
853 time, hence it is simply "waiting execution"
855 If you do a {\bf status dir}, it will by default list the first
856 occurrence of all jobs that are scheduled today and tomorrow. If you
857 wish to see the jobs that are scheduled in the next 3 days (e.g. on
858 Friday you want to see the first occurrence of what tapes are scheduled
859 to be used on Friday, the weekend, and Monday), you can add the {\bf
860 days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs
861 scheduled today only. If you have multiple run statements, the first
862 occurrence of each run statement for the job will be displayed for the
866 \index[console]{unmount}
867 This command causes the indicated Bacula Storage daemon to unmount the
868 specified device. The forms of the command are the same as the mount command:
871 unmount storage=\lt{}storage-name\gt{}
873 unmount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
877 \label{UpdateCommand}
879 \index[console]{update}
880 This command will update the catalog for either a specific Pool record, a Volume
881 record, or the Slots in an autochanger with barcode capability. In the case
882 of updating a Pool record, the new information will be automatically taken
883 from the corresponding Director's configuration resource record. It can be
884 used to increase the maximum number of volumes permitted or to set a maximum
885 number of volumes. The following main keywords may be specified:
888 media, volume, pool, slots
892 In the case of updating a Volume, you will be prompted for which value you
893 wish to change. The following Volume parameters may be changed:
899 Volume Retention Period
910 All Volumes from Pool
915 For slots {\bf update slots}, Bacula will obtain a list of slots and
916 their barcodes from the Storage daemon, and for each barcode found, it
917 will automatically update the slot in the catalog Media record to
918 correspond to the new value. This is very useful if you have moved
919 cassettes in the magazine, or if you have removed the magazine and
920 inserted a different one. As the slot of each Volume is updated, the
921 InChanger flag for that Volume will also be set, and any other Volumes
922 in the Pool that were last mounted on the same Storage device
923 will have their InChanger flag turned off. This permits
924 Bacula to know what magazine (tape holder) is currently in the
927 If you do not have barcodes, you can accomplish the same thing in
928 version 1.33 and later by using the {\bf update slots scan} command.
929 The {\bf scan} keyword tells Bacula to physically mount each tape and to
932 For Pool {\bf update pool}, Bacula will move the Volume record from its
933 existing pool to the pool specified.
935 For {\bf Volume from Pool} and {\bf All Volumes from Pool}, the
936 following values are updated from the Pool record: Recycle,
937 VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, and MaxVolBytes.
939 The full form of the update command with all command line arguments is:
943 update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
944 VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
951 \index[console]{use }
952 This command allows you to specify which Catalog database to use. Normally,
953 you will be using only one database so this will be done automatically. In
954 the case that you are using more than one database, you can use this command
955 to switch from one to another.
957 use \lt{}database-name\gt{}
961 \index[console]{var name }
962 This command takes a string or quoted string and does variable expansion on
963 it the same way variable expansion is done on the {\bf LabelFormat} string.
964 Thus, for the most part, you can test your LabelFormat strings. The
965 difference between the {\bf var} command and the actual LabelFormat process
966 is that during the var command, no job is running so "dummy" values are
967 used in place of Job specific variables. Generally, however, you will get a
968 good idea of what is going to happen in the real case.
971 \index[console]{version }
972 The command prints the Director's version.
975 \index[console]{quit }
976 This command terminates the console program. The console program sends the
977 {\bf quit} request to the Director and waits for acknowledgment. If the
978 Director is busy doing a previous command for you that has not terminated, it
979 may take some time. You may quit immediately by issuing the {\bf .quit}
980 command (i.e. quit preceded by a period).
983 \index[console]{query }
984 This command reads a predefined SQL query from the query file (the name and
985 location of the query file is defined with the QueryFile resource record in
986 the Director's configuration file). You are prompted to select a query from
987 the file, and possibly enter one or more parameters, then the command is
988 submitted to the Catalog database SQL engine.
990 The following queries are currently available (version 1.24):
996 2: List where a file is saved:
997 3: List where the most recent copies of a file are saved:
998 4: List total files/bytes by Job:
999 5: List total files/bytes by Volume:
1000 6: List last 20 Full Backups for a Client:
1001 7: List Volumes used by selected JobId:
1002 8: List Volumes to Restore All Files:
1003 9: List where a File is saved:
1004 Choose a query (1-9):
1010 \index[console]{exit }
1011 This command terminates the console program.
1014 \index[console]{wait }
1015 The wait command causes the Director to pause until there are no jobs
1016 running. This command is useful in a batch situation such as regression
1017 testing where you wish to start a job and wait until that job completes
1023 \subsection*{Special dot Commands}
1024 \index[general]{Commands!Special dot }
1025 \index[general]{Special dot Commands }
1026 \addcontentsline{toc}{subsection}{Special dot Commands}
1028 There is a list of commands that are prefixed with a period (.). These
1029 commands are intended to be used either by batch programs or graphical user
1030 interface front-ends. They are not normally used by interactive users. Once
1031 GUI development begins, this list will be considerably expanded. The following
1032 is the list of dot commands:
1036 .backups job=xxx list backups for specified job
1037 .defaults client=xxx fileset=yyy list defaults for specified client
1038 .die cause the Director to segment fault (for debugging)
1039 .dir when in tree mode prints the equivalent to the dir command,
1040 but with fields separated by commas rather than spaces.
1041 .jobs list all job names
1042 .levels list all levels
1043 .filesets list all fileset names
1044 .clients list all client names
1045 .pools list all pool names
1046 .types list job types
1047 .msgs return any queued messages
1048 .messages get quick messages
1049 .help help command output
1051 .status get status output
1058 \subsection*{Special At (@) Commands}
1059 \index[general]{Commands!Special At @ }
1060 \index[general]{Special At (@) Commands }
1061 \addcontentsline{toc}{subsection}{Special At (@) Commands}
1063 Normally, all commands entered to the Console program are immediately
1064 forwarded to the Director, which may be on another machine, to be executed.
1065 However, there is a small list of {\bf at} commands, all beginning with an at
1066 character (@), that will not be sent to the Director, but rather interpreted
1067 by the Console program directly. Note, these commands are implemented only in
1068 the tty console program and not in the GNOME Console. These commands are:
1072 \item [@input \lt{}filename\gt{}]
1073 \index[console]{@input \lt{}filename\gt{} }
1074 Read and execute the commands contained in the file specified.
1076 \item [@output \lt{}filename\gt{} w/a]
1077 \index[console]{@output \lt{}filename\gt{} w/a }
1078 Send all following output to the filename specified either overwriting the
1079 file (w) or appending to the file (a). To redirect the output to the
1080 terminal, simply enter {\bf @output} without a filename specification.
1081 WARNING: be careful not to overwrite a valid file. A typical example during a
1082 regression test might be:
1093 \item [@tee \lt{}filename\gt{} w/a]
1094 \index[console]{@tee \lt{}filename\gt{} w/a }
1095 Send all subsequent output to both the specified file and the terminal. It is
1096 turned off by specifying {\bf @tee} or {\bf @output} without a filename.
1098 \item [@sleep \lt{}seconds\gt{}]
1099 \index[console]{@sleep \lt{}seconds\gt{} }
1100 Sleep the specified number of seconds.
1103 \index[console]{@time }
1104 Print the current time and date.
1107 \index[console]{@version }
1108 Print the console's version.
1111 \index[console]{@quit }
1115 \index[console]{@exit }
1118 \item [@\# anything]
1119 \index[console]{anything }
1125 \subsection*{Running the Console Program from a Shell Script}
1126 \index[general]{Script!Running the Console Program from a Shell }
1127 \index[general]{Running the Console Program from a Shell Script }
1128 \addcontentsline{toc}{subsection}{Running the Console Program from a Shell
1131 You can automate many Console tasks by running the console program from a
1132 shell script. For example, if you have created a file containing the following
1137 ./bconsole -c ./bconsole.conf <<END_OF_DATA
1138 unmount storage=DDS-4
1144 when that file is executed, it will unmount the current DDS-4 storage device.
1145 You might want to run this command during a Job by using the {\bf
1146 RunBeforeJob} or {\bf RunAfterJob} records.
1148 It is also possible to run the Console program from file input where the file
1149 contains the commands as follows:
1153 ./bconsole -c ./bconsole.conf <filename
1157 where the file named {\bf filename} contains any set of console commands.
1159 As a real example, the following script is part of the Bacula regression
1160 tests. It labels a volume (a disk volume), runs a backup, then does a restore
1165 bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
1168 @output /tmp/log1.out
1169 label volume=TestVolume001
1176 @output /tmp/log2.out
1187 The output from the backup is directed to /tmp/log1.out and the output from
1188 the restore is directed to /tmp/log2.out. To ensure that the backup and
1189 restore ran correctly, the output files are checked with:
1193 grep "^Termination: *Backup OK" /tmp/log1.out
1195 grep "^Termination: *Restore OK" /tmp/log2.out
1200 \subsection*{Adding Volumes to a Pool}
1201 \index[general]{Adding Volumes to a Pool }
1202 \index[general]{Pool!Adding Volumes to a }
1203 \addcontentsline{toc}{subsection}{Adding Volumes to a Pool}
1205 If you have used the {\bf label} command to label a Volume, it will be
1206 automatically added to the Pool, and you will not need to add any media to the
1209 Alternatively, you may choose to add a number of Volumes to the pool without
1210 labeling them. At a later time when the Volume is requested by {\bf Bacula}
1211 you will need to label it.
1213 Before adding a volume, you must know the following information:
1216 \item The name of the Pool (normally "Default")
1217 \item The Media Type as specified in the Storage Resource in the Director's
1218 configuration file (e.g. "DLT8000")
1219 \item The number and names of the Volumes you wish to create.
1222 For example, to add media to a Pool, you would issue the following commands to
1223 the console program:
1228 Enter name of Pool to add Volumes to: Default
1229 Enter the Media Type: DLT8000
1230 Enter number of Media volumes to create. Max=1000: 10
1231 Enter base volume name: Save
1232 Enter the starting number: 1
1233 10 Volumes created in pool Default
1238 To see what you have added, enter:
1242 *list media pool=Default
1243 +-------+----------+---------+---------+-------+------------------+
1244 | MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
1245 +-------+----------+---------+---------+-------+------------------+
1246 | 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1247 | 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1248 | 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1249 | 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1250 | 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1251 | 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1252 | 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1253 | 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1254 | 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1255 | 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1256 +-------+----------+---------+---------+-------+------------------+
1261 Notice that the console program automatically appended a number to the base
1262 Volume name that you specify (Save in this case). If you don't want it to
1263 append a number, you can simply answer 0 (zero) to the question "Enter number
1264 of Media volumes to create. Max=1000:", and in this case, it will create a
1265 single Volume with the exact name you specify.