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