4 \section*{Bacula Console}
5 \label{_ConsoleChapter}
6 \index[general]{Console!Bacula }
7 \index[general]{Bacula Console }
8 \addcontentsline{toc}{section}{Bacula Console}
11 \index[general]{General }
12 \addcontentsline{toc}{subsection}{General}
14 The {\bf Bacula Console} (sometimes called the User Agent) is a program that
15 allows the user or the System Administrator, to interact with the Bacula
16 Director daemon while the daemon is running.
18 The current Bacula Console comes in two versions: a shell interface (TTY
19 style), and a GNOME GUI interface. Both permit the administrator or authorized
20 users to interact with Bacula. You can determine the status of a particular
21 job, examine the contents of the Catalog as well as perform certain tape
22 manipulations with the Console program.
24 In addition, there is a wx-console built with wxWidgets that allows a graphic
25 restore of files. As of version 1.34.1 it is in an early stage of development,
26 but it already is quite useful.
28 Since the Console program interacts with the Director through the network, your
29 Console and Director programs do not necessarily need to run on the same
32 In fact, a certain minimal knowledge of the Console program is needed in order
33 for Bacula to be able to write on more than one tape, because when Bacula
34 requests a new tape, it waits until the user, via the Console program,
35 indicates that the new tape is mounted.
37 \subsection*{Configuration}
38 \index[general]{Configuration }
39 \addcontentsline{toc}{subsection}{Configuration}
41 When the Console starts, it reads a standard Bacula configuration file named
42 {\bf bconsole.conf} or {\bf gnome-console.conf} in the case of the GNOME
43 Console version. This file allows default configuration of the Console, and at
44 the current time, the only Resource Record defined is the Director resource,
45 which gives the Console the name and address of the Director. For more
46 information on configuration of the Console program, please see the
47 \ilink{Console Configuration File}{_ChapterStart36} Chapter of
50 \subsection*{Running the Console Program}
51 \index[general]{Running the Console Program }
52 \index[general]{Program!Running the Console }
53 \addcontentsline{toc}{subsection}{Running the Console Program}
55 After launching the Console program (bconsole), it will prompt you for the
56 next command with an asterisk (*). (Note, in the GNOME version, the prompt is
57 not present; you simply enter the commands you want in the command text box at
58 the bottom of the screen.) Generally, for all commands, you can simply enter
59 the command name and the Console program will prompt you for the necessary
60 arguments. Alternatively, in most cases, you may enter the command followed by
61 arguments. The general format is:
65 <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
69 where {\bf command} is one of the commands listed below; {\bf keyword} is one
70 of the keywords listed below (usually followed by an argument); and {\bf
71 argument} is the value. The command may be abbreviated to the shortest unique
72 form. If two commands have the same starting letters, the one that will be
73 selected is the one that appears first in the {\bf help} listing. If you want
74 the second command, simply spell out the full command. None of the keywords
75 following the command may be abbreviated.
85 will list all files saved for JobId 23. Or:
93 will display all the Pool resource records.
95 \subsection*{Stopping the Console Program}
96 \index[general]{Program!Stopping the Console }
97 \index[general]{Stopping the Console Program }
98 \addcontentsline{toc}{subsection}{Stopping the Console Program}
100 Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
101 will terminate. However, it waits until the Director acknowledges the command.
102 If the Director is already doing a lengthy command (e.g. prune), it may take
103 some time. If you want to immediately terminate the Console program, enter the
106 There is currently no way to interrupt a Console command once issued (i.e.
107 Ctrl-C does not work). However, if you are at a prompt that is asking you to
108 select one of several possibilities and you would like to abort the command,
109 you can enter a period ({\bf .}), and in most cases, you will either be
110 returned to the main command prompt or if appropriate the previous prompt (in
111 the case of nested prompts). In a few places such as where it is asking for a
112 Volume name, the period will be taken to be the Volume name. In that case, you
113 will most likely be able to cancel at the next prompt.
116 \subsection*{Alphabetic List of Console Commands}
117 \index[general]{Commands!Alphabetic List of Console }
118 \index[general]{Alphabetic List of Console Commands }
119 \addcontentsline{toc}{subsection}{Alphabetic List of Console Commands}
121 The following commands are currently implemented:
124 \item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
125 jobid=\lt{}JobId\gt{}]} ]
126 \index[console]{add [pool }
127 This command is used to add Volumes to an existing Pool. The Volume names
128 entered are placed in the Catalog and thus become available for backup
129 operations. Normally, the {\bf label} command is used rather than this
130 command because the {\bf label} command labels the physical media (tape) and
131 does the equivalent of the {\bf add} command. This command affects only the
132 Catalog and not the physical media (data on Volumes). The physical media must
133 exist and be labeled before use (usually with the {\bf label} command). This
134 command can, however, be useful if you wish to add a number of Volumes to the
135 Pool that will be physically labeled at a later time. It can also be useful
136 if you are importing a tape from another site. Please see the {\bf label}
137 command below for the list of legal characters in a Volume name.
139 \item [autodisplay on/off]
140 \index[console]{autodisplay on/off }
141 This command accepts {\bf on} or {\bf off} as an argument, and turns
142 auto-display of messages on or off respectively. The default for the console
143 program is {\bf off}, which means that you will be notified when there are
144 console messages pending, but they will not automatically be displayed. The
145 default for the gnome-console program is {\bf on}, which means that messages
146 will be displayed when they are received (usually within 5 seconds of them
149 When autodisplay is turned off, you must explicitly retrieve the messages
150 with the {\bf messages} command. When autodisplay is turned on, the messages
151 will be displayed on the console as they are received.
153 \item [automount on/off]
154 \index[console]{automount on/off }
155 This command accepts {\bf on} or {\bf off} as the argument, and turns
156 auto-mounting of the tape after a {\bf label} command on or off respectively.
157 The default is {\bf on}. If {\bf automount} is turned off, you must
158 explicitly {\bf mount} the tape after a label command to use it.
160 \item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{}]}]
161 \index[console]{cancel [jobid }
162 This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
163 job=xxx} as an argument where nnn is replaced by the JobId and xxx is
164 replaced by the job name. If you do not specify a keyword, the Console
165 program will prompt you with the names of all the active jobs allowing you to
168 Once a Job is marked to be canceled, it may take a bit of time (generally
169 within a minute) before it actually terminates, depending on what operations
172 \item [{ create [pool=\lt{}pool-name\gt{}]}]
173 \index[console]{create [pool }
174 This command is used to create a Pool record in the database using the Pool
175 resource record defined in the Director's configuration file. So in a sense,
176 this command simply transfers the information from the Pool resource in the
177 configuration file into the Catalog. Normally this command is done
178 automatically for you when the Director starts providing the Pool is
179 referenced within a Job resource. If you use this command on an existing
180 Pool, it will automatically update the Catalog to have the same information
181 as the Pool resource. After creating a Pool, you will most likely use the
182 {\bf label} command to label one or more volumes and add their names to the
185 When starting a Job, if Bacula determines that there is no Pool record in the
186 database, but there is a Pool resource of the appropriate name, it will
187 create it for you. If you want the Pool record to appear in the database
188 immediately, simply use this command to force it to be created.
190 \item [{ delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
191 jobid=\lt{}id\gt{}] }]
192 \index[console]{delete }
193 The delete command is used to delete a Volume, Pool or Job record from the
194 Catalog as well as all associated Volume records that were created. This
195 command operates only on the Catalog database and has no effect on the actual
196 data written to a Volume. This command can be dangerous and we strongly
197 recommend that you do not use it unless you know what you are doing.
199 If the keyword {\bf Volume} appears on the command line, the named Volume
200 will be deleted from the catalog, if the keyword {\bf Pool} appears on the
201 command line, a Pool will be deleted, and if the keyword {\bf Job} appears on
202 the command line, a Job and all its associated records (File and JobMedia)
203 will be deleted from the catalog. The full form of this command is:
205 delete pool=\lt{}pool-name\gt{}
209 delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{} or
211 delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ... or
213 delete Job JobId=n,m,o-r,t ...
215 The first form deletes a Pool record from the catalog database. The second
216 form deletes a Volume record from the specified pool in the catalog database.
217 The third form deletes the specified Job record from the catalog database.
218 The last form deletes JobId records for JobIds n,m,o,p, q,r, and t. Where each
219 one of the n,m,... is, of course, a number.
223 \index[console]{estimate}
224 Using this command, you can get an idea how many files will be backed
225 up, or if you are unsure about your Include statements in your FileSet,
226 you can test them without doing an actual backup. The default is to
227 assume a Full backup. However, you can override this by specifying a
228 {\bf level=Incremental} or {\bf level=Differential} on the command line.
229 A Job name must be specified or you will be prompted for one, and
230 optionally a Client and FileSet may be specified on the command line.
231 It then contacts the client which computes the number of files and bytes
232 that would be backed up. Please note that this is an estimate
233 calculated from the number of blocks in the file rather than by reading
234 the actual bytes. As such, the estimated backup size will generally be
235 larger than an actual backup.
237 Optionally you may specify the keyword {\bf listing} in which case, all the
238 files to be backed up will be listed. Note, it could take quite some time to
239 display them if the backup is large. The full form is:
241 estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{}
242 fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{}
244 Specification of the {\bf job} is sufficient, but you can also override the
245 client, fileset and/or level by specifying them on the estimate command line.
248 As an example, you might do:
253 estimate job=NightlySave listing level=Incremental
258 which will do a full listing of all files to be backed up for the Job {\bf
259 NightlySave} during an Incremental save and put it in the file {\bf
263 \index[console]{help}
264 This command displays the list of commands available.
267 \index[console]{label}
268 \index[console]{relabel}
269 \index[general]{label}
270 \index[general]{relabel}
271 This command is used to label physical volumes. The full form of this command
274 label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{}
277 If you leave out any part, you will be prompted for it. The media type is
278 automatically taken from the Storage resource definition that you supply.
279 Once the necessary information is obtained, the Console program contacts the
280 specified Storage daemon and requests that the tape be labeled. If the tape
281 labeling is successful, the Console program will create a Volume record in
282 the appropriate Pool.
284 The Volume name is restricted to letters, numbers, and the special characters
285 hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and period ({\bf
286 .}). All other characters including a space are illegal. This restriction is
287 to ensure good readability of Volume names to reduce operator errors.
289 Please note, when labeling a blank tape, Bacula will get {\bf read I/O error} when
290 it attempts to ensure that the tape is already labeled. If you wish to avoid
291 getting these messages, please write and EOF mark on your tape before
292 attempting to label it:
302 The label command can fail for a number of reasons:
305 \item The Volume name you specify is already in the Volume database.
306 \item The Storage daemon has a tape already mounted on the device, in which
307 case you must {\bf unmount} the device, insert a blank tape, then do the
309 \item The tape in the device is already a Bacula labeled tape. (Bacula will
310 never relabel a Bacula labeled tape unless it is recycled and you use the
311 {\bf relabel} command).
312 \item There is no tape in the drive.
315 There are two ways to relabel a volume that already has a Bacula label. The
316 brute force method is to write an end of file mark on the tape using the
317 system {\bf mt} program, something like the following:
321 mt -f /dev/st0 rewind
326 Then you use the {\bf label} command to add a new label. However, this could
327 leave traces of the old volume in the catalog.
329 The preferable method to relabel a tape is to first {\bf purge} the volume,
330 either automatically, or explicitly with the {\bf purge} command, then use
331 the {\bf relabel} command described below.
333 If your autochanger has barcode labels, you can label all the Volumes in your
334 autochanger one after another by using the {\bf label barcodes} command. For
335 each tape in the changer containing a barcode, Bacula will mount the tape and
336 then label it with the same name as the barcode. An appropriate Media record
337 will also be created in the catalog. Any barcode that begins with the same
338 characters as specified on the "CleaningPrefix=xxx" directive in the
339 Director's Pool resource, will be
340 treated as a cleaning tape, and will not be labeled. However,
341 an entry for the cleaning tape will be created in
342 the catalog. For example with:
348 Cleaning Prefix = "CLN"
354 Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
355 and will not be mounted. Note, the full form of the command is:
359 update storage=xxx pool=yyy slots=1-5,10 barcodes
364 \index[console]{list }
365 The list command lists the requested contents of the Catalog. The various
366 fields of each record are listed on a single line. The various forms
367 of the list command are:
372 list jobid=\lt{}id\gt{}
374 list job=\lt{}job-name\gt{}
378 list jobmedia jobid=\lt{}id\gt{}
380 list jobmedia job=\lt{}job-name\gt{}
382 list files jobid=\lt{}id\gt{}
384 list files job=\lt{}job-name\gt{}
394 list volumes jobid=\lt{}id\gt{}
396 list volumes pool=\lt{}pool-name\gt{}
398 list volumes job=\lt{}job-name\gt{}
400 list volume=\lt{}volume-name\gt{}
402 list nextvolume job=\lt{}job-name\gt{}
404 list nextvol job=\lt{}job-name\gt{}
409 What most of the above commands do should be more or less obvious. In
410 general if you do not specify all the command line arguments, the
411 command will prompt you for what is needed.
413 The {\bf list nextvol} command will print the Volume name to be used by
414 the specified job. You should be aware that exactly what Volume will be
415 used depends on a lot of factors including the time and what a prior job
416 will do. It may fill a tape that is not full when you issue this
417 command. As a consequence, this command will give you a good estimate
418 of what Volume will be used but not a definitive answer. In addition,
419 this command may have certain side effect because it runs through the
420 same algorithm as a job, which means it may automatically purge or
423 If you wish to add specialized commands that list the contents of the
424 catalog, you can do so by adding them to the {\bf query.sql} file.
425 However, this takes some knowledge of programming SQL. Please see the
426 {\bf query} command below for additional information. See below for
427 listing the full contents of a catalog record with the {\bf llist}
430 As an example, the command {\bf list pools} might produce the following
435 +------+---------+---------+---------+----------+-------------+
436 | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
437 +------+---------+---------+---------+----------+-------------+
438 | 1 | Default | 0 | 0 | Backup | * |
439 | 2 | Recycle | 0 | 8 | Backup | File |
440 +------+---------+---------+---------+----------+-------------+
444 As mentioned above, the {\bf list} command lists what is in the
445 database. Some things are put into the database immediately when Bacula
446 starts up, but in general, most things are put in only when they are
447 first used, which is the case for a Client as with Job records, etc.
449 Bacula should create a client record in the database the first time you
450 run a job for that client. Doing a {\bf status} will not cause a
451 database record to be created. The client database record will be
452 created whether or not the job fails, but it must at least start. When
453 the Client is actually contacted, additional info from the client will
454 be added to the client record (a "uname -a" output).
456 If you want to see what Client resources you have available in your conf
457 file, you use the Console command {\bf show clients}.
460 \index[console]{llist}
461 The llist or "long list" command takes all the same arguments that the
462 list command described above does. The difference is that the llist
463 command list the full contents of each database record selected. It
464 does so by listing the various fields of the record vertically, with one
465 field per line. It is possible to produce a very large number of output
466 lines with this command.
468 If instead of the {\bf list pools} as in the example above, you enter
469 {\bf llist pools} you might get the following output:
480 VolRetention: 1,296,000
481 VolUseDuration: 86,400
496 VolUseDuration: 3,600
508 \index[console]{messages}
509 This command causes any pending console messages to be immediately displayed.
513 \index[console]{mount}
514 The mount command is used to get Bacula to read a volume on a physical
515 device. It is a way to tell Bacula that you have mounted a tape and
516 that Bacula should examine the tape. This command is used only after
517 there was no Volume in a drive and Bacula requests you to mount a new
518 Volume or when you have specifically unmounted a Volume with the {\bf
519 unmount} console command, which causes Bacula to close the drive. If
520 you have an autoloader, the mount command will not cause Bacula to
521 operate the autoloader. The various forms of the mount command are:
523 mount storage=\lt{}storage-name\gt{}
525 mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
527 If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
528 Device resource, under most circumstances, Bacula will automatically access
529 the Volume unless you have explicitly {\bf unmount}ed it in the Console
533 \index[console]{python}
534 The python command takes a single argument {\bf restart}:
538 This causes the Python interpreter in the Director to be reinitialized.
539 This can be helpful for testing because once the Director starts and the
540 Python interpreter is initialized, there is no other way to make it
541 accept any changes to the startup script {\bf DirStartUp.py}. For more
542 details on Python scripting, please see the \ilink{Python
543 Scripting}{_ChapterStart60} chapter of this manual.
545 \label{ManualPruning}
547 \index[console]{prune }
548 The Prune command allows you to safely remove expired database records
549 from Jobs and Volumes. This command works only on the Catalog database
550 and does not affect data written to Volumes. In all cases, the Prune
551 command applies a retention period to the specified records. You can
552 Prune expired File entries from Job records; you can Prune expired Job
553 records from the database, and you can Prune both expired Job and File
554 records from specified Volumes.
556 prune files|jobs|volume client=\lt{}client-name\gt{}
557 volume=\lt{}volume-name\gt{}
559 For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
560 Append, otherwise the pruning will not take place.
563 \index[console]{purge }
564 The Purge command will delete associated Catalog database records from
565 Jobs and Volumes without considering the retention period. {\bf Purge}
566 works only on the Catalog database and does not affect data written to
567 Volumes. This command can be dangerous because you can delete catalog
568 records associated with current backups of files, and we recommend that
569 you do not use it unless you know what you are doing. The permitted
570 forms of {\bf purge} are:
572 purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
574 purge jobs client=\lt{}client-name\gt{} (of all jobs)
576 purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
578 For the {\bf purge} command to work on Volume Catalog database records the
579 {\bf VolStatus} must be Append, Full, Used, or Error.
581 The actual data written to the Volume will be unaffected by this command.
584 \index[console]{relabel}
585 \index[general]{relabel}
586 This command is used to label physical volumes. The full form of this
589 relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
590 volume=\lt{}newvolume-name\gt{}
592 If you leave out any part, you will be prompted for it. In order for
593 the Volume (old-volume-name) to be relabeled, it must be in the catalog,
594 and the volume status must be marked {\bf Purged} or {\bf Recycle}.
595 This happens automatically as a result of applying retention periods, or
596 you may explicitly purge the volume using the {\bf purge} command.
598 Once the volume is physically relabeled, the old data previously written
599 on the Volume is lost and cannot be recovered.
602 \index[console]{release }
603 This command is used to cause the Storage daemon to rewind (release) the
604 current tape in the drive, and to re-read the Volume label the next time
607 release storage=\lt{}storage-name\gt{}
609 After a release command, the device is still kept open by Bacula (unless
610 Always Open is set to No in the Storage Daemon's configuration) so it
611 cannot be used by another program. However, with some tape drives, the
612 operator can remove the current tape and to insert a different one, and
613 when the next Job starts, Bacula will know to re-read the tape label to
614 find out what tape is mounted. If you want to be able to use the drive
615 with another program (e.g. {\bf mt}), you must use the {\bf unmount}
616 command to cause Bacula to completely release (close) the device.
619 \index[console]{reload}
620 The reload command causes the Director to re-read its configuration
621 file and apply the new values. The new values will take effect
622 immediately for all new jobs. However, if you change schedules,
623 be aware that the scheduler pre-schedules jobs up to two hours in
624 advance, so any changes that are to take place during the next two
625 hours may be delayed. Jobs that have already been scheduled to run
626 (i.e. surpassed their requested start time) will continue with the
627 old values. New jobs will use the new values. Each time you issue
628 a reload command while jobs are running, the prior config values
629 will queued until all jobs that were running before issuing
630 the reload terminate, at which time the old config values will
631 be released from memory. The Directory permits keeping up to
632 10 prior set of configurations before it will refuse a reload
633 command. Once at least one old set of config values has been
634 released it will again accept new reload commands.
636 While it is possible to reload the Director's configuration on the fly,
637 even while jobs are executing, this is a complex operation and not
638 without side effects. Accordingly, if you have to reload the Director's
639 configuration while Bacula is running, it is advisable to restart the
640 Director at the next convenient opportunity.
644 \index[console]{restore }
645 The restore command allows you to select one or more Jobs (JobIds) to be
646 restored using various methods. Once the JobIds are selected, the File
647 records for those Jobs are placed in an internal Bacula directory tree,
648 and the restore enters a file selection mode that allows you to
649 interactively walk up and down the file tree selecting individual files
650 to be restored. This mode is somewhat similar to the standard Unix {\bf
651 restore} program's interactive file selection mode.
653 restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{}
654 where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
655 select current all done
657 Where {\bf current}, if specified, tells the restore command to
658 automatically select a restore to the most current backup. If not
659 specified, you will be prompted. The {\bf all} specification tells the
660 restore command to restore all files. If it is not specified, you will
661 be prompted for the files to restore. For details of the {\bf restore}
662 command, please see the \ilink{Restore Chapter}{_ChapterStart13} of this
666 \index[console]{run }
667 This command allows you to schedule jobs to be run immediately. The full form
670 run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
671 fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
672 storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
673 when=\lt{}universal-time-specification\gt{} yes
675 Any information that is needed but not specified will be listed for
676 selection, and before starting the job, you will be prompted to accept,
677 reject, or modify the parameters of the job to be run, unless you have
678 specified {\bf yes}, in which case the job will be immediately sent to
681 On my system, when I enter a run command, I get the following prompt:
685 A job name must be specified.
686 The defined Job resources are:
696 Select Job resource (1-9):
701 If I then select number 5, I am prompted with:
707 FileSet: Minou Full Set
712 When: 2003-04-23 17:08:18
713 OK to run? (yes/mod/no):
718 If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
719 be presented with the following prompt.
723 Parameters to modify:
731 Select parameter to modify (1-7):
736 If you wish to start a job at a later time, you can do so by setting the When
737 time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
738 desired start time in YYYY-MM-DD HH:MM:SS format.
741 \index[dir]{setdebug}
742 This command is used to set the debug level in each daemon. The form of this
745 setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
746 storage=\lt{}storage-name\gt{} | all]
748 If trace=1 is set, then the tracing will be enabled, and the daemon
749 where the setdebug applies will be placed in trace mode, and all debug
750 output will go to the file {\bf bacula.trace} in the current directory
751 of the daemon. Normally, tracing is used only for Win32 clients where
752 the debug output cannot be written to a terminal or redirected to a
753 file. When tracing, each debug output message is appended to the trace
754 file. You must explicitly delete the file when you are done.
757 \index[console]{show }
758 The show command will list the Director's resource records as defined in
759 the Director's configuration file (normally {\bf bacula-dir.conf}).
760 This command is used mainly for debugging purposes by developers. The
761 following keywords are accepted on the show command line: directors,
762 clients, counters, jobs, storages, catalogs, schedules, filesets,
763 groups, pools, messages, all, help. Please don't confuse this command
764 with the {\bf list}, which displays the contents of the catalog.
767 \index[dir]{sqlquery }
768 The sqlquery command puts the Console program into SQL query mode where
769 each line you enter is concatenated to the previous line until a
770 semicolon (;) is seen. The semicolon terminates the command, which is
771 then passed directly to the SQL database engine. When the output from
772 the SQL engine is displayed, the formation of a new SQL command begins.
773 To terminate SQL query mode and return to the Console command prompt,
774 you enter a period (.) in column 1.
776 Using this command, you can query the SQL catalog database directly.
777 Note you should really know what you are doing otherwise you could
778 damage the catalog database. See the {\bf query} command below for
779 simpler and safer way of entering SQL queries.
781 Depending on what database engine you are using (MySQL, PostgreSQL or
782 SQLite), you will have somewhat different SQL commands available. For
783 more detailed information, please refer to the MySQL, PostgreSQL or
784 SQLite documentation.
788 This command will display the status of the next jobs that are scheduled
789 during the next twenty-four hours as well as the status of currently
790 running jobs. The full form of this command is:
792 status [all | dir=\lt{}dir-name\gt{} | director |
793 client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{}]
795 If you do a {\bf status dir}, the console will list any currently
796 running jobs, a summary of all jobs scheduled to be run in the next 24
797 hours, and a listing of the last 10 terminated jobs with their statuses.
798 The scheduled jobs summary will include the Volume name to be used. You
799 should be aware of two things: 1. to obtain the volume name, the code
800 goes through the same code that will be used when the job runs, which
801 means that it may prune or recycle a Volume; 2. The Volume listed is
802 only a best guess. The Volume actually used may be different because of
803 the time difference (more durations may expire when the job runs) and
804 another job could completely fill the Volume requiring a new one.
806 In the Running Jobs listing, you may find the following types of
812 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
813 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
814 priority jobs to finish
815 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
816 5343 Full Rufus.2004-03-13_01.05.04 is running
820 Looking at the above listing from bottom to top, obviously JobId 5343
821 (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
822 finish because it is using the Storage resource, hence the "waiting on
823 max Storage jobs". JobId 5349 has a lower priority than all the other
824 jobs so it is waiting for higher priority jobs to finish, and finally,
825 JobId 2508 (MatouVerify) is waiting because only one job can run at a
826 time, hence it is simply "waiting execution"
829 \index[console]{unmount }
830 This command causes the indicated Bacula Storage daemon to unmount the
831 specified device. The forms of the command are the same as the mount command:
834 unmount storage=\lt{}storage-name\gt{}
836 unmount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
840 \label{UpdateCommand}
842 \index[console]{update }
843 This command will update the catalog for either a specific Pool record, a Volume
844 record, or the Slots in an autochanger with barcode capability. In the case
845 of updating a Pool record, the new information will be automatically taken
846 from the corresponding Director's configuration resource record. It can be
847 used to increase the maximum number of volumes permitted or to set a maximum
848 number of volumes. The following main keywords may be specified:
851 media, volume, pool, slots
855 In the case of updating a Volume, you will be prompted for which value you
856 wish to change. The following Volume parameters may be changed:
862 Volume Retention Period
873 All Volumes from Pool
878 For slots {\bf update slots}, Bacula will obtain a list of slots and their
879 barcodes from the Storage daemon, and for each barcode found, it will
880 automatically update the slot in the catalog Media record to correspond to
881 the new value. This is very useful if you have moved cassettes in the
882 magazine, or if you have removed the magazine and inserted a different one.
883 As the slot of each Volume is updated, the InChanger flag for that Volume
884 will also be set, and any other Volumes in the Pool will have their InChanger
885 flag turned off. This permits Bacula to know what magazine (tape holder) is
886 currently in the autochanger.
888 If you do not have barcodes, you can accomplish the same thing in version
889 1.33 and later by using the {\bf update slots scan} command. The {\bf scan}
890 keyword tells Bacula to physically mount each tape and to read its
893 For Pool {\bf update pool}, Bacula will move the Volume record from its
894 existing pool to the pool specified.
896 For {\bf Volume from Pool} and {\bf All Volumes from Pool}, the following
897 values are updated from the Pool record: Recycle, VolRetention,
898 VolUseDuration, MaxVolJobs, MaxVolFiles, and MaxVolBytes.
900 The full form of the update command with all command line arguments is:
904 update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
905 VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
912 \index[console]{use }
913 This command allows you to specify which Catalog database to use. Normally,
914 you will be using only one database so this will be done automatically. In
915 the case that you are using more than one database, you can use this command
916 to switch from one to another.
918 use \lt{}database-name\gt{}
922 \index[console]{var name }
923 This command takes a string or quoted string and does variable expansion on
924 it the same way variable expansion is done on the {\bf LabelFormat} string.
925 Thus, for the most part, you can test your LabelFormat strings. The
926 difference between the {\bf var} command and the actual LabelFormat process
927 is that during the var command, no job is running so "dummy" values are
928 used in place of Job specific variables. Generally, however, you will get a
929 good idea of what is going to happen in the real case.
932 \index[console]{version }
933 The command prints the Director's version.
936 \index[console]{quit }
937 This command terminates the console program. The console program sends the
938 {\bf quit} request to the Director and waits for acknowledgment. If the
939 Director is busy doing a previous command for you that has not terminated, it
940 may take some time. You may quit immediately by issuing the {\bf .quit}
941 command (i.e. quit preceded by a period).
944 \index[console]{query }
945 This command reads a predefined SQL query from the query file (the name and
946 location of the query file is defined with the QueryFile resource record in
947 the Director's configuration file). You are prompted to select a query from
948 the file, and possibly enter one or more parameters, then the command is
949 submitted to the Catalog database SQL engine.
951 The following queries are currently available (version 1.24):
957 2: List where a file is saved:
958 3: List where the most recent copies of a file are saved:
959 4: List total files/bytes by Job:
960 5: List total files/bytes by Volume:
961 6: List last 20 Full Backups for a Client:
962 7: List Volumes used by selected JobId:
963 8: List Volumes to Restore All Files:
964 9: List where a File is saved:
965 Choose a query (1-9):
971 \index[console]{exit }
972 This command terminates the console program.
975 \index[console]{wait }
976 The wait command causes the Director to pause until there are no jobs
977 running. This command is useful in a batch situation such as regression
978 testing where you wish to start a job and wait until that job completes
984 \subsection*{Special dot Commands}
985 \index[general]{Commands!Special dot }
986 \index[general]{Special dot Commands }
987 \addcontentsline{toc}{subsection}{Special dot Commands}
989 There is a list of commands that are prefixed with a period (.). These
990 commands are intended to be used either by batch programs or graphical user
991 interface front-ends. They are not normally used by interactive users. Once
992 GUI development begins, this list will be considerably expanded. The following
993 is the list of dot commands:
997 .backups job=xxx list backups for specified job
998 .defaults client=xxx fileset=yyy list defaults for specified client
999 .die cause the Director to segment fault (for debugging)
1000 .dir when in tree mode prints the equivalent to the dir command,
1001 but with fields separated by commas rather than spaces.
1002 .jobs list all job names
1003 .levels list all levels
1004 .filesets list all fileset names
1005 .clients list all client names
1006 .pools list all pool names
1007 .types list job types
1008 .msgs return any queued messages
1009 .messages get quick messages
1010 .help help command output
1012 .status get status output
1019 \subsection*{Special At (@) Commands}
1020 \index[general]{Commands!Special At @ }
1021 \index[general]{Special At (@) Commands }
1022 \addcontentsline{toc}{subsection}{Special At (@) Commands}
1024 Normally, all commands entered to the Console program are immediately
1025 forwarded to the Director, which may be on another machine, to be executed.
1026 However, there is a small list of {\bf at} commands, all beginning with an at
1027 character (@), that will not be sent to the Director, but rather interpreted
1028 by the Console program directly. Note, these commands are implemented only in
1029 the tty console program and not in the GNOME Console. These commands are:
1033 \item [@input \lt{}filename\gt{}]
1034 \index[console]{@input \lt{}filename\gt{} }
1035 Read and execute the commands contained in the file specified.
1037 \item [@output \lt{}filename\gt{} w/a]
1038 \index[console]{@output \lt{}filename\gt{} w/a }
1039 Send all following output to the filename specified either overwriting the
1040 file (w) or appending to the file (a). To redirect the output to the
1041 terminal, simply enter {\bf @output} without a filename specification.
1042 WARNING: be careful not to overwrite a valid file. A typical example during a
1043 regression test might be:
1054 \item [@tee \lt{}filename\gt{} w/a]
1055 \index[console]{@tee \lt{}filename\gt{} w/a }
1056 Send all subsequent output to both the specified file and the terminal. It is
1057 turned off by specifying {\bf @tee} or {\bf @output} without a filename.
1059 \item [@sleep \lt{}seconds\gt{}]
1060 \index[console]{@sleep \lt{}seconds\gt{} }
1061 Sleep the specified number of seconds.
1064 \index[console]{@time }
1065 Print the current time and date.
1068 \index[console]{@version }
1069 Print the console's version.
1072 \index[console]{@quit }
1076 \index[console]{@exit }
1079 \item [@\# anything]
1080 \index[console]{anything }
1086 \subsection*{Running the Console Program from a Shell Script}
1087 \index[general]{Script!Running the Console Program from a Shell }
1088 \index[general]{Running the Console Program from a Shell Script }
1089 \addcontentsline{toc}{subsection}{Running the Console Program from a Shell
1092 You can automate many Console tasks by running the console program from a
1093 shell script. For example, if you have created a file containing the following
1098 ./bconsole -c ./bconsole.conf <<END_OF_DATA
1099 unmount storage=DDS-4
1105 when that file is executed, it will unmount the current DDS-4 storage device.
1106 You might want to run this command during a Job by using the {\bf
1107 RunBeforeJob} or {\bf RunAfterJob} records.
1109 It is also possible to run the Console program from file input where the file
1110 contains the commands as follows:
1114 ./bconsole -c ./bconsole.conf <filename
1118 where the file named {\bf filename} contains any set of console commands.
1120 As a real example, the following script is part of the Bacula regression
1121 tests. It labels a volume (a disk volume), runs a backup, then does a restore
1126 bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
1129 @output /tmp/log1.out
1130 label volume=TestVolume001
1137 @output /tmp/log2.out
1148 The output from the backup is directed to /tmp/log1.out and the output from
1149 the restore is directed to /tmp/log2.out. To ensure that the backup and
1150 restore ran correctly, the output files are checked with:
1154 grep "^Termination: *Backup OK" /tmp/log1.out
1156 grep "^Termination: *Restore OK" /tmp/log2.out
1161 \subsection*{Adding Volumes to a Pool}
1162 \index[general]{Adding Volumes to a Pool }
1163 \index[general]{Pool!Adding Volumes to a }
1164 \addcontentsline{toc}{subsection}{Adding Volumes to a Pool}
1166 If you have used the {\bf label} command to label a Volume, it will be
1167 automatically added to the Pool, and you will not need to add any media to the
1170 Alternatively, you may choose to add a number of Volumes to the pool without
1171 labeling them. At a later time when the Volume is requested by {\bf Bacula}
1172 you will need to label it.
1174 Before adding a volume, you must know the following information:
1177 \item The name of the Pool (normally "Default")
1178 \item The Media Type as specified in the Storage Resource in the Director's
1179 configuration file (e.g. "DLT8000")
1180 \item The number and names of the Volumes you wish to create.
1183 For example, to add media to a Pool, you would issue the following commands to
1184 the console program:
1189 Enter name of Pool to add Volumes to: Default
1190 Enter the Media Type: DLT8000
1191 Enter number of Media volumes to create. Max=1000: 10
1192 Enter base volume name: Save
1193 Enter the starting number: 1
1194 10 Volumes created in pool Default
1199 To see what you have added, enter:
1203 *list media pool=Default
1204 +-------+----------+---------+---------+-------+------------------+
1205 | MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
1206 +-------+----------+---------+---------+-------+------------------+
1207 | 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1208 | 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1209 | 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1210 | 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1211 | 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1212 | 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1213 | 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1214 | 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1215 | 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1216 | 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1217 +-------+----------+---------+---------+-------+------------------+
1222 Notice that the console program automatically appended a number to the base
1223 Volume name that you specify (Save in this case). If you don't want it to
1224 append a number, you can simply answer 0 (zero) to the question "Enter number
1225 of Media volumes to create. Max=1000:", and in this case, it will create a
1226 single Volume with the exact name you specify.