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
238
\index[console]{estimate}
239
Using this command, you can get an idea how many files will be backed
240
up, or if you are unsure about your Include statements in your FileSet,
241
you can test them without doing an actual backup. The default is to
242
assume a Full backup. However, you can override this by specifying a
243
{\bf level=Incremental} or {\bf level=Differential} on the command line.
244
A Job name must be specified or you will be prompted for one, and
245
optionally a Client and FileSet may be specified on the command line.
246
It then contacts the client which computes the number of files and bytes
247
that would be backed up. Please note that this is an estimate
248
calculated from the number of blocks in the file rather than by reading
249
the actual bytes. As such, the estimated backup size will generally be
250
larger than an actual backup.
252
Optionally you may specify the keyword {\bf listing} in which case, all the
253
files to be backed up will be listed. Note, it could take quite some time to
254
display them if the backup is large. The full form is:
256
estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{}
257
fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{}
259
Specification of the {\bf job} is sufficient, but you can also override
260
the client, fileset and/or level by specifying them on the estimate
264
As an example, you might do:
269
estimate job=NightlySave listing level=Incremental
274
which will do a full listing of all files to be backed up for the Job {\bf
275
NightlySave} during an Incremental save and put it in the file {\bf
279
\index[console]{help}
280
This command displays the list of commands available.
283
\index[console]{label}
284
\index[console]{relabel}
285
\index[general]{label}
286
\index[general]{relabel}
287
This command is used to label physical volumes. The full form of this command
290
label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{}
293
If you leave out any part, you will be prompted for it. The media type
294
is automatically taken from the Storage resource definition that you
295
supply. Once the necessary information is obtained, the Console program
296
contacts the specified Storage daemon and requests that the tape be
297
labeled. If the tape labeling is successful, the Console program will
298
create a Volume record in the appropriate Pool.
300
The Volume name is restricted to letters, numbers, and the special
301
characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
302
period ({\bf .}). All other characters including a space are illegal.
303
This restriction is to ensure good readability of Volume names to reduce
306
Please note, when labeling a blank tape, Bacula will get {\bf read I/O
307
error} when it attempts to ensure that the tape is already labeled. If
308
you wish to avoid getting these messages, please write and EOF mark on
309
your tape before attempting to label it:
319
The label command can fail for a number of reasons:
322
\item The Volume name you specify is already in the Volume database.
323
\item The Storage daemon has a tape already mounted on the device, in which
324
case you must {\bf unmount} the device, insert a blank tape, then do the
326
\item The tape in the device is already a Bacula labeled tape. (Bacula will
327
never relabel a Bacula labeled tape unless it is recycled and you use the
328
{\bf relabel} command).
329
\item There is no tape in the drive.
332
There are two ways to relabel a volume that already has a Bacula label. The
333
brute force method is to write an end of file mark on the tape using the
334
system {\bf mt} program, something like the following:
338
mt -f /dev/st0 rewind
343
Then you use the {\bf label} command to add a new label. However, this could
344
leave traces of the old volume in the catalog.
346
The preferable method to relabel a tape is to first {\bf purge} the volume,
347
either automatically, or explicitly with the {\bf purge} command, then use
348
the {\bf relabel} command described below.
350
If your autochanger has barcode labels, you can label all the Volumes in your
351
autochanger one after another by using the {\bf label barcodes} command. For
352
each tape in the changer containing a barcode, Bacula will mount the tape and
353
then label it with the same name as the barcode. An appropriate Media record
354
will also be created in the catalog. Any barcode that begins with the same
355
characters as specified on the "CleaningPrefix=xxx" directive in the
356
Director's Pool resource, will be
357
treated as a cleaning tape, and will not be labeled. However,
358
an entry for the cleaning tape will be created in
359
the catalog. For example with:
365
Cleaning Prefix = "CLN"
371
Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
372
and will not be mounted. Note, the full form of the command is:
376
update storage=xxx pool=yyy slots=1-5,10 barcodes
381
\index[console]{list}
382
The list command lists the requested contents of the Catalog. The
383
various fields of each record are listed on a single line. The various
384
forms of the list command are:
389
list jobid=\lt{}id\gt{}
391
list job=\lt{}job-name\gt{}
395
list jobmedia jobid=\lt{}id\gt{}
397
list jobmedia job=\lt{}job-name\gt{}
399
list files jobid=\lt{}id\gt{}
401
list files job=\lt{}job-name\gt{}
411
list volumes jobid=\lt{}id\gt{}
413
list volumes pool=\lt{}pool-name\gt{}
415
list volumes job=\lt{}job-name\gt{}
417
list volume=\lt{}volume-name\gt{}
419
list nextvolume job=\lt{}job-name\gt{}
421
list nextvol job=\lt{}job-name\gt{}
423
list nextvol job=\lt{}job-name\gt{} days=nnn
430
What most of the above commands do should be more or less obvious. In
431
general if you do not specify all the command line arguments, the
432
command will prompt you for what is needed.
434
The {\bf list nextvol} command will print the Volume name to be used by
435
the specified job. You should be aware that exactly what Volume will be
436
used depends on a lot of factors including the time and what a prior job
437
will do. It may fill a tape that is not full when you issue this
438
command. As a consequence, this command will give you a good estimate
439
of what Volume will be used but not a definitive answer. In addition,
440
this command may have certain side effect because it runs through the
441
same algorithm as a job, which means it may automatically purge or
442
recycle a Volume. By default, the job specified must run within the
443
next two days or no volume will be found. You can, however, use the
444
{\bf days=nnn} specification to specify up to 50 days. For example,
445
if on Friday, you want to see what Volume will be needed on Monday,
446
for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
448
If you wish to add specialized commands that list the contents of the
449
catalog, you can do so by adding them to the {\bf query.sql} file.
450
However, this takes some knowledge of programming SQL. Please see the
451
{\bf query} command below for additional information. See below for
452
listing the full contents of a catalog record with the {\bf llist}
455
As an example, the command {\bf list pools} might produce the following
460
+------+---------+---------+---------+----------+-------------+
461
| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
462
+------+---------+---------+---------+----------+-------------+
463
| 1 | Default | 0 | 0 | Backup | * |
464
| 2 | Recycle | 0 | 8 | Backup | File |
465
+------+---------+---------+---------+----------+-------------+
469
As mentioned above, the {\bf list} command lists what is in the
470
database. Some things are put into the database immediately when Bacula
471
starts up, but in general, most things are put in only when they are
472
first used, which is the case for a Client as with Job records, etc.
474
Bacula should create a client record in the database the first time you
475
run a job for that client. Doing a {\bf status} will not cause a
476
database record to be created. The client database record will be
477
created whether or not the job fails, but it must at least start. When
478
the Client is actually contacted, additional info from the client will
479
be added to the client record (a "uname -a" output).
481
If you want to see what Client resources you have available in your conf
482
file, you use the Console command {\bf show clients}.
485
\index[console]{llist}
486
The llist or "long list" command takes all the same arguments that the
487
list command described above does. The difference is that the llist
488
command list the full contents of each database record selected. It
489
does so by listing the various fields of the record vertically, with one
490
field per line. It is possible to produce a very large number of output
491
lines with this command.
493
If instead of the {\bf list pools} as in the example above, you enter
494
{\bf llist pools} you might get the following output:
505
VolRetention: 1,296,000
506
VolUseDuration: 86,400
521
VolUseDuration: 3,600
533
\index[console]{messages}
534
This command causes any pending console messages to be immediately displayed.
538
\index[console]{mount}
539
The mount command is used to get Bacula to read a volume on a physical
540
device. It is a way to tell Bacula that you have mounted a tape and
541
that Bacula should examine the tape. This command is used only after
542
there was no Volume in a drive and Bacula requests you to mount a new
543
Volume or when you have specifically unmounted a Volume with the {\bf
544
unmount} console command, which causes Bacula to close the drive. If
545
you have an autoloader, the mount command will not cause Bacula to
546
operate the autoloader. The various forms of the mount command are:
548
mount storage=\lt{}storage-name\gt{}
550
mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
552
If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
553
Device resource, under most circumstances, Bacula will automatically access
554
the Volume unless you have explicitly {\bf unmount}ed it in the Console
558
\index[console]{python}
559
The python command takes a single argument {\bf restart}:
563
This causes the Python interpreter in the Director to be reinitialized.
564
This can be helpful for testing because once the Director starts and the
565
Python interpreter is initialized, there is no other way to make it
566
accept any changes to the startup script {\bf DirStartUp.py}. For more
567
details on Python scripting, please see the \ilink{Python
568
Scripting}{_ChapterStart60} chapter of this manual.
570
\label{ManualPruning}
572
\index[console]{prune}
573
The Prune command allows you to safely remove expired database records
574
from Jobs and Volumes. This command works only on the Catalog database
575
and does not affect data written to Volumes. In all cases, the Prune
576
command applies a retention period to the specified records. You can
577
Prune expired File entries from Job records; you can Prune expired Job
578
records from the database, and you can Prune both expired Job and File
579
records from specified Volumes.
581
prune files|jobs|volume client=\lt{}client-name\gt{}
582
volume=\lt{}volume-name\gt{}
584
For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
585
Append, otherwise the pruning will not take place.
588
\index[console]{purge}
589
The Purge command will delete associated Catalog database records from
590
Jobs and Volumes without considering the retention period. {\bf Purge}
591
works only on the Catalog database and does not affect data written to
592
Volumes. This command can be dangerous because you can delete catalog
593
records associated with current backups of files, and we recommend that
594
you do not use it unless you know what you are doing. The permitted
595
forms of {\bf purge} are:
597
purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
599
purge jobs client=\lt{}client-name\gt{} (of all jobs)
601
purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
603
For the {\bf purge} command to work on Volume Catalog database records the
604
{\bf VolStatus} must be Append, Full, Used, or Error.
606
The actual data written to the Volume will be unaffected by this command.
609
\index[console]{relabel}
610
\index[general]{relabel}
611
This command is used to label physical volumes. The full form of this
614
relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
615
volume=\lt{}newvolume-name\gt{}
617
If you leave out any part, you will be prompted for it. In order for
618
the Volume (old-volume-name) to be relabeled, it must be in the catalog,
619
and the volume status must be marked {\bf Purged} or {\bf Recycle}.
620
This happens automatically as a result of applying retention periods, or
621
you may explicitly purge the volume using the {\bf purge} command.
623
Once the volume is physically relabeled, the old data previously written
624
on the Volume is lost and cannot be recovered.
627
\index[console]{release}
628
This command is used to cause the Storage daemon to rewind (release) the
629
current tape in the drive, and to re-read the Volume label the next time
632
release storage=\lt{}storage-name\gt{}
634
After a release command, the device is still kept open by Bacula (unless
635
Always Open is set to No in the Storage Daemon's configuration) so it
636
cannot be used by another program. However, with some tape drives, the
637
operator can remove the current tape and to insert a different one, and
638
when the next Job starts, Bacula will know to re-read the tape label to
639
find out what tape is mounted. If you want to be able to use the drive
640
with another program (e.g. {\bf mt}), you must use the {\bf unmount}
641
command to cause Bacula to completely release (close) the device.
644
\index[console]{reload}
645
The reload command causes the Director to re-read its configuration
646
file and apply the new values. The new values will take effect
647
immediately for all new jobs. However, if you change schedules,
648
be aware that the scheduler pre-schedules jobs up to two hours in
649
advance, so any changes that are to take place during the next two
650
hours may be delayed. Jobs that have already been scheduled to run
651
(i.e. surpassed their requested start time) will continue with the
652
old values. New jobs will use the new values. Each time you issue
653
a reload command while jobs are running, the prior config values
654
will queued until all jobs that were running before issuing
655
the reload terminate, at which time the old config values will
656
be released from memory. The Directory permits keeping up to
657
10 prior set of configurations before it will refuse a reload
658
command. Once at least one old set of config values has been
659
released it will again accept new reload commands.
661
While it is possible to reload the Director's configuration on the fly,
662
even while jobs are executing, this is a complex operation and not
663
without side effects. Accordingly, if you have to reload the Director's
664
configuration while Bacula is running, it is advisable to restart the
665
Director at the next convenient opportunity.
669
\index[console]{restore}
670
The restore command allows you to select one or more Jobs (JobIds) to be
671
restored using various methods. Once the JobIds are selected, the File
672
records for those Jobs are placed in an internal Bacula directory tree,
673
and the restore enters a file selection mode that allows you to
674
interactively walk up and down the file tree selecting individual files
675
to be restored. This mode is somewhat similar to the standard Unix {\bf
676
restore} program's interactive file selection mode.
678
restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{}
679
where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
680
select current all done
682
Where {\bf current}, if specified, tells the restore command to
683
automatically select a restore to the most current backup. If not
684
specified, you will be prompted. The {\bf all} specification tells the
685
restore command to restore all files. If it is not specified, you will
686
be prompted for the files to restore. For details of the {\bf restore}
687
command, please see the \ilink{Restore Chapter}{_ChapterStart13} of this
692
This command allows you to schedule jobs to be run immediately. The full form
695
run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
696
fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
697
storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
698
when=\lt{}universal-time-specification\gt{} yes
700
Any information that is needed but not specified will be listed for
701
selection, and before starting the job, you will be prompted to accept,
702
reject, or modify the parameters of the job to be run, unless you have
703
specified {\bf yes}, in which case the job will be immediately sent to
706
On my system, when I enter a run command, I get the following prompt:
710
A job name must be specified.
711
The defined Job resources are:
721
Select Job resource (1-9):
726
If I then select number 5, I am prompted with:
732
FileSet: Minou Full Set
737
When: 2003-04-23 17:08:18
738
OK to run? (yes/mod/no):
743
If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
744
be presented with the following prompt.
748
Parameters to modify:
756
Select parameter to modify (1-7):
761
If you wish to start a job at a later time, you can do so by setting the When
762
time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
763
desired start time in YYYY-MM-DD HH:MM:SS format.
766
\index[dir]{setdebug}
767
This command is used to set the debug level in each daemon. The form of this
770
setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
771
storage=\lt{}storage-name\gt{} | all]
773
If trace=1 is set, then the tracing will be enabled, and the daemon
774
where the setdebug applies will be placed in trace mode, and all debug
775
output will go to the file {\bf bacula.trace} in the current directory
776
of the daemon. Normally, tracing is used only for Win32 clients where
777
the debug output cannot be written to a terminal or redirected to a
778
file. When tracing, each debug output message is appended to the trace
779
file. You must explicitly delete the file when you are done.
782
\index[console]{show}
783
The show command will list the Director's resource records as defined in
784
the Director's configuration file (normally {\bf bacula-dir.conf}).
785
This command is used mainly for debugging purposes by developers. The
786
following keywords are accepted on the show command line: directors,
787
clients, counters, jobs, storages, catalogs, schedules, filesets,
788
groups, pools, messages, all, help. Please don't confuse this command
789
with the {\bf list}, which displays the contents of the catalog.
792
\index[dir]{sqlquery}
793
The sqlquery command puts the Console program into SQL query mode where
794
each line you enter is concatenated to the previous line until a
795
semicolon (;) is seen. The semicolon terminates the command, which is
796
then passed directly to the SQL database engine. When the output from
797
the SQL engine is displayed, the formation of a new SQL command begins.
798
To terminate SQL query mode and return to the Console command prompt,
799
you enter a period (.) in column 1.
801
Using this command, you can query the SQL catalog database directly.
802
Note you should really know what you are doing otherwise you could
803
damage the catalog database. See the {\bf query} command below for
804
simpler and safer way of entering SQL queries.
806
Depending on what database engine you are using (MySQL, PostgreSQL or
807
SQLite), you will have somewhat different SQL commands available. For
808
more detailed information, please refer to the MySQL, PostgreSQL or
809
SQLite documentation.
813
This command will display the status of the next jobs that are scheduled
814
during the next twenty-four hours as well as the status of currently
815
running jobs. The full form of this command is:
817
status [all | dir=\lt{}dir-name\gt{} | director |
818
client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} |
821
If you do a {\bf status dir}, the console will list any currently
822
running jobs, a summary of all jobs scheduled to be run in the next 24
823
hours, and a listing of the last 10 terminated jobs with their statuses.
824
The scheduled jobs summary will include the Volume name to be used. You
825
should be aware of two things: 1. to obtain the volume name, the code
826
goes through the same code that will be used when the job runs, which
827
means that it may prune or recycle a Volume; 2. The Volume listed is
828
only a best guess. The Volume actually used may be different because of
829
the time difference (more durations may expire when the job runs) and
830
another job could completely fill the Volume requiring a new one.
832
In the Running Jobs listing, you may find the following types of
838
2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
839
5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
840
priority jobs to finish
841
5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
842
5343 Full Rufus.2004-03-13_01.05.04 is running
846
Looking at the above listing from bottom to top, obviously JobId 5343
847
(Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
848
finish because it is using the Storage resource, hence the "waiting on
849
max Storage jobs". JobId 5349 has a lower priority than all the other
850
jobs so it is waiting for higher priority jobs to finish, and finally,
851
JobId 2508 (MatouVerify) is waiting because only one job can run at a
852
time, hence it is simply "waiting execution"
854
If you do a {\bf status dir}, it will by default list all jobs
855
that are scheduled in the next two days. If you wish to see
856
the jobs that are scheduled in the next 3 days (e.g. on Friday
857
you want to see wat tapes are scheduled to be used on Monday), you
858
can add the {\bf days=3} option.
861
\index[console]{unmount}
862
This command causes the indicated Bacula Storage daemon to unmount the
863
specified device. The forms of the command are the same as the mount command:
866
unmount storage=\lt{}storage-name\gt{}
868
unmount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
872
\label{UpdateCommand}
874
\index[console]{update}
875
This command will update the catalog for either a specific Pool record, a Volume
876
record, or the Slots in an autochanger with barcode capability. In the case
877
of updating a Pool record, the new information will be automatically taken
878
from the corresponding Director's configuration resource record. It can be
879
used to increase the maximum number of volumes permitted or to set a maximum
880
number of volumes. The following main keywords may be specified:
883
media, volume, pool, slots
887
In the case of updating a Volume, you will be prompted for which value you
888
wish to change. The following Volume parameters may be changed:
894
Volume Retention Period
905
All Volumes from Pool
910
For slots {\bf update slots}, Bacula will obtain a list of slots and
911
their barcodes from the Storage daemon, and for each barcode found, it
912
will automatically update the slot in the catalog Media record to
913
correspond to the new value. This is very useful if you have moved
914
cassettes in the magazine, or if you have removed the magazine and
915
inserted a different one. As the slot of each Volume is updated, the
916
InChanger flag for that Volume will also be set, and any other Volumes
917
in the Pool will have their InChanger flag turned off. This permits
918
Bacula to know what magazine (tape holder) is currently in the
921
If you do not have barcodes, you can accomplish the same thing in
922
version 1.33 and later by using the {\bf update slots scan} command.
923
The {\bf scan} keyword tells Bacula to physically mount each tape and to
926
For Pool {\bf update pool}, Bacula will move the Volume record from its
927
existing pool to the pool specified.
929
For {\bf Volume from Pool} and {\bf All Volumes from Pool}, the
930
following values are updated from the Pool record: Recycle,
931
VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, and MaxVolBytes.
933
The full form of the update command with all command line arguments is:
937
update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
938
VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
945
\index[console]{use }
946
This command allows you to specify which Catalog database to use. Normally,
947
you will be using only one database so this will be done automatically. In
948
the case that you are using more than one database, you can use this command
949
to switch from one to another.
951
use \lt{}database-name\gt{}
955
\index[console]{var name }
956
This command takes a string or quoted string and does variable expansion on
957
it the same way variable expansion is done on the {\bf LabelFormat} string.
958
Thus, for the most part, you can test your LabelFormat strings. The
959
difference between the {\bf var} command and the actual LabelFormat process
960
is that during the var command, no job is running so "dummy" values are
961
used in place of Job specific variables. Generally, however, you will get a
962
good idea of what is going to happen in the real case.
965
\index[console]{version }
966
The command prints the Director's version.
969
\index[console]{quit }
970
This command terminates the console program. The console program sends the
971
{\bf quit} request to the Director and waits for acknowledgment. If the
972
Director is busy doing a previous command for you that has not terminated, it
973
may take some time. You may quit immediately by issuing the {\bf .quit}
974
command (i.e. quit preceded by a period).
977
\index[console]{query }
978
This command reads a predefined SQL query from the query file (the name and
979
location of the query file is defined with the QueryFile resource record in
980
the Director's configuration file). You are prompted to select a query from
981
the file, and possibly enter one or more parameters, then the command is
982
submitted to the Catalog database SQL engine.
984
The following queries are currently available (version 1.24):
990
2: List where a file is saved:
991
3: List where the most recent copies of a file are saved:
992
4: List total files/bytes by Job:
993
5: List total files/bytes by Volume:
994
6: List last 20 Full Backups for a Client:
995
7: List Volumes used by selected JobId:
996
8: List Volumes to Restore All Files:
997
9: List where a File is saved:
998
Choose a query (1-9):
1004
\index[console]{exit }
1005
This command terminates the console program.
1008
\index[console]{wait }
1009
The wait command causes the Director to pause until there are no jobs
1010
running. This command is useful in a batch situation such as regression
1011
testing where you wish to start a job and wait until that job completes
1017
\subsection*{Special dot Commands}
1018
\index[general]{Commands!Special dot }
1019
\index[general]{Special dot Commands }
1020
\addcontentsline{toc}{subsection}{Special dot Commands}
1022
There is a list of commands that are prefixed with a period (.). These
1023
commands are intended to be used either by batch programs or graphical user
1024
interface front-ends. They are not normally used by interactive users. Once
1025
GUI development begins, this list will be considerably expanded. The following
1026
is the list of dot commands:
1030
.backups job=xxx list backups for specified job
1031
.defaults client=xxx fileset=yyy list defaults for specified client
1032
.die cause the Director to segment fault (for debugging)
1033
.dir when in tree mode prints the equivalent to the dir command,
1034
but with fields separated by commas rather than spaces.
1035
.jobs list all job names
1036
.levels list all levels
1037
.filesets list all fileset names
1038
.clients list all client names
1039
.pools list all pool names
1040
.types list job types
1041
.msgs return any queued messages
1042
.messages get quick messages
1043
.help help command output
1045
.status get status output
1052
\subsection*{Special At (@) Commands}
1053
\index[general]{Commands!Special At @ }
1054
\index[general]{Special At (@) Commands }
1055
\addcontentsline{toc}{subsection}{Special At (@) Commands}
1057
Normally, all commands entered to the Console program are immediately
1058
forwarded to the Director, which may be on another machine, to be executed.
1059
However, there is a small list of {\bf at} commands, all beginning with an at
1060
character (@), that will not be sent to the Director, but rather interpreted
1061
by the Console program directly. Note, these commands are implemented only in
1062
the tty console program and not in the GNOME Console. These commands are:
1066
\item [@input \lt{}filename\gt{}]
1067
\index[console]{@input \lt{}filename\gt{} }
1068
Read and execute the commands contained in the file specified.
1070
\item [@output \lt{}filename\gt{} w/a]
1071
\index[console]{@output \lt{}filename\gt{} w/a }
1072
Send all following output to the filename specified either overwriting the
1073
file (w) or appending to the file (a). To redirect the output to the
1074
terminal, simply enter {\bf @output} without a filename specification.
1075
WARNING: be careful not to overwrite a valid file. A typical example during a
1076
regression test might be:
1087
\item [@tee \lt{}filename\gt{} w/a]
1088
\index[console]{@tee \lt{}filename\gt{} w/a }
1089
Send all subsequent output to both the specified file and the terminal. It is
1090
turned off by specifying {\bf @tee} or {\bf @output} without a filename.
1092
\item [@sleep \lt{}seconds\gt{}]
1093
\index[console]{@sleep \lt{}seconds\gt{} }
1094
Sleep the specified number of seconds.
1097
\index[console]{@time }
1098
Print the current time and date.
1101
\index[console]{@version }
1102
Print the console's version.
1105
\index[console]{@quit }
1109
\index[console]{@exit }
1112
\item [@\# anything]
1113
\index[console]{anything }
1119
\subsection*{Running the Console Program from a Shell Script}
1120
\index[general]{Script!Running the Console Program from a Shell }
1121
\index[general]{Running the Console Program from a Shell Script }
1122
\addcontentsline{toc}{subsection}{Running the Console Program from a Shell
1125
You can automate many Console tasks by running the console program from a
1126
shell script. For example, if you have created a file containing the following
1131
./bconsole -c ./bconsole.conf <<END_OF_DATA
1132
unmount storage=DDS-4
1138
when that file is executed, it will unmount the current DDS-4 storage device.
1139
You might want to run this command during a Job by using the {\bf
1140
RunBeforeJob} or {\bf RunAfterJob} records.
1142
It is also possible to run the Console program from file input where the file
1143
contains the commands as follows:
1147
./bconsole -c ./bconsole.conf <filename
1151
where the file named {\bf filename} contains any set of console commands.
1153
As a real example, the following script is part of the Bacula regression
1154
tests. It labels a volume (a disk volume), runs a backup, then does a restore
1159
bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
1162
@output /tmp/log1.out
1163
label volume=TestVolume001
1170
@output /tmp/log2.out
1181
The output from the backup is directed to /tmp/log1.out and the output from
1182
the restore is directed to /tmp/log2.out. To ensure that the backup and
1183
restore ran correctly, the output files are checked with:
1187
grep "^Termination: *Backup OK" /tmp/log1.out
1189
grep "^Termination: *Restore OK" /tmp/log2.out
1194
\subsection*{Adding Volumes to a Pool}
1195
\index[general]{Adding Volumes to a Pool }
1196
\index[general]{Pool!Adding Volumes to a }
1197
\addcontentsline{toc}{subsection}{Adding Volumes to a Pool}
1199
If you have used the {\bf label} command to label a Volume, it will be
1200
automatically added to the Pool, and you will not need to add any media to the
1203
Alternatively, you may choose to add a number of Volumes to the pool without
1204
labeling them. At a later time when the Volume is requested by {\bf Bacula}
1205
you will need to label it.
1207
Before adding a volume, you must know the following information:
1210
\item The name of the Pool (normally "Default")
1211
\item The Media Type as specified in the Storage Resource in the Director's
1212
configuration file (e.g. "DLT8000")
1213
\item The number and names of the Volumes you wish to create.
1216
For example, to add media to a Pool, you would issue the following commands to
1217
the console program:
1222
Enter name of Pool to add Volumes to: Default
1223
Enter the Media Type: DLT8000
1224
Enter number of Media volumes to create. Max=1000: 10
1225
Enter base volume name: Save
1226
Enter the starting number: 1
1227
10 Volumes created in pool Default
1232
To see what you have added, enter:
1236
*list media pool=Default
1237
+-------+----------+---------+---------+-------+------------------+
1238
| MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
1239
+-------+----------+---------+---------+-------+------------------+
1240
| 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1241
| 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1242
| 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1243
| 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1244
| 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1245
| 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1246
| 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1247
| 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1248
| 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1249
| 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1250
+-------+----------+---------+---------+-------+------------------+
1255
Notice that the console program automatically appended a number to the base
1256
Volume name that you specify (Save in this case). If you don't want it to
1257
append a number, you can simply answer 0 (zero) to the question "Enter number
1258
of Media volumes to create. Max=1000:", and in this case, it will create a
1259
single Volume with the exact name you specify.
added
removed
manual-de/console.tex
