Debian Codegraph @

manuals/en/console/bconsole.tex

raw
1 \chapter{Bacula Enterprise Console}
2 \label{blb:ConsoleChapter}
3 \index[general]{Console!Bacula}
4 \index[general]{Bacula Console}
5
6 The \bConsole{} (sometimes called the \emph{User Agent}) is a program
7 that allows the user or the System Administrator, to interact with the
8 \bDirector{} daemon while the daemon is running.
9
10 The current \bConsole{} comes in two versions: a shell interface (TTY
11 style), and a QT GUI interface (\bat{}). Both permit the administrator or
12 authorized users to interact with \bacula{}. You can determine the status of a
13 particular job, examine the contents of the Catalog as well as perform certain
14 tape manipulations with the Console program.
15
16 Since the Console program interacts with the \bacula{} \bDirector{} through the network,
17 your \bConsole{} and \bDirector{} programs do not necessarily need to run on the
18 same machine.
19
20 In fact, a certain minimal knowledge of the Console program is needed in order
21 for \bacula{} to be able to write on more than one tape, because when \bacula{}
22 requests a new tape, it waits until the user, via the Console program,
23 indicates that the new tape is mounted.
24
25 \section{Console Configuration}
26 \index[general]{Console Configuration}
27 \index[general]{Configuration!Console}
28
29 When the \bConsole{} starts, it reads a standard \bacula{} configuration file
30 named \bfilename{bconsole.conf} or \bfilename{bat.conf} in the case of the \bat{}
31 QT \bConsole{} version from the current directory unless you specify the \textbf{-c}
32 command line option (see below). This file allows default configuration
33 of the \bConsole{}, and at the current time, the only Resource Record defined
34 is the \bresource{Director}, which gives the \bConsole{} the name and address of
35 the \bDirector{}. For more information on configuration of the \bConsole{}
36 program, please see the \bxlink{Console Configuration}{blb:ConsoleConfChapter}{main}{chapter} of the \bmainman{}.
37
38 \section{Running the Console Program}
39 \index[general]{Running the Console Program}
40 \index[general]{Program!Running the Console}
41
42 The \bconsole{} program can be run with the following options:
43 \begin{bVerbatim}
44 Usage: bconsole [-s] [-c config_file] [-d debug_level]
45 -c <file> set configuration file to file
46 -dnn set debug level to nn
47 -n no conio
48 -s no signals
49 -u <nn> set command execution timeout to <nn> seconds
50 -t test - read configuration and exit
51 -? print this message.
52 \end{bVerbatim}
53
54
55 After launching the \bConsole{} program (\bconsolename{}), it will prompt you for the next
56 command with an asterisk (*). Generally, for all commands, you can simply
57 enter the command name and the Console program will prompt you for the
58 necessary arguments. Alternatively, in most cases, you may enter the command
59 followed by arguments. The general format is:
60
61 \begin{bVerbatim}
62 <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
63 \end{bVerbatim}
64
65 where \bhighlight{command} is one of the commands listed below; \bhighlight{keyword} is one
66 of the keywords listed below (usually followed by an argument); and \bhighlight{argument}
67 is the value. The command may be abbreviated to the shortest unique
68 form. If two commands have the same starting letters, the one that will be
69 selected is the one that appears first in the \bcommandname{help} listing. If you want
70 the second command, simply spell out the full command. None of the keywords
71 following the command may be abbreviated.
72
73 For example:
74 \begin{bVerbatim}
75 list files jobid=23
76 \end{bVerbatim}
77
78 will list all files saved for JobId 23. Or:
79
80 \begin{bVerbatim}
81 show pools
82 \end{bVerbatim}
83
84 will display all the \bresourcename{Pool} resource records.
85
86 The maximum command line length is limited to \bvalue{511} characters, so if you
87 are scripting the console, you may need to take some care to limit the
88 line length.
89
90 \section{Stopping the Console Program}
91 \index[general]{Program!Stopping the Console}
92 \index[general]{Stopping the Console Program}
93
94 Normally, you simply enter \bcommandname{quit} or \bcommandname{exit} and the \bConsole{} program
95 will terminate. However, it waits until the \bDirector{} acknowledges the command.
96 If the \bDirector{} is already doing a lengthy command (e.g. \bcommandname{prune}), it may take
97 some time. If you want to immediately terminate the \bConsole{} program, enter the
98 \bcommandname{.quit} command.
99
100 There is currently no way to interrupt a \bConsole{} command once issued (i.e.
101 \texttt{Ctrl-C} does not work). However, if you are at a prompt that is asking you to
102 select one of several possibilities and you would like to abort the command,
103 you can enter a period (\bcommandname{.}), and in most cases, you will either be
104 returned to the main command prompt or if appropriate the previous prompt (in
105 the case of nested prompts). In a few places such as where it is asking for a
106 Volume name, the period will be taken to be the Volume name. In that case, you
107 will most likely be able to cancel at the next prompt.
108
109 \label{blb:keywords}
110 \section{Alphabetic List of Console Keywords}
111 \index[general]{Keywords!Alphabetic List of Console}
112 \index[general]{Alphabetic List of Console Keywords}
113 Unless otherwise specified, each of the following keywords
114 takes an argument, which is specified after the keyword following
115 an equal sign. For example:
116
117 \begin{bVerbatim}
118 jobid=536
119 \end{bVerbatim}
120
121 % Please note, this list is incomplete as it is currently in
122 % the process of being created and is not currently totally in
123 % alphabetic
124 % order ...
125
126 \begin{bdescription}
127 \item [all]
128 Permitted on the \bcommandname{status} and \bcommandname{show} commands to specify all components or
129 resources respectively.
130 \item [frompool]
131 Permitted on the \bcommandname{update volume} command to specify that the volume specified
132 on the command line should be updated with pool parameters.
133 \item [allfrompool=\bbracket{pool}]
134 Permitted on the \bcommandname{update} command to specify that all Volumes in the
135 pool (specified on the command line) should be updated.
136 \item [fromallpools]
137 Permitted on the \bcommandname{update} command to specify that all Volumes in all
138 pools should be updated.
139 \item [before]
140 Used in the \bcommandname{restore} command.
141 \item [bootstrap]
142 Used in the \bcommandname{restore} command.
143 \item [catalog]
144 Allowed in the \bcommandname{use} command to specify the catalog name
145 to be used.
146 \item [catalogs]
147 Used in the \bcommandname{show} command. Takes no arguments.
148 \item [client | fd]
149 \item [clients]
150 Used in the \bcommandname{show}, \bcommandname{list}, and \bcommandname{llist} commands. Takes no arguments.
151 \item [counters]
152 Used in the \bcommandname{show} command. Takes no arguments.
153 \item [current]
154 Used in the \bcommandname{restore} command. Takes no argument.
155 \item [days]
156 Used to define the number of days the \bcommandname{list nextvol} command
157 should consider when looking for jobs to be run. The \bcommandname{days} keyword
158 can also be used on the \bcommandname{status dir} command so that it will display
159 jobs scheduled for the number of days you want.
160 \item [devices]
161 Used in the \bcommandname{show} command. Takes no arguments.
162 \item [dir | director]
163 \item [directors]
164 Used in the \bcommandname{show} command. Takes no arguments.
165 \item [directory]
166 Used in the \bcommandname{restore} command. Its argument specifies the directory
167 to be restored.
168 \item [enabled]
169 This keyword can appear on the \bcommandname{update volume} as well
170 as the \bcommandname{update slots} commands, and can
171 allows one of the following arguments: \bvalue{yes}, \bvalue{true}, \bvalue{no}, \bvalue{false}, \bvalue{archived},
172 \bvalue{0}, \bvalue{1}, \bvalue{2}. Where \bvalue{0} corresponds to no or false, \bvalue{1} corresponds to \bvalue{yes} or \bvalue{true}, and
173 \bvalue{2} corresponds to \bvalue{archived}. Archived volumes will not be used, nor will
174 the Media record in the catalog be pruned. Volumes that are not enabled,
175 will not be used for backup or restore.
176 \item [done]
177 Used in the \bcommandname{restore} command. Takes no argument.
178 \item [file]
179 Used in the \bcommandname{restore} command.
180 \item [files]
181 Used in the \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
182 \item [fileset]
183 \item [filesets]
184 Used in the \bcommandname{show} command. Takes no arguments.
185 \item [help]
186 Used in the \bcommandname{show} command. Takes no arguments.
187 \item [jobs]
188 Used in the \bcommandname{show}, \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
189 \item [jobmedia]
190 Used in the \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
191 \item [jobtotals]
192 Used in the \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
193 \item [jobid]
194 The JobId is the numeric jobid that is printed in the Job
195 Report output. It is the index of the database record for the
196 given job. While it is unique for all the existing Job records
197 in the catalog database, the same JobId can be reused once a
198 Job is removed from the catalog. Probably you will refer
199 specific Jobs that ran using their numeric JobId.
200 \item [job | jobname]
201 The \bcommandname{job} or \bcommandname{jobname} keyword refers to the name you specified
202 in the \bresource{Job}, and hence it refers to any number of
203 Jobs that ran. It is typically useful if you want to list
204 all jobs of a particular name.
205 \item [level]
206 \item [listing]
207 Permitted on the \bcommandname{estimate} command. Takes no argument.
208 \item [limit]
209 \item [messages]
210 Used in the \bcommandname{show} command. Takes no arguments.
211 \item [media]
212 Used in the \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
213 \item [name]
214 Used in the \bcommandname{list object} commands. Can specify an Object name.
215 \item [nextvol | nextvolume]
216 Used in the \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
217 \item [object]
218 Used in the \bcommandname{list} commands. Takes no arguments.
219 \item [objectid]
220 Used in the \bcommandname{list} and \bcommandname{restore} commands. Takes an ObjectId as argument.
221 \item [order]
222 Used in the \bcommandname{list} to sort records. Can take ``ASC'' or ``DESC'' as argument.
223 \item [on]
224 Takes no keyword.
225 \item [off]
226 Takes no keyword.
227 \item [pool]
228 \item [pools]
229 Used in the \bcommandname{show}, \bcommandname{list}, and \bcommandname{llist} commands. Takes no arguments.
230 \item [select]
231 Used in the \bcommandname{restore} command. Takes no argument.
232 \item[limit]
233 Used in the \bcommandname{setbandwidth} command. Takes integer in \texttt{KB/s} unit.
234 \item [storages]
235 Used in the \bcommandname{show} command. Takes no arguments.
236 \item [schedules]
237 Used in the \bcommandname{show} command. Takes no arguments.
238 \item [sd | store | storage]
239 \item [tag] Used in the \bcommandname{list} command. Takes no arguments.
240 \item [ujobid]
241 The \bcommandname{ujobid} is a unique job identification that is printed
242 in the Job Report output. At the current time, it consists
243 of the Job name (from the \bdirective{Name} for the job) appended
244 with the date and time the job was run. This keyword is useful
245 if you want to completely identify the Job instance run.
246 \item [volume]
247 \item [volumes]
248 Used in the \bcommandname{list} and \bcommandname{llist} commands. Takes no arguments.
249 \item [where]
250 Used in the \bcommandname{restore} command.
251 \item [yes]
252 Used in the \bcommandname{restore} command. Takes no argument.
253 \end{bdescription}
254
255 \label{blb:list}
256 \section{Alphabetic List of Console Commands}
257 \index[general]{Commands!Alphabetic List of Console}
258 \index[general]{Alphabetic List of Console Commands}
259 \index[general]{Commands!Alphabetic List of Console}
260 \index[general]{Alphabetic List of Console Commands}
261
262 The following commands are currently implemented:
263
264 \begin{bdescription}
265 \item [{add [pool=\bbracket{pool-name} storage=\bbracket{storage} jobid=\bbracket{JobId}]} ]
266
267 \index[general]{add}
268 This command is used to add Volumes to an existing Pool. That is,
269 it creates the Volume name in the catalog and inserts into the Pool
270 in the catalog, but does not attempt to access the physical Volume.
271 Once
272 added, \bacula{} expects that Volume to exist and to be labeled.
273 This command is not normally used since \bacula{} will
274 automatically do the equivalent when Volumes are labeled. However,
275 there may be times when you have removed a Volume from the catalog
276 and want to later add it back.
277
278 Normally, the \bcommandname{label} command is used rather than this command
279 because the \bcommandname{label} command labels the physical media (tape, disk,
280 DVD, \ldots{}) and does the equivalent of the \bcommandname{add} command. The \bcommandname{add}
281 command affects only the Catalog and not the physical media (data
282 on Volumes). The physical media must exist and be labeled before use
283 (usually with the \bcommandname{label} command). This command can, however, be
284 useful if you wish to add a number of Volumes to the Pool that will be
285 physically labeled at a later time. It can also be useful if you are
286 importing a tape from another site. Please see the \bcommandname{label} command
287 below for the list of legal characters in a Volume name.
288
289 \item [autodisplay on/off]
290 \index[general]{autodisplay on/off}
291 This command accepts \bvalue{on} or \bvalue{off} as an argument, and turns
292 auto-display of messages on or off respectively. The default for the
293 console program is \bcommandname{off}, which means that you will be notified when
294 there are console messages pending, but they will not automatically be
295 displayed.
296
297 When autodisplay is turned off, you must explicitly retrieve the
298 messages with the \bcommandname{messages} command. When \bcommandname{autodisplay} is turned
299 on, the messages will be displayed on the console as they are received.
300
301 \item [automount on/off]
302 \index[general]{automount on/off}
303 This command accepts \bcommandname{on} or \bcommandname{off} as the argument, and turns
304 auto-mounting of the Volume after a \bcommandname{label} command on or off
305 respectively. The default is \bcommandname{on}. If \bcommandname{automount} is turned
306 off, you must explicitly \bcommandname{mount} tape Volumes after a \bcommandname{label} command to
307 use it.
308
309 \item [{cancel [jobid=\bbracket{number} job=\bbracket{job-name} ujobid=\bbracket{unique-jobid}] | [inactive client=<client-name> storage=<storage-name>]}]
310 \index[general]{cancel jobid}
311 This command is used to cancel a job and accepts \bvalue{jobid=nnn} or \bvalue{job=xxx}
312 as an argument where \texttt{nnn} is replaced by the JobId and \texttt{xxx} is
313 replaced by the job name. If you do not specify a keyword, the \bConsole{}
314 program will prompt you with the names of all the active jobs allowing
315 you to choose one.
316
317 Once a Job is marked to be canceled, it may take a bit of time
318 (generally within a minute but up to two hours) before the Job actually
319 terminates, depending on what operations it is doing.
320 Don't be surprised that you receive a Job not found message. That just
321 means that one of the three daemons had already canceled the job.
322 Messages numbered in the 1000's are from the Director, 2000's are from
323 the File daemon and 3000's from the Storage daemon.
324
325 If the Job is still active on the Storage Daemon and/or the File Daemon, but
326 not on the Director, it is possible to stop the Job with the
327 \textbf{inactive} option of the \bcommandname{cancel} command.
328
329 \item [{cloud [storage=\bbracket{sd-name} volume=\bbracket{vol-name} allpools allfrompool pool=\bbracket{p-name} mediatype=\bbracket{type-name} drive=\bbracket{num} slots=\bbracket{num}] [truncate | prune | list | upload]}]
330 The \bcommandname{cloud} \bconsolename{} command allows you to do a number of things with cloud volumes.
331
332 The \bcommandname{truncate} command will attempt to truncate the local cache for the specified Volume.
333
334 The \bcommandname{prune} command will attempt to prune the local cache for the
335 specified Volume. \bacula{} will respect the \bdirective{CacheRetention} volume attribute
336 to determine if the cache can be truncated or not. Only parts that are
337 uploaded to the cloud will be deleted from the cache.
338
339 The \bcommandname{upload} command will attempt to upload the specified Volumes.
340
341 The \bcommandname{list} command will list volumes stored in the Cloud. If a
342 volume name is specified, the command will list all parts for the given
343 volume.
344
345 \item [{create [pool=\bbracket{pool-name}]}]
346 \index[general]{create pool}
347 This command is not normally used as the Pool records are automatically
348 created by the \bDirector{} when it starts based on what it finds in
349 the conf file. If needed, this command can be
350 to create a \bPool{} record in the database using the
351 \bresource{Pool} record defined in the \bDirector{}'s configuration file. So
352 in a sense, this command simply transfers the information from the \bresource{Pool}
353 in the configuration file into the \bCatalog{}. Normally this
354 command is done automatically for you when the \bDirector{} starts providing
355 the \bPool{} is referenced within a \bresource{Job}. If you use this command
356 on an existing \bPool{}, it will automatically update the \bCatalog{} to have
357 the same information as the \bresource{Pool}. After creating a \bPool{}, you
358 will most likely use the \bcommandname{label} command to label one or more
359 volumes and add their names to the Media database.
360
361 When starting a \bJob{}, if \bacula{} determines that there is no \bPool{} record
362 in the database, but there is a \bresource{Pool} of the appropriate name,
363 it will create it for you. If you want the \bPool{} record to appear in the
364 database immediately, simply use this command to force it to be created.
365
366 \item [{delete [volume=\bbracket{vol-name} pool=\bbracket{pool-name} job jobid=\bbracket{id} object [objectid=id]]}]
367 \index[general]{delete}
368 The \bcommandname{delete} command is used to delete a \bVolume{}, \bPool{} \bJob{}, Object, Snapshot or \bClient{} record from
369 the \bCatalog{} as well as all associated catalog Volume records that were
370 created. This command operates only on the \bCatalog{} database and has no
371 effect on the actual data written to a \bVolume{}. This command can be
372 dangerous and we strongly recommend that you do not use it unless you
373 know what you are doing.
374
375 If the keyword \bvalue{Volume} appears on the command line, the named
376 \bVolume{} will be deleted from the \bCatalog{}, if the keyword \bvalue{Pool}
377 appears on the command line, a \bPool{} will be deleted, if the keyword \bvalue{Object} appears on the
378 command line, an Object and all of its associated records (File) will be deleted from the catalog, and
379 if the keyword \bvalue{Job} appears on the command line, a \bJob{} and all of its associated
380 records (File and JobMedia) will be deleted from the catalog. The full
381 form of this command is:
382
383 \begin{bVerbatim}
384 delete pool=<pool-name>
385 \end{bVerbatim}
386 or
387 \begin{bVerbatim}
388 delete volume=<volume-name> pool=<pool-name>
389 \end{bVerbatim}
390 or
391 \begin{bVerbatim}
392 delete JobId=<job-id> JobId=<job-id2> ...
393 \end{bVerbatim}
394 or
395 \begin{bVerbatim}
396 delete JobId=n,m,o-r,t ...
397 \end{bVerbatim}
398 or
399 \begin{bVerbatim}
400 delete client=xxx-fd
401 \end{bVerbatim}
402 or
403 \begin{bVerbatim}
404 delete snapshot
405 \end{bVerbatim}
406 or
407 \begin{bVerbatim}
408 delete object [objectid=id [all]] [category=obj\_cat] [type=obj\_type] [name=obj\_name] [uuid=obj\_uuid] [source=obj\_source]
409 \end{bVerbatim}
410
411
412 The first form deletes a \bPool{} record from the catalog database. The
413 second form deletes a \bVolume{} record from the specified pool in the
414 \bCatalog{} database. The third form deletes the specified \bJob{} record from
415 the catalog database. The fourth form deletes \bJobId{} records for JobIds
416 \bvalue{n, m, o, p, q, r} and \bvalue{t}. Where each one of the \bvalue{n,m,\ldots{}} is, of course, a
417 number. That is a \bcommandname{delete jobid} accepts lists and ranges of
418 jobids.
419
420 The deletion of a \bClient{} record will prune all job records associated
421 with the Client. This command is possible only of the \bClient{} resource
422 is no longer defined in the Director configuration file.
423
424 The deletion of a Snapshot record can be done with the sixth command.
425
426 The deletion of an Object records can be done with the last command. Different filters can be used along with
427 'delete object' command: category, type, name, uuid or source. Passing specific object id can be also used as a filter
428 to delete many objects at once. Following command will delete all objects records with the same category,
429 type, name, uuid and source as object with given id.
430
431 \begin{bVerbatim}
432 delete object objectid=1 all
433 \end{bVerbatim}
434
435 \item [disable job\bbracket{job-name}]
436 \index[general]{disable}
437 This command permits you to disable a \bJob{} for automatic scheduling.
438 The job may have been previously enabled with the \bresource{Job}
439 \bdirective{Enabled} or using the console \bcommand{enable}.
440 The next time the \bDirector{} is restarted,
441 the \bvalue{Enable}/\bvalue{Disable} state will be set to the value in the \bresource{Job}
442 (default \bvalue{enabled}) as defined in the \bfilename{bacula-dir.conf} file.
443
444 \item [disable job all]
445 \index[general]{disable}
446 This command permits you to disable all Jobs for automatic scheduling.
447 The next time the \bDirector{} is restarted,
448 the \bvalue{Enable}/\bvalue{Disable} state will be set to the value in the \bresource{Job}
449 (default \bvalue{enabled}) as defined in the \bfilename{bacula-dir.conf} file.
450
451 \item [enable job\bbracket{job-name}]
452 \index[general]{enable}
453 This command permits you to enable a \bJob{} for automatic scheduling.
454 The job may have been previously disabled with the \bresource{Job}
455 \bdirective{Enabled} or using the console \bcommand{disable}.
456 The next time the \bDirector{} is restarted,
457 the \bvalue{Enable}/\bvalue{Disable} state will be set to the value in the \bresource{Job}
458 (default \bvalue{enabled}) as defined in the \bfilename{bacula-dir.conf} file.
459
460 \item [enable job all]
461 \index[general]{disable}
462 This command permits you to enable all Jobs for automatic scheduling.
463 It does not enable jobs which have \bdirective{Disabled} directive.
464 The next time the \bDirector{} is restarted,
465 the \bvalue{Enable}/\bvalue{Disable} state will be set to the value in the \bresource{Job}
466 (default \bvalue{enabled}) as defined in the \bfilename{bacula-dir.conf} file.
467
468 \label{blb:estimate}
469 \item [estimate]
470 \index[general]{estimate}
471 Using this command, you can get an idea how many files will be backed
472 up, or if you are unsure about your Include statements in your \bFileSet{},
473 you can test them without doing an actual backup. The default is to
474 assume a Full backup. However, you can override this by specifying a
475 \bvalue{level=Incremental} or \bvalue{level=Differential} on the command line.
476 A \bJob{} name must be specified or you will be prompted for one, and
477 optionally a \bClient{} and \bFileSet{} may be specified on the command line.
478 It then contacts the client which computes the number of files and bytes
479 that would be backed up. Please note that this is an estimate
480 calculated from the number of blocks in the file rather than by reading
481 the actual bytes. As such, the estimated backup size will generally be
482 larger than an actual backup.
483
484 The \bcommandname{estimate} command can use the accurate code to detect changes
485 and give a better estimation. You can set the accurate behavior on command
486 line using \bvalue{accurate=yes/no} or use the \bJob{} setting as default value.
487
488 Optionally you may specify the keyword \bkeyword{listing} in which case, all the
489 files to be backed up will be listed. Note, it could take quite some time to
490 display them if the backup is large. The full form is:
491
492 \begin{bVerbatim}
493 estimate job=<job-name> listing client=<client-name> accurate=<yes/no>
494 fileset=<fileset-name> level=<level-name>
495 \end{bVerbatim}
496
497 Specification of the \bkeyword{job} is sufficient, but you can also override the
498 \bkeyword{client}, \bkeyword{fileset}, \bkeyword{accurate} and/or \bkeyword{level} by specifying them on the \bcommandname{estimate}
499 command line.
500
501
502 As an example, you might do:
503
504 \begin{bVerbatim}
505 @output /tmp/listing
506 estimate job=NightlySave listing level=Incremental
507 @output
508 \end{bVerbatim}
509
510 which will do a full listing of all files to be backed up for the Job \textbf{NightlySave}
511 during an Incremental save and put it in the file \bfilename{/tmp/listing}.
512 Note, the byte estimate provided by this command is
513 based on the file size contained in the directory item. This can give
514 wildly incorrect estimates of the actual storage used if there are
515 sparse files on your systems. Sparse files are often found on 64 bit
516 systems for certain system files. The size that is returned is the size
517 \bacula{} will backup if the sparse option is not specified in the \bFileSet{}.
518 There is currently no way to get an estimate of the real file size that
519 would be found should the sparse option be enabled.
520
521 \item [exit]
522 \index[general]{exit}
523 This command terminates the \bConsole{} program.
524
525 \item [gui]
526 \index[general]{gui}
527 Invoke the non-interactive gui mode.
528 \begin{bVerbatim}
529 gui [on|off]
530 \end{bVerbatim}
531
532 \item [help]
533 \index[general]{help}
534 This command displays the list of commands available.
535
536 \item [label]
537 \index[general]{label}
538 \index[general]{relabel}
539 This command is used to label physical volumes. The full form of this command
540 is:
541
542 \begin{bVerbatim}
543 label storage=<storage-name> volume=<volume-name>
544 slot=<slot>
545 \end{bVerbatim}
546
547 If you leave out any part, you will be prompted for it. The media type
548 is automatically taken from the \bresource{Storage} definition that you
549 supply. Once the necessary information is obtained, the \bConsole{} program
550 contacts the specified \bStorage{} daemon and requests that the \bVolume{} be
551 labeled. If the Volume labeling is successful, the Console program will
552 create a \bVolume{} record in the appropriate \bPool{}.
553
554 The Volume name is restricted to letters, numbers, and the special
555 characters hyphen (-), underscore (\_), colon (\string:), and
556 period (.). All other characters including a space are invalid.
557 This restriction is to ensure good readability of Volume names to reduce
558 operator errors.
559
560 Please note, when labeling a blank tape, \bacula{} will get \textbf{read I/O error}
561 when it attempts to ensure that the tape is not already labeled. If
562 you wish to avoid getting these messages, please write an EOF mark on
563 your tape before attempting to label it:
564
565 \begin{bVerbatim}
566 mt rewind
567 mt weof
568 \end{bVerbatim}
569
570 The \bcommandname{label} command can fail for a number of reasons:
571
572 \begin{benumerate}
573 \item The \bVolume{} name you specify is already in the Volume database.
574
575 \item The \bStorage{} daemon has a tape or other Volume already mounted on the
576 device, in which case you must \bcommandname{unmount} the device, insert a blank
577 tape, then do the \bcommandname{label} command.
578
579 \item The Volume in the device is already a \bacula{} labeled Volume. (\bacula{} will
580 never relabel a \bacula{} labeled Volume unless it is recycled and you use the
581 \bcommandname{relabel} command).
582
583 \item There is no Volume in the drive.
584 \end{benumerate}
585
586 There are two ways to relabel a volume that already has a \bacula{} label. The
587 brute force method is to write an end of file mark on the tape using the
588 system \btool{mt} program, something like the following:
589
590 \begin{bVerbatim}
591 mt -f /dev/st0 rewind
592 mt -f /dev/st0 weof
593 \end{bVerbatim}
594
595 For a disk volume, you would manually delete the Volume.
596
597 Then you use the \bcommandname{label} command to add a new label. However, this could
598 leave traces of the old volume in the catalog.
599
600 The preferable method to relabel a Volume is to first \bcommandname{purge} the volume,
601 either automatically, or explicitly with the \bcommandname{purge} command, then use
602 the \bcommandname{relabel} command described below.
603
604 If your autochanger has barcode labels, you can label all the Volumes in
605 your autochanger one after another by using the \bcommandname{label barcodes}
606 command. For each tape in the changer containing a barcode, \bacula{} will
607 mount the tape and then label it with the same name as the barcode. An
608 appropriate Media record will also be created in the catalog. Any barcode
609 that begins with the same characters as specified on the
610 ``\bvalueddirective{CleaningPrefix}{xxx}'' directive in the \bDirector{}'s \bresource{Pool}, will be
611 treated as a cleaning tape, and will not be labeled. However, an entry for
612 the cleaning tape will be created in the catalog. For example with:
613
614 \begin{bVerbatim}
615 Pool {
616 Name ...
617 Cleaning Prefix = "CLN"
618 }
619 \end{bVerbatim}
620
621 Any slot containing a barcode of \texttt{CLNxxxx} will be treated as a cleaning tape
622 and will not be mounted. Note, the full form of the command is:
623
624 \begin{bVerbatim}
625 label storage=xxx pool=yyy slots=1-5,10 barcodes
626 \end{bVerbatim}
627
628 \item [list]
629 \index[general]{list}
630 The \bcommandname{list} command lists the requested contents of the Catalog. The
631 various fields of each record are listed on a single line. The various
632 forms of the list command are:
633 \begin{bVerbatim}
634 list events
635
636 list jobs
637
638 list jobid=<id> (list jobid id)
639
640 list jobs joberrors (list jobs with errors)
641
642 list jobs jobstatus=f (list jobs with jobstatus f)
643
644 list jobs limit=10 order=desc (list the last 10 jobs)
645
646 list jobs limit=10 order=asc (list the first 10 jobs)
647
648 list jobs client=xxx (list jobs for client xxx)
649
650 list copies (list copy jobs)
651
652 list ujobid=<unique job name> (list job with unique name)
653
654 list job=<job-name> (list all jobs with "job-name")
655
656 list jobname=<job-name> (same as above)
657
658 In the above, you can add "limit=nn" to limit the output to
659 nn jobs.
660
661 list joblog jobid=<id> (list job output if recorded in the catalog)
662
663 list jobmedia
664
665 list jobmedia jobid=<id>
666
667 list jobmedia job=<job-name>
668
669 list files jobid=<id>
670
671 list files job=<job-name>
672
673 In the above, you can add type=<all|deleted> to see all file records or only
674 deleted records.
675
676 list files type=<deleted|all> jobid=<id>
677
678 list pools
679
680 list clients
681
682 list jobtotals
683
684 list objects (list plugin objects)
685
686 list objects jobid=<id>
687
688 list object client=<client> (list plugin objects of specified client)
689
690 list object type=<type> (list plugin objects of specified type)
691
692 list objects category=<category> (list plugin objects of specified category)
693
694 list objects limit=10 order=desc (list the last 10 objects)
695
696 list objects limit=10 order=asc (list the first 10 objects)
697
698 list volumes
699
700 list volumes jobid=<id>
701
702 list volumes pool=<pool-name>
703
704 list volumes job=<job-name>
705
706 list volume=<volume-name>
707
708 list nextvolume job=<job-name>
709
710 list nextvol job=<job-name>
711
712 list nextvol job=<job-name> days=nnn
713 \end{bVerbatim}
714
715 What most of the above commands do should be more or less obvious. In
716 general if you do not specify all the command line arguments, the
717 command will prompt you for what is needed.
718
719 The \bcommandname{list nextvol} command will print the Volume name to be used by
720 the specified job. You should be aware that exactly what Volume will be
721 used depends on a lot of factors including the time and what a prior job
722 will do. It may fill a tape that is not full when you issue this
723 command. As a consequence, this command will give you a good estimate
724 of what Volume will be used but not a definitive answer. In addition,
725 this command may have certain side effect because it runs through the
726 same algorithm as a job, which means it may automatically purge or
727 recycle a Volume. By default, the job specified must run within the
728 next two days or no volume will be found. You can, however, use the
729 \bkeyword{days=nnn} specification to specify up to 50 days. For example,
730 if on Friday, you want to see what Volume will be needed on Monday,
731 for job MyJob, you would use \bcommandname{list nextvol job=MyJob days=3}.
732
733 If you wish to add specialized commands that list the contents of the
734 catalog, you can do so by adding them to the \bfilename{query.sql} file.
735 However, this takes some knowledge of programming \btool{SQL}. Please see the
736 \bcommandname{query} command below for additional information. See below for
737 listing the full contents of a catalog record with the \bcommandname{llist}
738 command.
739
740 As an example, the command \bcommandname{list pools} might produce the following
741 output:
742
743 \begin{bVerbatim}
744 +------+---------+---------+---------+----------+-------------+
745 | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
746 +------+---------+---------+---------+----------+-------------+
747 | 1 | Default | 0 | 0 | Backup | * |
748 | 2 | Recycle | 0 | 8 | Backup | File |
749 +------+---------+---------+---------+----------+-------------+
750 \end{bVerbatim}
751
752 As mentioned above, the \bcommandname{list} command lists what is in the
753 database. Some things are put into the database immediately when \bacula{}
754 starts up, but in general, most things are put in only when they are
755 first used, which is the case for a Client as with Job records, etc.
756
757 \bacula{} should create a client record in the database the first time you
758 run a job for that client. Doing a \bcommandname{status} will not cause a
759 database record to be created. The client database record will be
760 created whether or not the job fails, but it must at least start. When
761 the Client is actually contacted, additional info from the client will
762 be added to the client record (a \btool{uname -a} output).
763
764 If you want to see what \bresources{Client} you have available in your conf
765 file, you use the Console command \bcommandname{show clients}.
766
767 \item [llist]
768 \index[general]{llist}
769 The \bcommandname{llist} or ``long list'' command takes all the same arguments that the
770 \bcommandname{list} command described above does. The difference is that the \bcommandname{llist}
771 command \bcommandname{list} the full contents of each database record selected. It
772 does so by listing the various fields of the record vertically, with one
773 field per line. It is possible to produce a very large number of output
774 lines with this command.
775
776 If instead of the \bcommandname{list pools} as in the example above, you enter
777 \bcommandname{llist pools} you might get the following output:
778
779 \begin{bVerbatim}
780 PoolId: 1
781 Name: Default
782 NumVols: 0
783 MaxVols: 0
784 UseOnce: 0
785 UseCatalog: 1
786 AcceptAnyVolume: 1
787 VolRetention: 1,296,000
788 VolUseDuration: 86,400
789 MaxVolJobs: 0
790 MaxVolBytes: 0
791 AutoPrune: 0
792 Recycle: 1
793 PoolType: Backup
794 LabelFormat: *
795
796 PoolId: 2
797 Name: Recycle
798 NumVols: 0
799 MaxVols: 8
800 UseOnce: 0
801 UseCatalog: 1
802 AcceptAnyVolume: 1
803 VolRetention: 3,600
804 VolUseDuration: 3,600
805 MaxVolJobs: 1
806 MaxVolBytes: 0
807 AutoPrune: 0
808 Recycle: 1
809 PoolType: Backup
810 LabelFormat: File
811 \end{bVerbatim}
812
813 \item [messages]
814 \index[general]{messages}
815 This command causes any pending console messages to be immediately displayed.
816
817 \item [memory]
818 \index[general]{memory}
819 Print current memory usage.
820
821
822 \item [mount]
823 \index[general]{mount}
824 The \bcommandname{mount} command is used to get \bacula{} to read a volume on a physical
825 device. It is a way to tell \bacula{} that you have mounted a tape and
826 that \bacula{} should examine the tape. This command is normally
827 used only after there was no Volume in a drive and \bacula{} requests you to mount a new
828 Volume or when you have specifically unmounted a Volume with the \bcommandname{unmount}
829 console command, which causes \bacula{} to close the drive. If
830 you have an autoloader, the \bcommandname{mount} command will not cause \bacula{} to
831 operate the autoloader unless you specify a \bkeyword{slot} and possibly a
832 \bkeyword{drive}. The various forms of the mount command are:
833 \begin{bVerbatim}
834 mount storage=<storage-name> [ slot=<num> ] [ drive=<num> ]
835 \end{bVerbatim}
836
837
838 \begin{bVerbatim}
839 mount [ jobid=<id> | job=<job-name> ]
840 \end{bVerbatim}
841 If you have specified \bdirectivename{Automatic Mount = yes} in the Storage daemon's
842 \bresource{Device}, under most circumstances, \bacula{} will automatically access
843 the Volume unless you have explicitly \bcommandname{unmount}ed it in the Console
844 program.
845
846 \label{blb:ManualPruning}
847 \item [prune]
848 \index[general]{prune}
849 The \bcommandname{prune} command allows you to safely remove expired database records from
850 Jobs, Volumes and Statistics. This command works only on the Catalog
851 database and does not affect data written to Volumes. In all cases, the
852 \bcommandname{prune} command applies a retention period to the specified records. You can
853 prune expired File entries from Job records; you can prune expired Job
854 records from the database, and you can prune both expired Job and File
855 records from specified Volumes.
856 \begin{bVerbatim}
857 prune files|jobs|volume|stats client=<client-name>
858 volume=<volume-name>
859 \end{bVerbatim}
860 For a Volume to be pruned, the \textbf{VolStatus} must be \bstatus{Full}, \bstatus{Used}, or
861 \bstatus{Append}, otherwise the pruning will not take place.
862 \smallskip
863
864 With the \bkeyword{all} keyword, all combination of \bresourcename{Client}/\bresourcename{Pool} present
865 in the \bJob{} table will be pruned. \bcommandname{prune jobs all yes}
866
867
868 \item [purge]
869 \index[general]{purge}
870 The \bcommandname{purge} command will delete associated Catalog database records from
871 Jobs and Volumes without considering the retention period. \bcommandname{purge}
872 works only on the Catalog database and does not affect data written to
873 Volumes. This command can be dangerous because you can delete catalog
874 records associated with current backups of files, and we recommend that
875 you do not use it unless you know what you are doing. The permitted
876 forms of \bcommandname{purge} are:
877 \begin{bVerbatim}
878 purge files jobid=<jobid>|job=<job-name>|client=<client-name>
879 \end{bVerbatim}
880 \begin{bVerbatim}
881 purge jobs client=<client-name> (of all jobs)
882 \end{bVerbatim}
883 \begin{bVerbatim}
884 purge volume|volume=<vol-name> (of all jobs)
885 \end{bVerbatim}
886 For the \bcommandname{purge} command to work on Volume Catalog database records the
887 {\bf VolStatus} must be \bvalue{Append}, \bvalue{Full}, \bvalue{Used}, or \bvalue{Error.}
888
889 The actual data written to the Volume will be unaffected by this command unless
890 you are using the \bdirectivename{ActionOnPurge=Truncate} option on those Media.
891
892 To ask \bacula{} to truncate your \texttt{Purged} volumes, you need to use the
893 following command in interactive mode or in a \bresourcename{RunScript}:
894 \begin{bVerbatim}
895 * purge volume action=truncate storage=File allpools
896
897 # or by default, action=all
898 * purge volume action storage=File pool=Default
899 \end{bVerbatim}
900
901 This is possible to specify the volume name, the media type, the pool, the
902 storage, etc\dots (see \bcommandname{help purge}) Be sure that your storage device is
903 idle when you decide to run this command.
904
905 \item [query]
906 \index[general]{query}
907 This command reads a predefined SQL query from the query file (the name and
908 location of the query file is defined with the \bresource{QueryFile} record in
909 the Director's configuration file). You are prompted to select a query from
910 the file, and possibly enter one or more parameters, then the command is
911 submitted to the Catalog database SQL engine.
912
913 The following queries are currently available (version 2.2.7):
914
915 \begin{bVerbatim}
916 Available queries:
917 1: List up to 20 places where a File is saved regardless of the directory
918 2: List where the most recent copies of a file are saved
919 3: List last 20 Full Backups for a Client
920 4: List all backups for a Client after a specified time
921 5: List all backups for a Client
922 6: List Volume Attributes for a selected Volume
923 7: List Volumes used by selected JobId
924 8: List Volumes to Restore All Files
925 9: List Pool Attributes for a selected Pool
926 10: List total files/bytes by Job
927 11: List total files/bytes by Volume
928 12: List Files for a selected JobId
929 13: List Jobs stored on a selected MediaId
930 14: List Jobs stored for a given Volume name
931 15: List Volumes Bacula thinks are in changer
932 16: List Volumes likely to need replacement from age or errors
933 Choose a query (1-16):
934 \end{bVerbatim}
935
936 \item [quit]
937 \index[general]{quit}
938 This command terminates the console program. The console program sends the
939 {\bf quit} request to the Director and waits for acknowledgment. If the
940 Director is busy doing a previous command for you that has not terminated, it
941 may take some time. You may quit immediately by issuing the \bcommandname{.quit}
942 command (i.e. quit preceded by a period).
943
944 \item [relabel]
945 \index[general]{relabel}
946 This command is used to label physical volumes. The full form of this
947 command is:
948 \begin{bVerbatim}
949 relabel storage=<storage-name> oldvolume=<old-volume-name>
950 volume=<newvolume-name>
951 \end{bVerbatim}
952 If you leave out any part, you will be prompted for it. In order for
953 the Volume (old-volume-name) to be relabeled, it must be in the catalog,
954 and the volume status must be marked \bvalue{Purged} or \bvalue{Recycle}.
955 This happens automatically as a result of applying retention periods, or
956 you may explicitly purge the volume using the \bcommandname{purge} command.
957
958 Once the volume is physically relabeled, the old data previously written
959 on the Volume is lost and cannot be recovered.
960
961 \item [release]
962 \index[general]{release}
963 This command is used to cause the Storage daemon to rewind (release) the
964 current tape in the drive, and to re-read the Volume label the next time
965 the tape is used.
966 \begin{bVerbatim}
967 release storage=<storage-name>
968 \end{bVerbatim}
969 After a \bcommandname{release} command, the device is still kept open by \bacula{} (unless
970 \bdirectivename{Always Open} is set to \bvalue{No} in the Storage Daemon's configuration) so it
971 cannot be used by another program. However, with some tape drives, the
972 operator can remove the current tape and to insert a different one, and
973 when the next Job starts, \bacula{} will know to re-read the tape label to
974 find out what tape is mounted. If you want to be able to use the drive
975 with another program (e.g. \btool{mt}), you must use the \bcommandname{unmount}
976 command to cause \bacula{} to completely release (close) the device.
977
978 \item [reload]
979 \index[general]{reload}
980 The \bcommandname{reload} command causes the Director to re-read its configuration
981 file and apply the new values. The new values will take effect
982 immediately for all new jobs. However, if you change schedules,
983 be aware that the scheduler pre-schedules jobs up to two hours in
984 advance, so any changes that are to take place during the next two
985 hours may be delayed. Jobs that have already been scheduled to run
986 (i.e. surpassed their requested start time) will continue with the
987 old values. New jobs will use the new values. Each time you issue
988 a \bcommandname{reload} command while jobs are running, the old config values
989 will keptf until all jobs that were running before issuing
990 the reload terminate, at which time the old config values will
991 be released from memory. As a default a maximum number of
992 32 reload requests that can be made, which is generally sufficient.
993 In the case that you make a very large number of reload requests,
994 you may use the {\bf Maximum Reload Requests} directive in the
995 Director resource of {\bf bacula-dir.conf} to set a larger maximum
996 to that value you wish.
997
998
999 \label{blb:restart_command}
1000 \item [restart]
1001 \index[general]{restart}
1002 \index[general]{resume}
1003 The \bcommandname{restart} command allows console users to restart
1004 a canceled, failed, or incomplete Job. For canceled and failed
1005 Jobs, the Job will restart from the beginning. For incomplete
1006 Jobs the Job will restart at the point that it was stopped either
1007 by a stop command or by some recoverable failure.
1008 \smallskip
1009
1010 \label{blb:resume_command}
1011 \item [resume]
1012 \index[general]{resume}
1013 The \bcommandname{resume} command does exactly the same thing as a
1014 \bcommandname{restart} command, but for some users the
1015 name may be more logical because in general the
1016 \bcommandname{restart} command is used to resume running
1017 a Job that was incomplete.
1018
1019 \label{blb:restore_command}
1020 \item [restore]
1021 \index[general]{restore}
1022 The \bcommandname{restore} command allows you to select one or more Jobs (JobIds) to be
1023 restored using various methods. Once the JobIds are selected, the File
1024 records for those Jobs are placed in an internal \bacula{} directory tree,
1025 and the restore enters a file selection mode that allows you to
1026 interactively walk up and down the file tree selecting individual files
1027 to be restored. This mode is somewhat similar to the standard Unix \btool{restore}
1028 program's interactive file selection mode.
1029 \begin{bVerbatim}
1030 restore storage=<storage-name> client=<backup-client-name> where=<path>
1031 pool=<pool-name> fileset=<fileset-name>
1032 restoreclient=<restore-client-name> objectid=<id>
1033 restorejob=<job-name> jobuser=<user-name> jobgroup=<group-name>
1034 select current all done
1035 \end{bVerbatim}
1036 Where \bkeyword{current}, if specified, tells the \bcommandname{restore} command to
1037 automatically select a restore to the most current backup. If not
1038 specified, you will be prompted. The \bkeyword{all} specification tells the
1039 \bcommandname{restore} command to restore all files. If it is not specified, you will
1040 be prompted for the files to restore. For details of the \bcommandname{restore}
1041 command, please see the \bxlink{Restore}{blb:RestoreChapter}{main}{chapter}
1042 of the \bmainman{}.
1043
1044 The client keyword initially specifies the client from which the backup
1045 was made and the client to which the restore will be make. However,
1046 if the \bkeyword{restoreclient} keyword is specified, then the restore is written
1047 to that client.
1048
1049 The restore job rarely needs to be specified, as bacula installations
1050 commonly only have a single restore job configured. However, for certain
1051 cases, such as a varying list of \bresourcename{RunScript} specifications, multiple
1052 restore jobs may be configured. The \bkeyword{restorejob} argument allows the
1053 selection of one of these jobs.
1054
1055 \item [run]
1056 \index[general]{run}
1057 This command allows you to schedule jobs to be run immediately. The full form of the command is:
1058 \begin{bVerbatim}
1059 run job=<job-name> client=<client-name>
1060 fileset=<FileSet-name> level=<level-keyword>
1061 storage=<storage-name> where=<directory-prefix>
1062 when=<universal-time-specification> spooldata=yes|no yes
1063 \end{bVerbatim}
1064 Any information that is needed but not specified will be listed for
1065 selection, and before starting the job, you will be prompted to accept,
1066 reject, or modify the parameters of the job to be run, unless you have
1067 specified \bvalue{yes}, in which case the job will be immediately sent to
1068 the scheduler.
1069
1070 On my system, when I enter a run command, I get the following prompt:
1071
1072 \begin{bVerbatim}
1073 A job name must be specified.
1074 The defined Job resources are:
1075 1: Matou
1076 2: Polymatou
1077 3: Rufus
1078 4: Minimatou
1079 5: Minou
1080 6: PmatouVerify
1081 7: MatouVerify
1082 8: RufusVerify
1083 9: Watchdog
1084 Select Job resource (1-9):
1085 \end{bVerbatim}
1086
1087 If I then select number 5, I am prompted with:
1088
1089 \begin{bVerbatim}
1090 Run Backup job
1091 JobName: Minou
1092 FileSet: Minou Full Set
1093 Level: Incremental
1094 Client: Minou
1095 Storage: DLTDrive
1096 Pool: Default
1097 When: 2003-04-23 17:08:18
1098 OK to run? (yes/mod/no):
1099
1100 \end{bVerbatim}
1101
1102 If I now enter \bvalue{yes}, the Job will be run. If I enter \bvalue{mod}, I will
1103 be presented with the following prompt:
1104
1105 \begin{bVerbatim}
1106 Parameters to modify:
1107 1: Level
1108 2: Storage
1109 3: Job
1110 4: FileSet
1111 5: Client
1112 6: When
1113 7: Pool
1114 Select parameter to modify (1-7):
1115 \end{bVerbatim}
1116
1117 If you wish to start a job at a later time, you can do so by setting the When
1118 time. Use the \bvalue{mod} option and select \bvalue{When} (no. 6). Then enter the
1119 desired start time in \texttt{YYYY-MM-DD HH:MM:SS} format.
1120
1121 The \bkeyword{spooldata} argument of the run command cannot be modified through the menu
1122 and is only accessible by setting its value on the intial command line. If
1123 no spooldata flag is set, the job, storage or schedule flag is used.
1124
1125 \item[setbandwidth]
1126 \index[general]{setbandwidth}
1127 This command is used to limit the bandwidth of a running job or a client.
1128 \begin{bVerbatim}
1129 setbandwidth limit=<nb> [ jobid=<id> | client=<cli> ]
1130 \end{bVerbatim}
1131 \item [setdebug]
1132 \index[general]{setdebug}
1133 \index[general]{Debugging}
1134 \index[general]{Debugging Win32}
1135 \index[general]{Windows!debugging}
1136 This command is used to set the debug level in each daemon. The form of this
1137 command is:
1138 \begin{bVerbatim}
1139 setdebug level=nn [trace=0/1 client=<client-name> | dir | director |
1140 storage=<storage-name> | all | options=0cidtTlp | tags=<tags>]
1141 \end{bVerbatim}
1142 If \bkeyword{trace=1} is set, then tracing will be enabled, and the daemon will be
1143 placed in trace mode, which means that all debug output as set by the
1144 debug level will be directed to the file \bfilename{bacula.trace} in the
1145 current directory of the daemon. Normally, tracing is needed only for
1146 Win32 clients where the debug output cannot be written to a terminal or
1147 redirected to a file. When tracing, each debug output message is
1148 appended to the trace file. You must explicitly delete the file when
1149 you are done.
1150 \smallskip
1151
1152 If \bkeyword{options} parameter is set, the following arguments can be used
1153 to control debug functions.
1154 \begin{bdescription}
1155 \item [0] clear debug flags
1156 \item [i] Turn off, ignore bwrite() errors on restore on File Daemon
1157 \item [d] Turn off decomp of BackupRead() streams on File Daemon
1158 \item [t] Turn on timestamp in traces
1159 \item [T] Turn off timestamp in traces
1160 \item [c] Truncate trace file if trace file is activated
1161 \item [l] Turn on recoding events on P() and V()
1162 \item [p] Turn on the display of the event ring when doing a lockdump
1163 \end{bdescription}
1164 \smallskip
1165
1166 It is now possible to use \emph{class} of debug messages called \texttt{tags}
1167 to control the debug output of \bacula{} daemons.
1168
1169 \begin{bdescription}
1170 \item [all] Display all debug messages
1171 \item [bvfs] Display BVFS debug messages
1172 \item [sql] Display SQL related debug messages
1173 \item [memory] Display memory and poolmem allocation messages
1174 \item [scheduler] Display scheduler related debug messages
1175 \end{bdescription}
1176
1177 \begin{bVerbatim}
1178 * setdebug level=10 tags=bvfs,sql,memory
1179 * setdebug level=10 tags=!bvfs
1180 \end{bVerbatim}
1181
1182 The \texttt{tags} option is composed of a list of tags, tags are separated by
1183 ``,'' or ``+'' or ``-'' or ``!''. To disable a specific tag, use ``-'' or ``!''
1184 in front of the tag.
1185
1186 \item [setip]
1187 \index[general]{setip}
1188 Sets new client address --- if authorized.
1189
1190 A console is authorized to use the \bcommandname{SetIP} command only if it has a
1191 \bresource{Console} definition in both the Director and the Console. In
1192 addition, if the console name, provided on the \bdirective{Name},
1193 must be the same as a Client name, the user of that console is permitted
1194 to use the \bcommandname{SetIP} command to change the \bdirective{Address} in the
1195 Director's \bresource{Client} to the IP address of the Console. This
1196 permits portables or other machines using DHCP (non-fixed IP addresses)
1197 to ``notify'' the Director of their current IP address.
1198
1199
1200
1201 \item [show]
1202 \index[general]{show}
1203 The \bcommandname{show} command will list the \bresourceq{Director} records as defined in
1204 the Director's configuration file (normally \bfilename{bacula-dir.conf}).
1205 This command is used mainly for debugging purposes by developers.
1206 The following keywords are accepted on the
1207 \bcommandname{show} command line:\bkeyword{catalogs}, \bkeyword{clients}, \bkeyword{counters}, \bkeyword{devices}, \bkeyword{directors}
1208 \bkeyword{filesets}, \bkeyword{jobs}, \bkeyword{messages}, \bkeyword{pools}, \bkeyword{schedules}, \bkeyword{storages}, \bkeyword{all}, \bkeyword{help}.
1209 Please don't confuse this command
1210 with the \bcommandname{list}, which displays the contents of the catalog.
1211
1212 \item [sqlquery]
1213 \index[general]{sqlquery}
1214 The \bcommandname{sqlquery} command puts the Console program into SQL query mode where
1215 each line you enter is concatenated to the previous line until a
1216 semicolon (;) is seen. The semicolon terminates the command, which is
1217 then passed directly to the SQL database engine. When the output from
1218 the SQL engine is displayed, the formation of a new SQL command begins.
1219 To terminate SQL query mode and return to the Console command prompt,
1220 you enter a period (.) in column 1.
1221
1222 Using this command, you can query the SQL catalog database directly.
1223 Note you should really know what you are doing otherwise you could
1224 damage the catalog database. See the \bcommandname{query} command above for
1225 simpler and safer way of entering SQL queries.
1226
1227 Depending on what database engine you are using (\mysql{} or \postgresql{}), you will have somewhat different SQL commands available. For
1228 more detailed information, please refer to the \mysql{}, \postgresql{} documentation.
1229
1230 \item [status]
1231 \index[general]{status}
1232
1233 This command will display the status of all components. For the director, it
1234 will display the next jobs that are scheduled during the next 24 hours as
1235 well as the status of currently running jobs. For the Storage Daemon, you
1236 will have drive status or autochanger content. The File Daemon will give you
1237 information about current jobs like average speed or file accounting. The
1238 full form of this command is:
1239 \begin{bVerbatim}
1240 status [all | dir=<dir-name> | director [days=nnn] |
1241 client=<client-name> | [slots] storage=<storage-name>] | network [bytes=<nb>]
1242 \end{bVerbatim}
1243 If you do a \bcommandname{status dir}, the console will list any currently
1244 running jobs, a summary of all jobs scheduled to be run in the next 24
1245 hours, and a listing of the last ten terminated jobs with their statuses.
1246 The scheduled jobs summary will include the Volume name to be used. You
1247 should be aware of two things: 1. to obtain the volume name, the code
1248 goes through the same code that will be used when the job runs, but it
1249 does not do pruning nor recycling of Volumes; 2. The Volume listed is
1250 at best a guess. The Volume actually used may be different because of
1251 the time difference (more durations may expire when the job runs) and
1252 another job could completely fill the Volume requiring a new one.
1253
1254 In the Running Jobs listing, you may find the following types of
1255 information:
1256
1257
1258 \begin{bVerbatim}
1259 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
1260 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
1261 priority jobs to finish
1262 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
1263 5343 Full Rufus.2004-03-13_01.05.04 is running
1264 \end{bVerbatim}
1265
1266 Looking at the above listing from bottom to top, obviously JobId 5343
1267 (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
1268 finish because it is using the \bresource{Storage}, hence the ``waiting on
1269 max Storage jobs''. JobId 5349 has a lower priority than all the other
1270 jobs so it is waiting for higher priority jobs to finish, and finally,
1271 JobId 2507 (MatouVerify) is waiting because only one job can run at a
1272 time, hence it is simply ``waiting execution''
1273
1274 If you do a \bcommandname{status dir}, it will by default list the first
1275 occurrence of all jobs that are scheduled today and tomorrow. If you
1276 wish to see the jobs that are scheduled in the next three days (e.g. on
1277 Friday you want to see the first occurrence of what tapes are scheduled
1278 to be used on Friday, the weekend, and Monday), you can add the \bkeyword{days=3}
1279 option. Note, a \bkeyword{days=0} shows the first occurrence of jobs
1280 scheduled today only. If you have multiple run statements, the first
1281 occurrence of each run statement for the job will be displayed for the
1282 period specified.
1283
1284 If your job seems to be blocked, you can get a general idea of the
1285 problem by doing a \bcommandname{status dir}, but you can most often get a
1286 much more specific indication of the problem by doing a
1287 \bcommandname{status storage=xxx}. For example, on an idle test system, when
1288 we do \bcommandname{status storage=File}, we get:
1289
1290 \begin{bVerbatim}
1291 status storage=File
1292 Connecting to Storage daemon File at 192.168.68.112:8103
1293
1294 rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
1295 Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
1296
1297 Running Jobs:
1298 No Jobs running.
1299 ====
1300
1301 Jobs waiting to reserve a drive:
1302 ====
1303
1304 Terminated Jobs:
1305 JobId Level Files Bytes Status Finished Name
1306 ======================================================================
1307 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
1308 ====
1309
1310 Device status:
1311 Autochanger "DDS-4-changer" with devices:
1312 "DDS-4" (/dev/nst0)
1313 Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
1314 Pool="*unknown*"
1315 Slot 2 is loaded in drive 0.
1316 Total Bytes Read=0 Blocks Read=0 Bytes/block=0
1317 Positioned at File=0 Block=0
1318
1319 Device "DVD-Writer" (/dev/hdc) is not open.
1320 Device "File" (/tmp) is not open.
1321 ====
1322
1323 In Use Volume status:
1324 ====
1325 \end{bVerbatim}
1326
1327 Now, what this tells us is that no jobs are running and that none of
1328 the devices are in use. Now, if we \bcommandname{unmount} the autochanger, which
1329 will not be used in this example, and then start a Job that uses the
1330 File device, the job will block. When we re-issue the status storage
1331 command, we get for the Device status:
1332
1333 \begin{bVerbatim}
1334 status storage=File
1335 ...
1336 Device status:
1337 Autochanger "DDS-4-changer" with devices:
1338 "DDS-4" (/dev/nst0)
1339 Device "DDS-4" (/dev/nst0) is not open.
1340 Device is BLOCKED. User unmounted.
1341 Drive 0 is not loaded.
1342
1343 Device "DVD-Writer" (/dev/hdc) is not open.
1344 Device "File" (/tmp) is not open.
1345 Device is BLOCKED waiting for media.
1346 ====
1347 ...
1348 \end{bVerbatim}
1349 \normalsize
1350
1351 Now, here it should be clear that if a job were running that wanted
1352 to use the Autochanger (with two devices), it would block because
1353 the user unmounted the device. The real problem for the Job I started
1354 using the ``File'' device is that the device is blocked waiting for
1355 media --- that is \bacula{} needs you to label a Volume.
1356 \smallskip
1357
1358 If you enter \bcommandname{status storage}, \bacula{} will prompt you with a
1359 list of the storage resources. When you select one, the Storage daemon
1360 will be requested to do a \bcommandname{status}. However, note that the Storage
1361 daemon will do a status of all the devices it has, and not just of the
1362 one you requested. In the current version of \bacula{}, when you enter
1363 the \bcommandname{status storage} command, it prompts you only with a subset of
1364 all the storage resources that the Director considers to be in different
1365 Storage daemons. In other words, it attempts to remove duplicate
1366 storage definitions. This can be a bit confusing at first, but can
1367 vastly simplify the promt listing if you have defined a large number
1368 of storage resources.
1369
1370 If you prefer to see the full list of all storage resources, simply
1371 add the keyword \bkeyword{select} to the command such as:
1372 \bcommandname{status select storage} and you will get a prompt that includes
1373 all storage resources even if they reference the same storage daemon.
1374 \smallskip
1375
1376 If you enter \bcommandname{status network}, \bacula{} will prompt you with a
1377 list of the storage resources and a list of the client resources. Then,
1378 \bacula{} will test the network throughput between the two selected daemons.
1379
1380 \begin{bVerbatim}
1381 *status network
1382 The defined Client resources are:
1383 1: zog82-fd
1384 2: zog8-fd
1385 Select Client (File daemon) resource (1-2): 2
1386 Automatically selected Storage: File1
1387 Connecting to Storage File1 at zog8:8103
1388 Connecting to Client zog8-fd at zog8:8102
1389 Running network test between Client=zog8-fd and Storage=File1 with 52.42 MB ...
1390 2000 OK bytes=52428800 duration=48ms write_speed=1.088 GB/s
1391 2000 OK bytes=52428800 duration=56ms read_speed=933.8 MB/s
1392 \end{bVerbatim}
1393
1394
1395 \item [tag]
1396 \index[general]{tag}
1397 The \bcommandname{tag} command will add, delete or list the tags associated with catalog records such as
1398 Clients, Jobs, Volumes or Objects. The command accepts all parameters in command line.
1399 \begin{bVerbatim}
1400 *tag add name="#test1" client=zog8-fd
1401 1000 Tag added
1402
1403 *tag
1404 Available Tag operations:
1405 1: Add
1406 2: Delete
1407 3: List
1408 Select Tag operation (1-3): 1
1409 Available Tag target:
1410 1: Client
1411 2: Job
1412 3: Volume
1413 Select Tag target (1-3): 1
1414 Automatically selected Client: zog8-fd
1415 Enter the Tag value: test1
1416 1000 Tag added
1417 *tag
1418 Available Tag operations:
1419 1: Add
1420 2: Delete
1421 3: List
1422 Select Tag operation (1-3): 3
1423 Available Tag target:
1424 1: Client
1425 2: Job
1426 3: Volume
1427 Select Tag target (1-3): 1
1428 Automatically selected Client: zog8-fd
1429 +--------+----------+---------+
1430 | tag | clientid | client |
1431 +--------+----------+---------+
1432 | test1 | 1 | zog8-fd |
1433 | #test1 | 1 | zog8-fd |
1434 +--------+----------+---------+
1435 \end{bVerbatim}
1436
1437 \item [time]
1438 \index[general]{time}
1439 Prints the current time.
1440
1441 \item [trace]
1442 \index[general]{trace}
1443 Turn on/off trace to file.
1444
1445 \item [umount]
1446 \index[general]{umount|see{unmount}}
1447 For old-time Unix guys. See the \bcommandname{unmount} command for full details.
1448
1449 \item [unmount]
1450 \index[general]{unmount}
1451 This command causes the indicated \bacula{} Storage daemon to unmount the
1452 specified device. The forms of the command are the same as the \bcommandname{mount} command:
1453
1454 \begin{bVerbatim}
1455 unmount storage=<storage-name> [ drive=<num> ]
1456 \end{bVerbatim}
1457 \begin{bVerbatim}
1458 unmount [ jobid=<id> | job=<job-name> ]
1459 \end{bVerbatim}
1460
1461
1462 Once you unmount a storage device, \bacula{} will no longer be able to use
1463 it until you issue a mount command for that device. If \bacula{} needs to
1464 access that device, it will block and issue mount requests periodically
1465 to the operator.
1466
1467 If the device you are unmounting is an autochanger, it will unload
1468 the drive you have specified on the command line. If no drive is
1469 specified, it will assume drive 1.
1470
1471 \label{blb:UpdateCommand}
1472 \item [update]
1473 \index[general]{update}
1474 This command will update the catalog for either a specific Pool record, a Volume
1475 record, or the Slots in an autochanger with barcode capability. In the case
1476 of updating a Pool record, the new information will be automatically taken
1477 from the corresponding Director's configuration resource record. It can be
1478 used to increase the maximum number of volumes permitted or to set a maximum
1479 number of volumes. The following main keywords may be specified: \bkeyword{media},
1480 \bkeyword{volume}, \bkeyword{pool}, \bkeyword{slots}, \bkeyword{stats}.
1481
1482 In the case of updating a Volume, you will be prompted for which value you
1483 wish to change. The following Volume parameters may be changed:
1484
1485 \begin{bVerbatim}
1486 Volume Status
1487 Volume Retention Period
1488 Volume Use Duration
1489 Maximum Volume Jobs
1490 Maximum Volume Files
1491 Maximum Volume Bytes
1492 Recycle Flag
1493 Recycle Pool
1494 Slot
1495 InChanger Flag
1496 Pool
1497 Volume Files
1498 Volume from Pool
1499 All Volumes from Pool
1500 All Volumes from all Pools
1501 \end{bVerbatim}
1502
1503
1504 For slots \bcommandname{update slots}, \bacula{} will obtain a list of slots and
1505 their barcodes from the Storage daemon, and for each barcode found, it
1506 will automatically update the slot in the catalog Media record to
1507 correspond to the new value. This is very useful if you have moved
1508 cassettes in the magazine, or if you have removed the magazine and
1509 inserted a different one. As the slot of each Volume is updated, the
1510 InChanger flag for that Volume will also be set, and any other Volumes
1511 in the Pool that were last mounted on the same Storage device
1512 will have their InChanger flag turned off. This permits
1513 \bacula{} to know what magazine (tape holder) is currently in the
1514 autochanger.
1515
1516 If you do not have barcodes, you can accomplish the same thing in
1517 version 1.33 and later by using the \bcommandname{update slots scan} command.
1518 The \bkeyword{scan} keyword tells \bacula{} to physically mount each tape and to
1519 read its VolumeName.
1520
1521 For Pool \bcommandname{update pool}, \bacula{} will move the Volume record from its
1522 existing pool to the pool specified.
1523
1524 For \bkeyword{Volume from Pool}, \bkeyword{All Volumes from Pool} and
1525 \bkeyword{All Volumes from all Pools}, the following values are updated from the Pool record:
1526 Recycle, RecyclePool, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles,
1527 and MaxVolBytes. (RecyclePool feature is available with \bacula{} 2.1.4 or
1528 higher.)
1529
1530 The full form of the \bcommandname{update} command with all command line arguments is:
1531
1532 \begin{bVerbatim}
1533 update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
1534 VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
1535 slot=nnn enabled=n recyclepool=zzz actiononpurge=xxx
1536 \end{bVerbatim}
1537
1538 \begin{bVerbatim}
1539 update volume=xxx frompool
1540 \end{bVerbatim}
1541
1542 \begin{bVerbatim}
1543 update volume allfrompool=xxx
1544 \end{bVerbatim}
1545
1546 \begin{bVerbatim}
1547 update volume fromallpools
1548 \end{bVerbatim}
1549
1550 \item [use]
1551 \index[general]{use}
1552 This command allows you to specify which Catalog database to use. Normally,
1553 you will be using only one database so this will be done automatically. In
1554 the case that you are using more than one database, you can use this command
1555 to switch from one to another.
1556
1557 \begin{bVerbatim}
1558 use [catalog=name-of-catalog]
1559 \end{bVerbatim}
1560
1561 \item [var]
1562 \label{blb:var}
1563 \index[general]{var name}
1564 This command takes a string or quoted string and does variable expansion on
1565 it the same way variable expansion is done on the \bdirectivename{LabelFormat} string.
1566 Thus, for the most part, you can test your LabelFormat strings. The
1567 difference between the \bcommandname{var} command and the actual LabelFormat process
1568 is that during the var command, no job is running so ``dummy'' values are
1569 used in place of Job specific variables. Generally, however, you will get a
1570 good idea of what is going to happen in the real case.
1571
1572 \item [version]
1573 \index[general]{version}
1574 The command prints the Director's version.
1575
1576 \item [wait]
1577 \index[general]{wait}
1578 The \bcommandname{wait} command causes the Director to pause until there are no jobs
1579 running. This command is useful in a batch situation such as regression
1580 testing where you wish to start a job and wait until that job completes
1581 before continuing. This command now has the following options:
1582
1583 \begin{bVerbatim}
1584 wait [jobid=nn] [jobuid=unique id] [job=job name]
1585 \end{bVerbatim}
1586
1587 If specified with a specific JobId, the \bcommandname{wait} command will wait
1588 for that particular job to terminate before continuing.
1589
1590 \end{bdescription}
1591
1592 \label{blb:dotcommands}
1593 \section{Special dot Commands}
1594 \index[general]{Commands!Special dot (.)}
1595 \index[general]{Special dot (.) Commands}
1596 \index[general]{. commands}
1597
1598 There is a list of commands that are prefixed with a period (.). These
1599 commands are intended to be used either by batch programs or graphical user
1600 interface front-ends. They are not normally used by interactive users. Once
1601 GUI development begins, this list will be considerably expanded. The following
1602 is the list of dot commands:
1603
1604 \begin{bVerbatim}
1605 .api
1606 .backups job=xxx list backups for specified job
1607 .clients list all client names
1608 .catalogs
1609 .defaults client=xxx fileset=yyy list defaults for specified client
1610 .die cause the Director to segment fault (for debugging)
1611 .dir when in tree mode prints the equivalent to the dir command,
1612 but with fields separated by commas rather than spaces.
1613 .dump
1614 .exit quit
1615 .events list record custom events
1616 .filesets list all fileset names
1617 .help help command output
1618 .jobs list all job names
1619 .estimate
1620 .jlist list catalog objects in JSON format (see list command)
1621 .levels list all levels
1622 .messages get quick messages
1623 .msgs return any queued messages
1624 .pools list all pool names
1625 .quit quit
1626 .putfile
1627 .schedule
1628 .sql
1629 .status get status output
1630 .storage return storage resource names
1631 .volstatus
1632 .media
1633 .mediatypes
1634 .locations
1635 .actiononpurge
1636 .bvfs_lsdirs
1637 .bvfs_lsfiles [allfiles] [jobid=xxx] [pathid=xxx] [path=str]
1638 .bvfs_get_volumes
1639 .bvfs_update
1640 .bvfs_get_jobids
1641 .bvfs_get_jobs
1642 .bvfs_get_bootstrap
1643 .bvfs_get_fileindex
1644 .bvfs_versions
1645 .bvfs_get_delta
1646 .bvfs_restore
1647 .bvfs_cleanup
1648 .bvfs_decode_lstat
1649 .bvfs_clear_cache
1650 .bvfs_update_fv
1651 .bvfs_delete_fileid
1652 .setuid
1653 .ls
1654 .types list job types
1655 .query
1656 .tags list tags
1657 \end{bVerbatim}
1658
1659 \label{blb:atcommands}
1660 \section{Special At (@) Commands}
1661 \index[general]{Commands!Special At (\symbol{64})}
1662 \index[general]{Special At (\symbol{64}) Commands}
1663 \index[general]{\symbol{64} commands}
1664
1665 Normally, all commands entered to the Console program are immediately
1666 forwarded to the Director, which may be on another machine, to be executed.
1667 However, there is a small list of \bcommandname{at} commands, all beginning with an at
1668 character (\bcommandname{@}), that will not be sent to the Director, but rather interpreted
1669 by the Console program directly. Note, these commands are implemented only in
1670 the tty console program and not in the \bat{} Console. These commands are:
1671
1672 \begin{bdescription}
1673 \item [@input \bbracket{filename}]
1674 \index[general]{\symbol{64}input \bbracket{filename}}
1675 Read and execute the commands contained in the file specified.
1676
1677 \item [@output \bbracket{filename} w/a]
1678 \index[general]{\symbol{64}output \bbracket{filename} w/a}
1679 Send all following output to the filename specified either overwriting the
1680 file (w) or appending to the file (a). To redirect the output to the
1681 terminal, simply enter \bcommandname{@output} without a filename specification.
1682 WARNING: be careful not to overwrite a valid file. A typical example during a
1683 regression test might be:
1684
1685 \begin{bVerbatim}
1686 @output /dev/null
1687 commands ...
1688 @output
1689 \end{bVerbatim}
1690
1691 \item [@tee \bbracket{filename} w/a]
1692 \index[general]{\symbol{64}tee \bbracket{filename} w/a}
1693 Send all subsequent output to both the specified file and the terminal. It is
1694 turned off by specifying \bcommandname{@tall}, \bcommandname{@tee} or \bcommandname{@output} without a filename.
1695
1696 \item [@tall \bbracket{filename} w/a]
1697 \index[general]{\symbol{64}tall \bbracket{filename} w/a}
1698 Send all subsequent input and output to both the specified file and the terminal. It is
1699 turned off by specifying \bcommandname{@tall}, \bcommandname{@tee} or \bcommandname{@output} without a filename.
1700
1701
1702 \item [@sleep \bbracket{seconds}]
1703 \index[general]{\symbol{64}sleep \bbracket{seconds}}
1704 Sleep the specified number of seconds.
1705
1706 \item [@time]
1707 \index[general]{\symbol{64}time}
1708 Print the current time and date.
1709
1710 \item [@version]
1711 \index[general]{\symbol{64}version}
1712 Print the console's version.
1713
1714 \item [@quit]
1715 \index[general]{\symbol{64}quit}
1716 quit
1717
1718 \item [@exit]
1719 \index[general]{\symbol{64}exit}
1720 quit
1721
1722 \item [@\# anything]
1723 \index[general]{anything}
1724 Comment
1725
1726 \item [@help]
1727 \index[general]{\symbol{64}help}
1728 Get the list of every special \bcommandname{@} commands.
1729
1730 \item [@separator \bbracket{char}]
1731 \index[general]{\symbol{64}separator}
1732 When using \bconsolename{} with readline, you can set the command separator to one
1733 of those characters to write commands who require multiple input on one line,
1734 or to put multiple commands on a single line.
1735 \begin{bVerbatim}
1736 !$%&'()*+,-/:;<>?[]^`{|}~
1737 \end{bVerbatim}
1738
1739 Note, if you use a semicolon (;) as a separator character, which is
1740 common, you will not be able to use the \bcommandname{sql} command, which
1741 requires each command to be terminated by a semicolon.
1742 \end{bdescription}
1743
1744 \label{blb:scripting}
1745 \section{Running the Console from a Shell Script}
1746 \index[general]{Script!Running the Console Program from a Shell}
1747 \index[general]{Running the Console Program from a Shell Script}
1748
1749 You can automate many Console tasks by running the console program from a
1750 shell script. For example, if you have created a file containing the following
1751 commands:
1752
1753 \begin{bVerbatim}
1754 ./bconsole -c ./bconsole.conf <<END_OF_DATA
1755 unmount storage=DDS-4
1756 quit
1757 END_OF_DATA
1758 \end{bVerbatim}
1759
1760 when that file is executed, it will unmount the current DDS-4 storage device.
1761 You might want to run this command during a Job by using the \bresourcename{RunBeforeJob}
1762 or \bresourcename{RunAfterJob} records.
1763
1764 It is also possible to run the Console program from file input where the file
1765 contains the commands as follows:
1766
1767 \begin{bVerbatim}
1768 ./bconsole -c ./bconsole.conf <filename
1769 \end{bVerbatim}
1770
1771 where the file named \bfilename{filename} contains any set of console commands.
1772
1773 As a real example, the following script is part of the \bacula{} regression
1774 tests. It labels a volume (a disk volume), runs a backup, then does a restore
1775 of the files saved.
1776
1777 \begin{bVerbatim}
1778 bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
1779 @output /dev/null
1780 messages
1781 @output /tmp/log1.out
1782 label volume=TestVolume001
1783 run job=Client1 yes
1784 wait
1785 messages
1786 @#
1787 @# now do a restore
1788 @#
1789 @output /tmp/log2.out
1790 restore current all
1791 yes
1792 wait
1793 messages
1794 @output
1795 quit
1796 END_OF_DATA
1797 \end{bVerbatim}
1798
1799 The output from the backup is directed to \bfilename{/tmp/log1.out} and the output from
1800 the restore is directed to \bfilename{/tmp/log2.out}. To ensure that the backup and
1801 restore ran correctly, the output files are checked with:
1802
1803 \begin{bVerbatim}
1804 grep "^ *Termination: *Backup OK" /tmp/log1.out
1805 backupstat=$?
1806 grep "^ *Termination: *Restore OK" /tmp/log2.out
1807 restorestat=$?
1808 \end{bVerbatim}
1809
1810 \section{Adding Volumes to a Pool}
1811 \index[general]{Adding Volumes to a Pool}
1812 \index[general]{Pool!Adding Volumes to a}
1813
1814 If you have used the \bcommandname{label} command to label a Volume, it will be
1815 automatically added to the Pool, and you will not need to add any media to the
1816 pool.
1817
1818 Alternatively, you may choose to add a number of Volumes to the pool without
1819 labeling them. At a later time when the Volume is requested by \bacula{} you
1820 will need to label it.
1821
1822 Before adding a volume, you must know the following information:
1823
1824 \begin{benumerate}
1825 \item The name of the Pool (normally ``Default'')
1826 \item The Media Type as specified in the \bresource{Storage} in the Director's
1827 configuration file (e.g. ``DLT8000'')
1828 \item The number and names of the Volumes you wish to create.
1829 \end{benumerate}
1830
1831 For example, to add media to a Pool, you would issue the following commands to
1832 the console program:
1833
1834 \begin{bVerbatim}
1835 *add
1836 Enter name of Pool to add Volumes to: Default
1837 Enter the Media Type: DLT8000
1838 Enter number of Media volumes to create. Max=1000: 10
1839 Enter base volume name: Save
1840 Enter the starting number: 1
1841 10 Volumes created in pool Default
1842 *
1843 \end{bVerbatim}
1844
1845 To see what you have added, enter:
1846
1847 \begin{bVerbatim}
1848 *list media pool=Default
1849 +-------+----------+---------+---------+-------+------------------+
1850 | MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
1851 +-------+----------+---------+---------+-------+------------------+
1852 | 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1853 | 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1854 | 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1855 | 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1856 | 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1857 | 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1858 | 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1859 | 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1860 | 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1861 | 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
1862 +-------+----------+---------+---------+-------+------------------+
1863 *
1864 \end{bVerbatim}
1865
1866 Notice that the console program automatically appended a number to the base
1867 Volume name that you specify (Save in this case). If you don't want it to
1868 append a number, you can simply answer 0 (zero) to the question ``Enter number
1869 of Media volumes to create. Max=1000:'', and in this case, it will create a
1870 single Volume with the exact name you specify.