\clearpage
\include{bconsole}
-\include{gui}
\include{fdl}
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Console}
+\label{_ConsoleChapter}
+\index[general]{Console!Bacula}
+\index[general]{Bacula Console}
+\index[general]{Console!Bacula}
+\index[general]{Bacula Console}
+
+The {\bf Bacula Console} (sometimes called the User Agent) is a program that
+allows the user or the System Administrator, to interact with the Bacula
+Director daemon while the daemon is running.
+
+The current Bacula Console comes in two versions: a shell interface (TTY
+style), and a QT GUI interface (Bat). Both permit the administrator or
+authorized users to interact with Bacula. You can determine the status of a
+particular job, examine the contents of the Catalog as well as perform certain
+tape manipulations with the Console program.
+
+In addition, there is a bwx-console built with wxWidgets that allows a graphic
+restore of files. As of version 1.34.1 it is in an early stage of development,
+but it already is quite useful. Unfortunately, it has not been enhanced for
+some time now.
+
+Since the Console program interacts with the Director through the network, your
+Console and Director programs do not necessarily need to run on the same
+machine.
+
+In fact, a certain minimal knowledge of the Console program is needed in order
+for Bacula to be able to write on more than one tape, because when Bacula
+requests a new tape, it waits until the user, via the Console program,
+indicates that the new tape is mounted.
+
+\section{Console Configuration}
+\index[general]{Console Configuration}
+\index[general]{Configuration!Console}
+\index[general]{Console Configuration}
+\index[general]{Configuration!Console}
+
+When the Console starts, it reads a standard Bacula configuration file
+named {\bf bconsole.conf} or {\bf bat.conf} in the case of the Bat
+QT Console version from the current directory unless you specify the {\bf {-}c}
+command line option (see below). This file allows default configuration
+of the Console, and at the current time, the only Resource Record defined
+is the Director resource, which gives the Console the name and address of
+the Director. For more information on configuration of the Console
+program, please see the \ilink{Console Configuration
+File}{ConsoleConfChapter} Chapter of this document.
+
+\section{Running the Console Program}
+\index[general]{Running the Console Program}
+\index[general]{Program!Running the Console}
+\index[general]{Running the Console Program}
+\index[general]{Program!Running the Console}
+
+The console program can be run with the following options:
+\footnotesize
+\begin{verbatim}
+Usage: bconsole [-s] [-c config_file] [-d debug_level]
+ -c <file> set configuration file to file
+ -dnn set debug level to nn
+ -n no conio
+ -s no signals
+ -u <nn> set command execution timeout to <nn> seconds
+ -t test - read configuration and exit
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+
+After launching the Console program (bconsole), it will prompt you for the next
+command with an asterisk (*). Generally, for all commands, you can simply
+enter the command name and the Console program will prompt you for the
+necessary arguments. Alternatively, in most cases, you may enter the command
+followed by arguments. The general format is:
+
+\footnotesize
+\begin{verbatim}
+ <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
+\end{verbatim}
+\normalsize
+
+where {\bf command} is one of the commands listed below; {\bf keyword} is one
+of the keywords listed below (usually followed by an argument); and {\bf
+argument} is the value. The command may be abbreviated to the shortest unique
+form. If two commands have the same starting letters, the one that will be
+selected is the one that appears first in the {\bf help} listing. If you want
+the second command, simply spell out the full command. None of the keywords
+following the command may be abbreviated.
+
+For example:
+
+\footnotesize
+\begin{verbatim}
+list files jobid=23
+\end{verbatim}
+\normalsize
+
+will list all files saved for JobId 23. Or:
+
+\footnotesize
+\begin{verbatim}
+show pools
+\end{verbatim}
+\normalsize
+
+will display all the Pool resource records.
+
+The maximum command line length is limited to 511 characters, so if you
+are scripting the console, you may need to take some care to limit the
+line length.
+
+\section{Stopping the Console Program}
+\index[general]{Program!Stopping the Console}
+\index[general]{Stopping the Console Program}
+\index[general]{Program!Stopping the Console}
+\index[general]{Stopping the Console Program}
+
+Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
+will terminate. However, it waits until the Director acknowledges the command.
+If the Director is already doing a lengthy command (e.g. prune), it may take
+some time. If you want to immediately terminate the Console program, enter the
+{\bf .quit} command.
+
+There is currently no way to interrupt a Console command once issued (i.e.
+Ctrl-C does not work). However, if you are at a prompt that is asking you to
+select one of several possibilities and you would like to abort the command,
+you can enter a period ({\bf .}), and in most cases, you will either be
+returned to the main command prompt or if appropriate the previous prompt (in
+the case of nested prompts). In a few places such as where it is asking for a
+Volume name, the period will be taken to be the Volume name. In that case, you
+will most likely be able to cancel at the next prompt.
+
+\label{keywords}
+\section{Alphabetic List of Console Keywords}
+\index[general]{Keywords!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Keywords}
+\index[general]{Keywords!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Keywords}
+Unless otherwise specified, each of the following keywords
+takes an argument, which is specified after the keyword following
+an equal sign. For example:
+
+\begin{verbatim}
+jobid=536
+\end{verbatim}
+
+Please note, this list is incomplete as it is currently in
+the process of being created and is not currently totally in
+alphabetic
+order ...
+
+\begin{description}
+\item [restart]
+ Permitted on the python command, and causes the Python
+ interpreter to be restarted. Takes no argument.
+\item [all]
+ Permitted on the status and show commands to specify all components or
+ resources respectively.
+\item [allfrompool]
+ Permitted on the update command to specify that all Volumes in the
+ pool (specified on the command line) should be updated.
+\item [allfrompools]
+ Permitted on the update command to specify that all Volumes in all
+ pools should be updated.
+\item [before]
+ Used in the restore command.
+\item [bootstrap]
+ Used in the restore command.
+\item [catalog]
+ Allowed in the use command to specify the catalog name
+ to be used.
+\item [catalogs]
+ Used in the show command. Takes no arguments.
+\item [client | fd]
+\item [clients]
+ Used in the show, list, and llist commands. Takes no arguments.
+\item [counters]
+ Used in the show command. Takes no arguments.
+\item [current]
+ Used in the restore command. Takes no argument.
+\item [days]
+ Used to define the number of days the "list nextvol" command
+ should consider when looking for jobs to be run. The days keyword
+ can also be used on the "status dir" command so that it will display
+ jobs scheduled for the number of days you want.
+\item [devices]
+ Used in the show command. Takes no arguments.
+\item [dir | director]
+\item [directors]
+ Used in the show command. Takes no arguments.
+\item [directory]
+ Used in the restore command. Its argument specifies the directory
+ to be restored.
+\item [enabled]
+ This keyword can appear on the {\bf update volume} as well
+ as the {\bf update slots} commands, and can
+ allows one of the following arguments: yes, true, no, false, archived,
+ 0, 1, 2. Where 0 corresponds to no or false, 1 corresponds to yes or true, and
+ 2 corresponds to archived. Archived volumes will not be used, nor will
+ the Media record in the catalog be pruned. Volumes that are not enabled,
+ will not be used for backup or restore.
+\item [done]
+ Used in the restore command. Takes no argument.
+\item [file]
+ Used in the restore command.
+\item [files]
+ Used in the list and llist commands. Takes no arguments.
+\item [fileset]
+\item [filesets]
+ Used in the show command. Takes no arguments.
+\item [help]
+ Used in the show command. Takes no arguments.
+\item [jobs]
+ Used in the show, list and llist commands. Takes no arguments.
+\item [jobmedia]
+ Used in the list and llist commands. Takes no arguments.
+\item [jobtotals]
+ Used in the list and llist commands. Takes no arguments.
+\item [jobid]
+ The JobId is the numeric jobid that is printed in the Job
+ Report output. It is the index of the database record for the
+ given job. While it is unique for all the existing Job records
+ in the catalog database, the same JobId can be reused once a
+ Job is removed from the catalog. Probably you will refer
+ specific Jobs that ran using their numeric JobId.
+\item [job | jobname]
+ The Job or Jobname keyword refers to the name you specified
+ in the Job resource, and hence it refers to any number of
+ Jobs that ran. It is typically useful if you want to list
+ all jobs of a particular name.
+\item [level]
+\item [listing]
+ Permitted on the estimate command. Takes no argument.
+\item [limit]
+\item [messages]
+ Used in the show command. Takes no arguments.
+\item [media]
+ Used in the list and llist commands. Takes no arguments.
+\item [nextvol | nextvolume]
+ Used in the list and llist commands. Takes no arguments.
+\item [on]
+ Takes no keyword.
+\item [off]
+ Takes no keyword.
+\item [pool]
+\item [pools]
+ Used in the show, list, and llist commands. Takes no arguments.
+\item [select]
+ Used in the restore command. Takes no argument.
+\item [storages]
+ Used in the show command. Takes no arguments.
+\item [schedules]
+ Used in the show command. Takes no arguments.
+\item [sd | store | storage]
+\item [ujobid]
+ The ujobid is a unique job identification that is printed
+ in the Job Report output. At the current time, it consists
+ of the Job name (from the Name directive for the job) appended
+ with the date and time the job was run. This keyword is useful
+ if you want to completely identify the Job instance run.
+\item [volume]
+\item [volumes]
+ Used in the list and llist commands. Takes no arguments.
+\item [where]
+ Used in the restore command.
+\item [yes]
+ Used in the restore command. Takes no argument.
+\end{description}
+
+\label{list}
+\section{Alphabetic List of Console Commands}
+\index[general]{Commands!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Commands}
+\index[general]{Commands!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Commands}
+
+The following commands are currently implemented:
+
+\begin{description}
+\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
+ jobid=\lt{}JobId\gt{}]} ]
+ \index[general]{add}
+ This command is used to add Volumes to an existing Pool. That is,
+ it creates the Volume name in the catalog and inserts into the Pool
+ in the catalog, but does not attempt to access the physical Volume.
+ Once
+ added, Bacula expects that Volume to exist and to be labeled.
+ This command is not normally used since Bacula will
+ automatically do the equivalent when Volumes are labeled. However,
+ there may be times when you have removed a Volume from the catalog
+ and want to later add it back.
+
+ Normally, the {\bf label} command is used rather than this command
+ because the {\bf label} command labels the physical media (tape, disk,
+ DVD, ...) and does the equivalent of the {\bf add} command. The {\bf
+ add} command affects only the Catalog and not the physical media (data
+ on Volumes). The physical media must exist and be labeled before use
+ (usually with the {\bf label} command). This command can, however, be
+ useful if you wish to add a number of Volumes to the Pool that will be
+ physically labeled at a later time. It can also be useful if you are
+ importing a tape from another site. Please see the {\bf label} command
+ below for the list of legal characters in a Volume name.
+
+\item [autodisplay on/off]
+ \index[general]{autodisplay on/off}
+ This command accepts {\bf on} or {\bf off} as an argument, and turns
+ auto-display of messages on or off respectively. The default for the
+ console program is {\bf off}, which means that you will be notified when
+ there are console messages pending, but they will not automatically be
+ displayed.
+
+ When autodisplay is turned off, you must explicitly retrieve the
+ messages with the {\bf messages} command. When autodisplay is turned
+ on, the messages will be displayed on the console as they are received.
+
+\item [automount on/off]
+ \index[general]{automount on/off}
+ This command accepts {\bf on} or {\bf off} as the argument, and turns
+ auto-mounting of the Volume after a {\bf label} command on or off
+ respectively. The default is {\bf on}. If {\bf automount} is turned
+ off, you must explicitly {\bf mount} tape Volumes after a label command to
+ use it.
+
+\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
+ \index[general]{cancel jobid}
+ This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
+ job=xxx} as an argument where nnn is replaced by the JobId and xxx is
+ replaced by the job name. If you do not specify a keyword, the Console
+ program will prompt you with the names of all the active jobs allowing
+ you to choose one.
+
+ Once a Job is marked to be canceled, it may take a bit of time
+ (generally within a minute but up to two hours) before the Job actually
+ terminates, depending on what operations it is doing.
+ Don't be surprised that you receive a Job not found message. That just
+ means that one of the three daemons had already canceled the job.
+ Messages numbered in the 1000's are from the Director, 2000's are from
+ the File daemon and 3000's from the Storage daemon.
+
+
+\item [{create [pool=\lt{}pool-name\gt{}]}]
+ \index[general]{create pool}
+ This command is not normally used as the Pool records are automatically
+ created by the Director when it starts based on what it finds in
+ the conf file. If needed, this command can be
+ to create a Pool record in the database using the
+ Pool resource record defined in the Director's configuration file. So
+ in a sense, this command simply transfers the information from the Pool
+ resource in the configuration file into the Catalog. Normally this
+ command is done automatically for you when the Director starts providing
+ the Pool is referenced within a Job resource. If you use this command
+ on an existing Pool, it will automatically update the Catalog to have
+ the same information as the Pool resource. After creating a Pool, you
+ will most likely use the {\bf label} command to label one or more
+ volumes and add their names to the Media database.
+
+ When starting a Job, if Bacula determines that there is no Pool record
+ in the database, but there is a Pool resource of the appropriate name,
+ it will create it for you. If you want the Pool record to appear in the
+ database immediately, simply use this command to force it to be created.
+
+\item [{delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
+ jobid=\lt{}id\gt{}]}]
+ \index[general]{delete}
+ The delete command is used to delete a Volume, Pool or Job record from
+ the Catalog as well as all associated catalog Volume records that were
+ created. This command operates only on the Catalog database and has no
+ effect on the actual data written to a Volume. This command can be
+ dangerous and we strongly recommend that you do not use it unless you
+ know what you are doing.
+
+ If the keyword {\bf Volume} appears on the command line, the named
+ Volume will be deleted from the catalog, if the keyword {\bf Pool}
+ appears on the command line, a Pool will be deleted, and if the keyword
+ {\bf Job} appears on the command line, a Job and all its associated
+ records (File and JobMedia) will be deleted from the catalog. The full
+ form of this command is:
+
+\begin{verbatim}
+delete pool=<pool-name>
+\end{verbatim}
+
+ or
+
+\begin{verbatim}
+delete volume=<volume-name> pool=<pool-name> or
+\end{verbatim}
+
+\begin{verbatim}
+delete JobId=<job-id> JobId=<job-id2> ... or
+\end{verbatim}
+
+\begin{verbatim}
+delete Job JobId=n,m,o-r,t ...
+\end{verbatim}
+
+ The first form deletes a Pool record from the catalog database. The
+ second form deletes a Volume record from the specified pool in the
+ catalog database. The third form deletes the specified Job record from
+ the catalog database. The last form deletes JobId records for JobIds
+ n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
+ number. That is a "delete jobid" accepts lists and ranges of
+ jobids.
+
+\item [disable job\lt{}job-name\gt{}]
+ \index[general]{disable}
+ This command permits you to disable a Job for automatic scheduling.
+ The job may have been previously enabled with the Job resource
+ {\bf Enabled} directive or using the console {\bf enable} command.
+ The next time the Director is restarted or the conf file is reloaded,
+ the Enable/Disable state will be set to the value in the Job resource
+ (default enabled) as defined in the bacula-dir.conf file.
+
+\item [enable job\lt{}job-name\gt{}]
+ \index[general]{enable}
+ This command permits you to enable a Job for automatic scheduling.
+ The job may have been previously disabled with the Job resource
+ {\bf Enabled} directive or using the console {\bf disable} command.
+ The next time the Director is restarted or the conf file is reloaded,
+ the Enable/Disable state will be set to the value in the Job resource
+ (default enabled) as defined in the bacula-dir.conf file.
+
+\label{estimate}
+\item [estimate]
+ \index[general]{estimate}
+ Using this command, you can get an idea how many files will be backed
+ up, or if you are unsure about your Include statements in your FileSet,
+ you can test them without doing an actual backup. The default is to
+ assume a Full backup. However, you can override this by specifying a
+ {\bf level=Incremental} or {\bf level=Differential} on the command line.
+ A Job name must be specified or you will be prompted for one, and
+ optionally a Client and FileSet may be specified on the command line.
+ It then contacts the client which computes the number of files and bytes
+ that would be backed up. Please note that this is an estimate
+ calculated from the number of blocks in the file rather than by reading
+ the actual bytes. As such, the estimated backup size will generally be
+ larger than an actual backup.
+
+ The \texttt{estimate} command can use the accurate code to detect changes
+ and give a better estimation. You can set the accurate behavior on command
+ line using \texttt{accurate=yes/no} or use the Job setting as default value.
+
+ Optionally you may specify the keyword {\bf listing} in which case, all the
+ files to be backed up will be listed. Note, it could take quite some time to
+ display them if the backup is large. The full form is:
+
+\begin{verbatim}
+estimate job=<job-name> listing client=<client-name> accurate=<yes/no>
+ fileset=<fileset-name> level=<level-name>
+\end{verbatim}
+
+ Specification of the {\bf job} is sufficient, but you can also override the
+ client, fileset, accurate and/or level by specifying them on the estimate
+ command line.
+
+
+As an example, you might do:
+
+\footnotesize
+\begin{verbatim}
+ @output /tmp/listing
+ estimate job=NightlySave listing level=Incremental
+ @output
+\end{verbatim}
+\normalsize
+
+ which will do a full listing of all files to be backed up for the Job {\bf
+ NightlySave} during an Incremental save and put it in the file {\bf
+ /tmp/listing}. Note, the byte estimate provided by this command is
+ based on the file size contained in the directory item. This can give
+ wildly incorrect estimates of the actual storage used if there are
+ sparse files on your systems. Sparse files are often found on 64 bit
+ systems for certain system files. The size that is returned is the size
+ Bacula will backup if the sparse option is not specified in the FileSet.
+ There is currently no way to get an estimate of the real file size that
+ would be found should the sparse option be enabled.
+
+\item [exit]
+ \index[general]{exit}
+ This command terminates the console program.
+
+\item [gui]
+ \index[general]{gui}
+ Invoke the non-interactive gui mode.
+\begin{verbatim}
+gui [on|off]
+\end{verbatim}
+
+\item [help]
+ \index[general]{help}
+ This command displays the list of commands available.
+
+\item [label]
+ \index[general]{label}
+ \index[general]{relabel}
+ \index[general]{label}
+ \index[general]{relabel}
+ This command is used to label physical volumes. The full form of this command
+ is:
+
+\begin{verbatim}
+label storage=<storage-name> volume=<volume-name>
+ slot=<slot>
+\end{verbatim}
+
+ If you leave out any part, you will be prompted for it. The media type
+ is automatically taken from the Storage resource definition that you
+ supply. Once the necessary information is obtained, the Console program
+ contacts the specified Storage daemon and requests that the Volume be
+ labeled. If the Volume labeling is successful, the Console program will
+ create a Volume record in the appropriate Pool.
+
+ The Volume name is restricted to letters, numbers, and the special
+ characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
+ period ({\bf .}). All other characters including a space are invalid.
+ This restriction is to ensure good readability of Volume names to reduce
+ operator errors.
+
+ Please note, when labeling a blank tape, Bacula will get {\bf read I/O
+ error} when it attempts to ensure that the tape is not already labeled. If
+ you wish to avoid getting these messages, please write an EOF mark on
+ your tape before attempting to label it:
+
+\footnotesize
+\begin{verbatim}
+ mt rewind
+ mt weof
+
+\end{verbatim}
+\normalsize
+
+The label command can fail for a number of reasons:
+
+\begin{enumerate}
+\item The Volume name you specify is already in the Volume database.
+
+\item The Storage daemon has a tape or other Volume already mounted on the
+ device, in which case you must {\bf unmount} the device, insert a blank
+ tape, then do the {\bf label} command.
+
+\item The Volume in the device is already a Bacula labeled Volume. (Bacula will
+ never relabel a Bacula labeled Volume unless it is recycled and you use the
+ {\bf relabel} command).
+
+\item There is no Volume in the drive.
+\end{enumerate}
+
+There are two ways to relabel a volume that already has a Bacula label. The
+brute force method is to write an end of file mark on the tape using the
+system {\bf mt} program, something like the following:
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/st0 rewind
+ mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+For a disk volume, you would manually delete the Volume.
+
+Then you use the {\bf label} command to add a new label. However, this could
+leave traces of the old volume in the catalog.
+
+The preferable method to relabel a Volume is to first {\bf purge} the volume,
+either automatically, or explicitly with the {\bf purge} command, then use
+the {\bf relabel} command described below.
+
+If your autochanger has barcode labels, you can label all the Volumes in
+your autochanger one after another by using the {\bf label barcodes}
+command. For each tape in the changer containing a barcode, Bacula will
+mount the tape and then label it with the same name as the barcode. An
+appropriate Media record will also be created in the catalog. Any barcode
+that begins with the same characters as specified on the
+"CleaningPrefix=xxx" directive in the Director's Pool resource, will be
+treated as a cleaning tape, and will not be labeled. However, an entry for
+the cleaning tape will be created in the catalog. For example with:
+
+\footnotesize
+\begin{verbatim}
+ Pool {
+ Name ...
+ Cleaning Prefix = "CLN"
+ }
+
+\end{verbatim}
+\normalsize
+
+Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
+and will not be mounted. Note, the full form of the command is:
+
+\footnotesize
+\begin{verbatim}
+label storage=xxx pool=yyy slots=1-5,10 barcodes
+\end{verbatim}
+\normalsize
+
+\item [list]
+ \index[general]{list}
+ The list command lists the requested contents of the Catalog. The
+ various fields of each record are listed on a single line. The various
+ forms of the list command are:
+\footnotesize
+\begin{verbatim}
+ list jobs
+
+ list jobid=<id> (list jobid id)
+
+ list ujobid=<unique job name> (list job with unique name)
+
+ list job=<job-name> (list all jobs with "job-name")
+
+ list jobname=<job-name> (same as above)
+
+ In the above, you can add "limit=nn" to limit the output to
+ nn jobs.
+
+ list jobmedia
+
+ list jobmedia jobid=<id>
+
+ list jobmedia job=<job-name>
+
+ list files jobid=<id>
+
+ list files job=<job-name>
+
+ list pools
+
+ list clients
+
+ list jobtotals
+
+ list volumes
+
+ list volumes jobid=<id>
+
+ list volumes pool=<pool-name>
+
+ list volumes job=<job-name>
+
+ list volume=<volume-name>
+
+ list nextvolume job=<job-name>
+
+ list nextvol job=<job-name>
+
+ list nextvol job=<job-name> days=nnn
+
+\end{verbatim}
+\normalsize
+
+ What most of the above commands do should be more or less obvious. In
+ general if you do not specify all the command line arguments, the
+ command will prompt you for what is needed.
+
+ The {\bf list nextvol} command will print the Volume name to be used by
+ the specified job. You should be aware that exactly what Volume will be
+ used depends on a lot of factors including the time and what a prior job
+ will do. It may fill a tape that is not full when you issue this
+ command. As a consequence, this command will give you a good estimate
+ of what Volume will be used but not a definitive answer. In addition,
+ this command may have certain side effect because it runs through the
+ same algorithm as a job, which means it may automatically purge or
+ recycle a Volume. By default, the job specified must run within the
+ next two days or no volume will be found. You can, however, use the
+ {\bf days=nnn} specification to specify up to 50 days. For example,
+ if on Friday, you want to see what Volume will be needed on Monday,
+ for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
+
+ If you wish to add specialized commands that list the contents of the
+ catalog, you can do so by adding them to the {\bf query.sql} file.
+ However, this takes some knowledge of programming SQL. Please see the
+ {\bf query} command below for additional information. See below for
+ listing the full contents of a catalog record with the {\bf llist}
+ command.
+
+ As an example, the command {\bf list pools} might produce the following
+ output:
+
+\footnotesize
+\begin{verbatim}
++------+---------+---------+---------+----------+-------------+
+| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
++------+---------+---------+---------+----------+-------------+
+| 1 | Default | 0 | 0 | Backup | * |
+| 2 | Recycle | 0 | 8 | Backup | File |
++------+---------+---------+---------+----------+-------------+
+\end{verbatim}
+\normalsize
+
+ As mentioned above, the {\bf list} command lists what is in the
+ database. Some things are put into the database immediately when Bacula
+ starts up, but in general, most things are put in only when they are
+ first used, which is the case for a Client as with Job records, etc.
+
+ Bacula should create a client record in the database the first time you
+ run a job for that client. Doing a {\bf status} will not cause a
+ database record to be created. The client database record will be
+ created whether or not the job fails, but it must at least start. When
+ the Client is actually contacted, additional info from the client will
+ be added to the client record (a "uname -a" output).
+
+ If you want to see what Client resources you have available in your conf
+ file, you use the Console command {\bf show clients}.
+
+\item [llist]
+ \index[general]{llist}
+ The llist or "long list" command takes all the same arguments that the
+ list command described above does. The difference is that the llist
+ command list the full contents of each database record selected. It
+ does so by listing the various fields of the record vertically, with one
+ field per line. It is possible to produce a very large number of output
+ lines with this command.
+
+ If instead of the {\bf list pools} as in the example above, you enter
+ {\bf llist pools} you might get the following output:
+
+\footnotesize
+\begin{verbatim}
+ PoolId: 1
+ Name: Default
+ NumVols: 0
+ MaxVols: 0
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 1,296,000
+ VolUseDuration: 86,400
+ MaxVolJobs: 0
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: *
+
+ PoolId: 2
+ Name: Recycle
+ NumVols: 0
+ MaxVols: 8
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 3,600
+ VolUseDuration: 3,600
+ MaxVolJobs: 1
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: File
+
+\end{verbatim}
+\normalsize
+
+\item [messages]
+ \index[general]{messages}
+ This command causes any pending console messages to be immediately displayed.
+
+\item [memory]
+ \index[general]{memory}
+ Print current memory usage.
+
+
+\item [mount]
+ \index[general]{mount}
+ The mount command is used to get Bacula to read a volume on a physical
+ device. It is a way to tell Bacula that you have mounted a tape and
+ that Bacula should examine the tape. This command is normally
+ used only after there was no Volume in a drive and Bacula requests you to mount a new
+ Volume or when you have specifically unmounted a Volume with the {\bf
+ unmount} console command, which causes Bacula to close the drive. If
+ you have an autoloader, the mount command will not cause Bacula to
+ operate the autoloader unless you specify a {\bf slot} and possibly a
+ {\bf drive}. The various forms of the mount command are:
+
+mount storage=\lt{}storage-name\gt{} [ slot=\lt{}num\gt{} ] [
+ drive=\lt{}num\gt{} ]
+
+mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
+
+ If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
+ Device resource, under most circumstances, Bacula will automatically access
+ the Volume unless you have explicitly {\bf unmount}ed it in the Console
+ program.
+
+\label{ManualPruning}
+\item [prune]
+ \index[general]{prune}
+ The Prune command allows you to safely remove expired database records from
+ Jobs, Volumes and Statistics. This command works only on the Catalog
+ database and does not affect data written to Volumes. In all cases, the
+ Prune command applies a retention period to the specified records. You can
+ Prune expired File entries from Job records; you can Prune expired Job
+ records from the database, and you can Prune both expired Job and File
+ records from specified Volumes.
+
+prune files|jobs|volume|stats client=\lt{}client-name\gt{}
+volume=\lt{}volume-name\gt{}
+
+ For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
+ Append, otherwise the pruning will not take place.
+
+\item [purge]
+ \index[general]{purge}
+ The Purge command will delete associated Catalog database records from
+ Jobs and Volumes without considering the retention period. {\bf Purge}
+ works only on the Catalog database and does not affect data written to
+ Volumes. This command can be dangerous because you can delete catalog
+ records associated with current backups of files, and we recommend that
+ you do not use it unless you know what you are doing. The permitted
+ forms of {\bf purge} are:
+
+purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
+
+purge jobs client=\lt{}client-name\gt{} (of all jobs)
+
+purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
+
+For the {\bf purge} command to work on Volume Catalog database records the
+{\bf VolStatus} must be Append, Full, Used, or Error.
+
+The actual data written to the Volume will be unaffected by this command.
+
+\item[python]
+ \index[general]{python}
+ The python command takes a single argument {\bf restart}:
+
+python restart
+
+ This causes the Python interpreter in the Director to be reinitialized.
+ This can be helpful for testing because once the Director starts and the
+ Python interpreter is initialized, there is no other way to make it
+ accept any changes to the startup script {\bf DirStartUp.py}. For more
+ details on Python scripting, please see the \ilink{Python
+ Scripting}{PythonChapter} chapter of this manual.
+
+\item [query]
+ \index[general]{query}
+ This command reads a predefined SQL query from the query file (the name and
+ location of the query file is defined with the QueryFile resource record in
+ the Director's configuration file). You are prompted to select a query from
+ the file, and possibly enter one or more parameters, then the command is
+ submitted to the Catalog database SQL engine.
+
+The following queries are currently available (version 2.2.7):
+
+\footnotesize
+\begin{verbatim}
+Available queries:
+1: List up to 20 places where a File is saved regardless of the directory
+2: List where the most recent copies of a file are saved
+3: List last 20 Full Backups for a Client
+4: List all backups for a Client after a specified time
+5: List all backups for a Client
+6: List Volume Attributes for a selected Volume
+7: List Volumes used by selected JobId
+8: List Volumes to Restore All Files
+9: List Pool Attributes for a selected Pool
+10: List total files/bytes by Job
+11: List total files/bytes by Volume
+12: List Files for a selected JobId
+13: List Jobs stored on a selected MediaId
+14: List Jobs stored for a given Volume name
+15: List Volumes Bacula thinks are in changer
+16: List Volumes likely to need replacement from age or errors
+Choose a query (1-16):
+\end{verbatim}
+\normalsize
+
+\item [quit]
+ \index[general]{quit}
+ This command terminates the console program. The console program sends the
+ {\bf quit} request to the Director and waits for acknowledgment. If the
+ Director is busy doing a previous command for you that has not terminated, it
+ may take some time. You may quit immediately by issuing the {\bf .quit}
+ command (i.e. quit preceded by a period).
+
+\item [relabel]
+ \index[general]{relabel}
+ \index[general]{relabel}
+ This command is used to label physical volumes. The full form of this
+ command is:
+
+relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
+ volume=\lt{}newvolume-name\gt{}
+
+ If you leave out any part, you will be prompted for it. In order for
+ the Volume (old-volume-name) to be relabeled, it must be in the catalog,
+ and the volume status must be marked {\bf Purged} or {\bf Recycle}.
+ This happens automatically as a result of applying retention periods, or
+ you may explicitly purge the volume using the {\bf purge} command.
+
+ Once the volume is physically relabeled, the old data previously written
+ on the Volume is lost and cannot be recovered.
+
+\item [release]
+ \index[general]{release}
+ This command is used to cause the Storage daemon to rewind (release) the
+ current tape in the drive, and to re-read the Volume label the next time
+ the tape is used.
+
+release storage=\lt{}storage-name\gt{}
+
+ After a release command, the device is still kept open by Bacula (unless
+ Always Open is set to No in the Storage Daemon's configuration) so it
+ cannot be used by another program. However, with some tape drives, the
+ operator can remove the current tape and to insert a different one, and
+ when the next Job starts, Bacula will know to re-read the tape label to
+ find out what tape is mounted. If you want to be able to use the drive
+ with another program (e.g. {\bf mt}), you must use the {\bf unmount}
+ command to cause Bacula to completely release (close) the device.
+
+\item [reload]
+ \index[general]{reload}
+ The reload command causes the Director to re-read its configuration
+ file and apply the new values. The new values will take effect
+ immediately for all new jobs. However, if you change schedules,
+ be aware that the scheduler pre-schedules jobs up to two hours in
+ advance, so any changes that are to take place during the next two
+ hours may be delayed. Jobs that have already been scheduled to run
+ (i.e. surpassed their requested start time) will continue with the
+ old values. New jobs will use the new values. Each time you issue
+ a reload command while jobs are running, the prior config values
+ will queued until all jobs that were running before issuing
+ the reload terminate, at which time the old config values will
+ be released from memory. The Directory permits keeping up to
+ ten prior set of configurations before it will refuse a reload
+ command. Once at least one old set of config values has been
+ released it will again accept new reload commands.
+
+ While it is possible to reload the Director's configuration on the fly,
+ even while jobs are executing, this is a complex operation and not
+ without side effects. Accordingly, if you have to reload the Director's
+ configuration while Bacula is running, it is advisable to restart the
+ Director at the next convenient opportunity.
+
+\label{restore_command}
+\item [restore]
+ \index[general]{restore}
+ The restore command allows you to select one or more Jobs (JobIds) to be
+ restored using various methods. Once the JobIds are selected, the File
+ records for those Jobs are placed in an internal Bacula directory tree,
+ and the restore enters a file selection mode that allows you to
+ interactively walk up and down the file tree selecting individual files
+ to be restored. This mode is somewhat similar to the standard Unix {\bf
+ restore} program's interactive file selection mode.
+
+restore storage=\lt{}storage-name\gt{} client=\lt{}backup-client-name\gt{}
+ where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
+ restoreclient=\lt{}restore-client-name\gt{}
+ select current all done
+
+ Where {\bf current}, if specified, tells the restore command to
+ automatically select a restore to the most current backup. If not
+ specified, you will be prompted. The {\bf all} specification tells the
+ restore command to restore all files. If it is not specified, you will
+ be prompted for the files to restore. For details of the {\bf restore}
+ command, please see the \ilink{Restore Chapter}{RestoreChapter} of this
+ manual.
+
+ The client keyword initially specifies the client from which the backup
+ was made and the client to which the restore will be make. However,
+ if the restoreclient keyword is specified, then the restore is written
+ to that client.
+
+\item [run]
+ \index[general]{run}
+ This command allows you to schedule jobs to be run immediately. The full form
+ of the command is:
+
+run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
+ fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
+ storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
+ when=\lt{}universal-time-specification\gt{} spooldata=yes|no yes
+
+ Any information that is needed but not specified will be listed for
+ selection, and before starting the job, you will be prompted to accept,
+ reject, or modify the parameters of the job to be run, unless you have
+ specified {\bf yes}, in which case the job will be immediately sent to
+ the scheduler.
+
+ On my system, when I enter a run command, I get the following prompt:
+
+\footnotesize
+\begin{verbatim}
+A job name must be specified.
+The defined Job resources are:
+ 1: Matou
+ 2: Polymatou
+ 3: Rufus
+ 4: Minimatou
+ 5: Minou
+ 6: PmatouVerify
+ 7: MatouVerify
+ 8: RufusVerify
+ 9: Watchdog
+Select Job resource (1-9):
+
+\end{verbatim}
+\normalsize
+
+If I then select number 5, I am prompted with:
+
+\footnotesize
+\begin{verbatim}
+Run Backup job
+JobName: Minou
+FileSet: Minou Full Set
+Level: Incremental
+Client: Minou
+Storage: DLTDrive
+Pool: Default
+When: 2003-04-23 17:08:18
+OK to run? (yes/mod/no):
+
+\end{verbatim}
+\normalsize
+
+If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
+be presented with the following prompt.
+
+\footnotesize
+\begin{verbatim}
+Parameters to modify:
+ 1: Level
+ 2: Storage
+ 3: Job
+ 4: FileSet
+ 5: Client
+ 6: When
+ 7: Pool
+Select parameter to modify (1-7):
+
+\end{verbatim}
+\normalsize
+
+If you wish to start a job at a later time, you can do so by setting the When
+time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
+desired start time in YYYY-MM-DD HH:MM:SS format.
+
+The spooldata argument of the run command cannot be modified through the menu
+and is only accessible by setting its value on the intial command line. If
+no spooldata flag is set, the job, storage or schedule flag is used.
+
+\item [setdebug]
+ \index[general]{setdebug}
+ \index[general]{setdebug}
+ \index[general]{debugging}
+ \index[general]{debugging Win32}
+ \index[general]{Windows!debugging}
+ This command is used to set the debug level in each daemon. The form of this
+ command is:
+
+setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
+ storage=\lt{}storage-name\gt{} | all]
+
+ If trace=1 is set, then tracing will be enabled, and the daemon will be
+ placed in trace mode, which means that all debug output as set by the
+ debug level will be directed to the file {\bf bacula.trace} in the
+ current directory of the daemon. Normally, tracing is needed only for
+ Win32 clients where the debug output cannot be written to a terminal or
+ redirected to a file. When tracing, each debug output message is
+ appended to the trace file. You must explicitly delete the file when
+ you are done.
+
+\item [setip]
+ \index[general]{setip}
+ Sets new client address -- if authorized.
+
+
+\item [show]
+ \index[general]{show}
+ \index[general]{show}
+ The show command will list the Director's resource records as defined in
+ the Director's configuration file (normally {\bf bacula-dir.conf}).
+ This command is used mainly for debugging purposes by developers.
+ The following keywords are accepted on the
+ show command line: catalogs, clients, counters, devices, directors,
+ filesets, jobs, messages, pools, schedules, storages, all, help.
+ Please don't confuse this command
+ with the {\bf list}, which displays the contents of the catalog.
+
+\item [sqlquery]
+ \index[general]{sqlquery}
+ The sqlquery command puts the Console program into SQL query mode where
+ each line you enter is concatenated to the previous line until a
+ semicolon (;) is seen. The semicolon terminates the command, which is
+ then passed directly to the SQL database engine. When the output from
+ the SQL engine is displayed, the formation of a new SQL command begins.
+ To terminate SQL query mode and return to the Console command prompt,
+ you enter a period (.) in column 1.
+
+ Using this command, you can query the SQL catalog database directly.
+ Note you should really know what you are doing otherwise you could
+ damage the catalog database. See the {\bf query} command below for
+ simpler and safer way of entering SQL queries.
+
+ Depending on what database engine you are using (MySQL, PostgreSQL or
+ SQLite), you will have somewhat different SQL commands available. For
+ more detailed information, please refer to the MySQL, PostgreSQL or
+ SQLite documentation.
+
+\item [status]
+ \index[general]{status}
+
+ This command will display the status of all components. For the director, it
+ will display the next jobs that are scheduled during the next 24 hours as
+ well as the status of currently running jobs. For the Storage Daemon, you
+ will have drive status or autochanger content. The File Daemon will give you
+ information about current jobs like average speed or file accounting. The
+ full form of this command is:
+
+status [all | dir=\lt{}dir-name\gt{} | director [days=nnn] |
+ client=\lt{}client-name\gt{} | [slots] storage=\lt{}storage-name\gt{}]
+
+ If you do a {\bf status dir}, the console will list any currently
+ running jobs, a summary of all jobs scheduled to be run in the next 24
+ hours, and a listing of the last ten terminated jobs with their statuses.
+ The scheduled jobs summary will include the Volume name to be used. You
+ should be aware of two things: 1. to obtain the volume name, the code
+ goes through the same code that will be used when the job runs, but it
+ does not do pruning nor recycling of Volumes; 2. The Volume listed is
+ at best a guess. The Volume actually used may be different because of
+ the time difference (more durations may expire when the job runs) and
+ another job could completely fill the Volume requiring a new one.
+
+ In the Running Jobs listing, you may find the following types of
+ information:
+
+
+\footnotesize
+\begin{verbatim}
+2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
+5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
+ priority jobs to finish
+5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
+5343 Full Rufus.2004-03-13_01.05.04 is running
+\end{verbatim}
+\normalsize
+
+ Looking at the above listing from bottom to top, obviously JobId 5343
+ (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
+ finish because it is using the Storage resource, hence the "waiting on
+ max Storage jobs". JobId 5349 has a lower priority than all the other
+ jobs so it is waiting for higher priority jobs to finish, and finally,
+ JobId 2507 (MatouVerify) is waiting because only one job can run at a
+ time, hence it is simply "waiting execution"
+
+ If you do a {\bf status dir}, it will by default list the first
+ occurrence of all jobs that are scheduled today and tomorrow. If you
+ wish to see the jobs that are scheduled in the next three days (e.g. on
+ Friday you want to see the first occurrence of what tapes are scheduled
+ to be used on Friday, the weekend, and Monday), you can add the {\bf
+ days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs
+ scheduled today only. If you have multiple run statements, the first
+ occurrence of each run statement for the job will be displayed for the
+ period specified.
+
+ If your job seems to be blocked, you can get a general idea of the
+ problem by doing a {\bf status dir}, but you can most often get a
+ much more specific indication of the problem by doing a
+ {\bf status storage=xxx}. For example, on an idle test system, when
+ I do {\bf status storage=File}, I get:
+\footnotesize
+\begin{verbatim}
+status storage=File
+Connecting to Storage daemon File at 192.168.68.112:8103
+
+rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
+Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
+
+Running Jobs:
+No Jobs running.
+====
+
+Jobs waiting to reserve a drive:
+====
+
+Terminated Jobs:
+ JobId Level Files Bytes Status Finished Name
+======================================================================
+ 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
+====
+
+Device status:
+Autochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
+Pool="*unknown*"
+ Slot 2 is loaded in drive 0.
+ Total Bytes Read=0 Blocks Read=0 Bytes/block=0
+ Positioned at File=0 Block=0
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+====
+
+In Use Volume status:
+====
+\end{verbatim}
+\normalsize
+
+Now, what this tells me is that no jobs are running and that none of
+the devices are in use. Now, if I {\bf unmount} the autochanger, which
+will not be used in this example, and then start a Job that uses the
+File device, the job will block. When I re-issue the status storage
+command, I get for the Device status:
+
+\footnotesize
+\begin{verbatim}
+status storage=File
+...
+Device status:
+Autochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is not open.
+ Device is BLOCKED. User unmounted.
+ Drive 0 is not loaded.
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+ Device is BLOCKED waiting for media.
+====
+...
+\end{verbatim}
+\normalsize
+
+Now, here it should be clear that if a job were running that wanted
+to use the Autochanger (with two devices), it would block because
+the user unmounted the device. The real problem for the Job I started
+using the "File" device is that the device is blocked waiting for
+media -- that is Bacula needs you to label a Volume.
+
+\item [time]
+ \index[general]{time}
+ Prints the current time.
+
+\item [trace]
+ \index[general]{trace}
+ Turn on/off trace to file.
+
+\item [umount]
+ \index[general]{umount}
+ For old-time Unix guys. See the unmount command for full details.
+
+\item [unmount]
+ \index[general]{unmount}
+ This command causes the indicated Bacula Storage daemon to unmount the
+ specified device. The forms of the command are the same as the mount command:
+\footnotesize
+\begin{verbatim}
+unmount storage=<storage-name> [ drive=<num> ]
+
+unmount [ jobid=<id> | job=<job-name> ]
+\end{verbatim}
+\normalsize
+
+ Once you unmount a storage device, Bacula will no longer be able to use
+ it until you issue a mount command for that device. If Bacula needs to
+ access that device, it will block and issue mount requests periodically
+ to the operator.
+
+ If the device you are unmounting is an autochanger, it will unload
+ the drive you have specified on the command line. If no drive is
+ specified, it will assume drive 1.
+
+\label{UpdateCommand}
+\item [update]
+ \index[general]{update}
+ This command will update the catalog for either a specific Pool record, a Volume
+ record, or the Slots in an autochanger with barcode capability. In the case
+ of updating a Pool record, the new information will be automatically taken
+ from the corresponding Director's configuration resource record. It can be
+ used to increase the maximum number of volumes permitted or to set a maximum
+ number of volumes. The following main keywords may be specified:
+\footnotesize
+\begin{verbatim}
+ media, volume, pool, slots, stats
+\end{verbatim}
+\normalsize
+
+In the case of updating a Volume, you will be prompted for which value you
+wish to change. The following Volume parameters may be changed:
+
+\footnotesize
+\begin{verbatim}
+
+ Volume Status
+ Volume Retention Period
+ Volume Use Duration
+ Maximum Volume Jobs
+ Maximum Volume Files
+ Maximum Volume Bytes
+ Recycle Flag
+ Recycle Pool
+ Slot
+ InChanger Flag
+ Pool
+ Volume Files
+ Volume from Pool
+ All Volumes from Pool
+ All Volumes from all Pools
+
+\end{verbatim}
+\normalsize
+
+ For slots {\bf update slots}, Bacula will obtain a list of slots and
+ their barcodes from the Storage daemon, and for each barcode found, it
+ will automatically update the slot in the catalog Media record to
+ correspond to the new value. This is very useful if you have moved
+ cassettes in the magazine, or if you have removed the magazine and
+ inserted a different one. As the slot of each Volume is updated, the
+ InChanger flag for that Volume will also be set, and any other Volumes
+ in the Pool that were last mounted on the same Storage device
+ will have their InChanger flag turned off. This permits
+ Bacula to know what magazine (tape holder) is currently in the
+ autochanger.
+
+ If you do not have barcodes, you can accomplish the same thing in
+ version 1.33 and later by using the {\bf update slots scan} command.
+ The {\bf scan} keyword tells Bacula to physically mount each tape and to
+ read its VolumeName.
+
+ For Pool {\bf update pool}, Bacula will move the Volume record from its
+ existing pool to the pool specified.
+
+ For {\bf Volume from Pool}, {\bf All Volumes from Pool} and {\bf All Volumes
+ from all Pools}, the following values are updated from the Pool record:
+ Recycle, RecyclePool, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles,
+ and MaxVolBytes. (RecyclePool feature is available with bacula 2.1.4 or
+ higher.)
+
+ The full form of the update command with all command line arguments is:
+
+\footnotesize
+\begin{verbatim}
+ update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
+ VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
+ slot=nnn enabled=n recyclepool=zzz
+
+\end{verbatim}
+\normalsize
+
+\item [use]
+ \index[general]{use}
+ This command allows you to specify which Catalog database to use. Normally,
+you will be using only one database so this will be done automatically. In
+the case that you are using more than one database, you can use this command
+to switch from one to another.
+
+use \lt{}database-name\gt{}
+
+\item [var]
+ \label{var}
+ \index[general]{var name}
+ This command takes a string or quoted string and does variable expansion on
+ it the same way variable expansion is done on the {\bf LabelFormat} string.
+ Thus, for the most part, you can test your LabelFormat strings. The
+ difference between the {\bf var} command and the actual LabelFormat process
+ is that during the var command, no job is running so "dummy" values are
+ used in place of Job specific variables. Generally, however, you will get a
+ good idea of what is going to happen in the real case.
+
+\item [version]
+ \index[general]{version}
+ The command prints the Director's version.
+
+\item [wait]
+ \index[general]{wait}
+ The wait command causes the Director to pause until there are no jobs
+ running. This command is useful in a batch situation such as regression
+ testing where you wish to start a job and wait until that job completes
+ before continuing. This command now has the following options:
+\footnotesize
+\begin{verbatim}
+ wait [jobid=nn] [jobuid=unique id] [job=job name]
+\end{verbatim}
+\normalsize
+ If specified with a specific JobId, ... the wait command will wait
+ for that particular job to terminate before continuing.
+
+\end{description}
+
+\label{dotcommands}
+\section{Special dot Commands}
+\index[general]{Commands!Special dot}
+\index[general]{Special dot Commands}
+
+There is a list of commands that are prefixed with a period (.). These
+commands are intended to be used either by batch programs or graphical user
+interface front-ends. They are not normally used by interactive users. Once
+GUI development begins, this list will be considerably expanded. The following
+is the list of dot commands:
+
+\footnotesize
+\begin{verbatim}
+.backups job=xxx list backups for specified job
+.clients list all client names
+.defaults client=xxx fileset=yyy list defaults for specified client
+.die cause the Director to segment fault (for debugging)
+.dir when in tree mode prints the equivalent to the dir command,
+ but with fields separated by commas rather than spaces.
+.exit quit
+.filesets list all fileset names
+.help help command output
+.jobs list all job names
+.levels list all levels
+.messages get quick messages
+.msgs return any queued messages
+.pools list all pool names
+.quit quit
+.status get status output
+.storage return storage resource names
+.types list job types
+\end{verbatim}
+\normalsize
+
+\label{atcommands}
+
+\section{Special At (@) Commands}
+\index[general]{Commands!Special At @}
+\index[general]{Special At (@) Commands}
+
+Normally, all commands entered to the Console program are immediately
+forwarded to the Director, which may be on another machine, to be executed.
+However, there is a small list of {\bf at} commands, all beginning with an at
+character (@), that will not be sent to the Director, but rather interpreted
+by the Console program directly. Note, these commands are implemented only in
+the tty console program and not in the Bat Console. These commands are:
+
+\begin{description}
+
+\item [@input \lt{}filename\gt{}]
+ \index[general]{@input \lt{}filename\gt{}}
+ Read and execute the commands contained in the file specified.
+
+\item [@output \lt{}filename\gt{} w/a]
+ \index[general]{@output \lt{}filename\gt{} w/a}
+ Send all following output to the filename specified either overwriting the
+file (w) or appending to the file (a). To redirect the output to the
+terminal, simply enter {\bf @output} without a filename specification.
+WARNING: be careful not to overwrite a valid file. A typical example during a
+regression test might be:
+
+\footnotesize
+\begin{verbatim}
+ @output /dev/null
+ commands ...
+ @output
+
+\end{verbatim}
+\normalsize
+
+\item [@tee \lt{}filename\gt{} w/a]
+ \index[general]{@tee \lt{}filename\gt{} w/a}
+ Send all subsequent output to both the specified file and the terminal. It is
+ turned off by specifying {\bf @tee} or {\bf @output} without a filename.
+
+\item [@sleep \lt{}seconds\gt{}]
+ \index[general]{@sleep \lt{}seconds\gt{}}
+ Sleep the specified number of seconds.
+
+\item [@time]
+ \index[general]{@time}
+ Print the current time and date.
+
+\item [@version]
+ \index[general]{@version}
+ Print the console's version.
+
+\item [@quit]
+ \index[general]{@quit}
+ quit
+
+\item [@exit]
+ \index[general]{@exit}
+ quit
+
+\item [@\# anything]
+ \index[general]{anything}
+ Comment
+
+\item [@help]
+ \index[general]{@help}
+ Get the list of every special @ commands.
+
+\item [@separator \lt{}char\gt{}]
+\index[general]{@separator}
+ When using bconsole with readline, you can set the command separator to one
+ of those characters to write commands who require multiple input on one line,
+ or to put multiple commands on a single line.
+\begin{verbatim}
+ !$%&'()*+,-/:;<>?[]^`{|}~
+\end{verbatim}
+
+ Note, if you use a semicolon (;) as a separator character, which is
+ common, you will not be able to use the {\bf sql} command, which
+ requires each command to be terminated by a semicolon.
+
+\end{description}
+
+\label{scripting}
+\section{Running the Console from a Shell Script}
+\index[general]{Script!Running the Console Program from a Shell}
+\index[general]{Running the Console Program from a Shell Script}
+
+You can automate many Console tasks by running the console program from a
+shell script. For example, if you have created a file containing the following
+commands:
+
+\footnotesize
+\begin{verbatim}
+ ./bconsole -c ./bconsole.conf <<END_OF_DATA
+ unmount storage=DDS-4
+ quit
+ END_OF_DATA
+\end{verbatim}
+\normalsize
+
+when that file is executed, it will unmount the current DDS-4 storage device.
+You might want to run this command during a Job by using the {\bf
+RunBeforeJob} or {\bf RunAfterJob} records.
+
+It is also possible to run the Console program from file input where the file
+contains the commands as follows:
+
+\footnotesize
+\begin{verbatim}
+./bconsole -c ./bconsole.conf <filename
+\end{verbatim}
+\normalsize
+
+where the file named {\bf filename} contains any set of console commands.
+
+As a real example, the following script is part of the Bacula regression
+tests. It labels a volume (a disk volume), runs a backup, then does a restore
+of the files saved.
+
+\footnotesize
+\begin{verbatim}
+bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
+@output /dev/null
+messages
+@output /tmp/log1.out
+label volume=TestVolume001
+run job=Client1 yes
+wait
+messages
+@#
+@# now do a restore
+@#
+@output /tmp/log2.out
+restore current all
+yes
+wait
+messages
+@output
+quit
+END_OF_DATA
+\end{verbatim}
+\normalsize
+
+The output from the backup is directed to /tmp/log1.out and the output from
+the restore is directed to /tmp/log2.out. To ensure that the backup and
+restore ran correctly, the output files are checked with:
+
+\footnotesize
+\begin{verbatim}
+grep "^Termination: *Backup OK" /tmp/log1.out
+backupstat=$?
+grep "^Termination: *Restore OK" /tmp/log2.out
+restorestat=$?
+\end{verbatim}
+\normalsize
+
+\section{Adding Volumes to a Pool}
+\index[general]{Adding Volumes to a Pool}
+\index[general]{Pool!Adding Volumes to a}
+
+If you have used the {\bf label} command to label a Volume, it will be
+automatically added to the Pool, and you will not need to add any media to the
+pool.
+
+Alternatively, you may choose to add a number of Volumes to the pool without
+labeling them. At a later time when the Volume is requested by {\bf Bacula}
+you will need to label it.
+
+Before adding a volume, you must know the following information:
+
+\begin{enumerate}
+\item The name of the Pool (normally "Default")
+\item The Media Type as specified in the Storage Resource in the Director's
+ configuration file (e.g. "DLT8000")
+\item The number and names of the Volumes you wish to create.
+\end{enumerate}
+
+For example, to add media to a Pool, you would issue the following commands to
+the console program:
+
+\footnotesize
+\begin{verbatim}
+*add
+Enter name of Pool to add Volumes to: Default
+Enter the Media Type: DLT8000
+Enter number of Media volumes to create. Max=1000: 10
+Enter base volume name: Save
+Enter the starting number: 1
+10 Volumes created in pool Default
+*
+\end{verbatim}
+\normalsize
+
+To see what you have added, enter:
+
+\footnotesize
+\begin{verbatim}
+*list media pool=Default
++-------+----------+---------+---------+-------+------------------+
+| MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
++-------+----------+---------+---------+-------+------------------+
+| 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
++-------+----------+---------+---------+-------+------------------+
+*
+\end{verbatim}
+\normalsize
+
+Notice that the console program automatically appended a number to the base
+Volume name that you specify (Save in this case). If you don't want it to
+append a number, you can simply answer 0 (zero) to the question "Enter number
+of Media volumes to create. Max=1000:", and in this case, it will create a
+single Volume with the exact name you specify.
--- /dev/null
+%%
+%%
+%% The following characters must be preceded by a backslash
+%% to be entered as printable characters:
+%%
+%% # $ % & ~ _ ^ \ { }
+%%
+
+\documentclass[10pt,a4paper]{book}
+
+\topmargin -0.5in
+\oddsidemargin 0.0in
+\evensidemargin 0.0in
+\textheight 10in
+\textwidth 6.5in
+
+\usepackage{html}
+\usepackage{float}
+\usepackage{graphicx}
+\usepackage{bacula}
+\usepackage{longtable}
+\usepackage{makeidx}
+\usepackage{index}
+\usepackage{setspace}
+\usepackage{hyperref}
+\usepackage{url}
+
+
+\makeindex
+\newindex{general}{idx}{ind}{General Index}
+
+\sloppy
+
+\begin{document}
+\sloppy
+
+\newfont{\bighead}{cmr17 at 36pt}
+\parskip 10pt
+\parindent 0pt
+
+\title{\includegraphics{\idir bacula-logo.eps} \\ \bigskip
+ \Huge{Bacula Console and Operators Guide}
+ \begin{center}
+ \large{It comes in the night and sucks
+ the essence from your computers. }
+ \end{center}
+}
+
+
+\author{Kern Sibbald}
+\date{\vspace{1.0in}\today \\
+ This manual documents Bacula version \input{version} \\
+ \vspace{0.2in}
+ Copyright \copyright 1999-2010, Free Software Foundation Europe
+ e.V. \\
+ \vspace{0.2in}
+ Permission is granted to copy, distribute and/or modify this document under the terms of the
+ GNU Free Documentation License, Version 1.2 published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU Free Documentation License".
+}
+
+\maketitle
+
+\clearpage
+\tableofcontents
+\clearpage
+
+\include{bconsole}
+\include{fdl}
+
+
+% The following line tells link_resolver.pl to not include these files:
+% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main
+
+% pull in the index
+\clearpage
+\printindex[general]
+
+\end{document}
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
--- /dev/null
+5.1.2 (26 February 2010)
--- /dev/null
+%%
+%%
+
+\chapter{Bacula Console}
+\label{_ConsoleChapter}
+\index[general]{Console!Bacula}
+\index[general]{Bacula Console}
+\index[general]{Console!Bacula}
+\index[general]{Bacula Console}
+
+The {\bf Bacula Console} (sometimes called the User Agent) is a program that
+allows the user or the System Administrator, to interact with the Bacula
+Director daemon while the daemon is running.
+
+The current Bacula Console comes in two versions: a shell interface (TTY
+style), and a QT GUI interface (Bat). Both permit the administrator or
+authorized users to interact with Bacula. You can determine the status of a
+particular job, examine the contents of the Catalog as well as perform certain
+tape manipulations with the Console program.
+
+In addition, there is a bwx-console built with wxWidgets that allows a graphic
+restore of files. As of version 1.34.1 it is in an early stage of development,
+but it already is quite useful. Unfortunately, it has not been enhanced for
+some time now.
+
+Since the Console program interacts with the Director through the network, your
+Console and Director programs do not necessarily need to run on the same
+machine.
+
+In fact, a certain minimal knowledge of the Console program is needed in order
+for Bacula to be able to write on more than one tape, because when Bacula
+requests a new tape, it waits until the user, via the Console program,
+indicates that the new tape is mounted.
+
+\section{Console Configuration}
+\index[general]{Console Configuration}
+\index[general]{Configuration!Console}
+\index[general]{Console Configuration}
+\index[general]{Configuration!Console}
+
+When the Console starts, it reads a standard Bacula configuration file
+named {\bf bconsole.conf} or {\bf bat.conf} in the case of the Bat
+QT Console version from the current directory unless you specify the {\bf {-}c}
+command line option (see below). This file allows default configuration
+of the Console, and at the current time, the only Resource Record defined
+is the Director resource, which gives the Console the name and address of
+the Director. For more information on configuration of the Console
+program, please see the \ilink{Console Configuration
+File}{ConsoleConfChapter} Chapter of this document.
+
+\section{Running the Console Program}
+\index[general]{Running the Console Program}
+\index[general]{Program!Running the Console}
+\index[general]{Running the Console Program}
+\index[general]{Program!Running the Console}
+
+The console program can be run with the following options:
+\footnotesize
+\begin{verbatim}
+Usage: bconsole [-s] [-c config_file] [-d debug_level]
+ -c <file> set configuration file to file
+ -dnn set debug level to nn
+ -n no conio
+ -s no signals
+ -u <nn> set command execution timeout to <nn> seconds
+ -t test - read configuration and exit
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+
+After launching the Console program (bconsole), it will prompt you for the next
+command with an asterisk (*). Generally, for all commands, you can simply
+enter the command name and the Console program will prompt you for the
+necessary arguments. Alternatively, in most cases, you may enter the command
+followed by arguments. The general format is:
+
+\footnotesize
+\begin{verbatim}
+ <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
+\end{verbatim}
+\normalsize
+
+where {\bf command} is one of the commands listed below; {\bf keyword} is one
+of the keywords listed below (usually followed by an argument); and {\bf
+argument} is the value. The command may be abbreviated to the shortest unique
+form. If two commands have the same starting letters, the one that will be
+selected is the one that appears first in the {\bf help} listing. If you want
+the second command, simply spell out the full command. None of the keywords
+following the command may be abbreviated.
+
+For example:
+
+\footnotesize
+\begin{verbatim}
+list files jobid=23
+\end{verbatim}
+\normalsize
+
+will list all files saved for JobId 23. Or:
+
+\footnotesize
+\begin{verbatim}
+show pools
+\end{verbatim}
+\normalsize
+
+will display all the Pool resource records.
+
+The maximum command line length is limited to 511 characters, so if you
+are scripting the console, you may need to take some care to limit the
+line length.
+
+\section{Stopping the Console Program}
+\index[general]{Program!Stopping the Console}
+\index[general]{Stopping the Console Program}
+\index[general]{Program!Stopping the Console}
+\index[general]{Stopping the Console Program}
+
+Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
+will terminate. However, it waits until the Director acknowledges the command.
+If the Director is already doing a lengthy command (e.g. prune), it may take
+some time. If you want to immediately terminate the Console program, enter the
+{\bf .quit} command.
+
+There is currently no way to interrupt a Console command once issued (i.e.
+Ctrl-C does not work). However, if you are at a prompt that is asking you to
+select one of several possibilities and you would like to abort the command,
+you can enter a period ({\bf .}), and in most cases, you will either be
+returned to the main command prompt or if appropriate the previous prompt (in
+the case of nested prompts). In a few places such as where it is asking for a
+Volume name, the period will be taken to be the Volume name. In that case, you
+will most likely be able to cancel at the next prompt.
+
+\label{keywords}
+\section{Alphabetic List of Console Keywords}
+\index[general]{Keywords!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Keywords}
+\index[general]{Keywords!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Keywords}
+Unless otherwise specified, each of the following keywords
+takes an argument, which is specified after the keyword following
+an equal sign. For example:
+
+\begin{verbatim}
+jobid=536
+\end{verbatim}
+
+Please note, this list is incomplete as it is currently in
+the process of being created and is not currently totally in
+alphabetic
+order ...
+
+\begin{description}
+\item [restart]
+ Permitted on the python command, and causes the Python
+ interpreter to be restarted. Takes no argument.
+\item [all]
+ Permitted on the status and show commands to specify all components or
+ resources respectively.
+\item [allfrompool]
+ Permitted on the update command to specify that all Volumes in the
+ pool (specified on the command line) should be updated.
+\item [allfrompools]
+ Permitted on the update command to specify that all Volumes in all
+ pools should be updated.
+\item [before]
+ Used in the restore command.
+\item [bootstrap]
+ Used in the restore command.
+\item [catalog]
+ Allowed in the use command to specify the catalog name
+ to be used.
+\item [catalogs]
+ Used in the show command. Takes no arguments.
+\item [client | fd]
+\item [clients]
+ Used in the show, list, and llist commands. Takes no arguments.
+\item [counters]
+ Used in the show command. Takes no arguments.
+\item [current]
+ Used in the restore command. Takes no argument.
+\item [days]
+ Used to define the number of days the "list nextvol" command
+ should consider when looking for jobs to be run. The days keyword
+ can also be used on the "status dir" command so that it will display
+ jobs scheduled for the number of days you want.
+\item [devices]
+ Used in the show command. Takes no arguments.
+\item [dir | director]
+\item [directors]
+ Used in the show command. Takes no arguments.
+\item [directory]
+ Used in the restore command. Its argument specifies the directory
+ to be restored.
+\item [enabled]
+ This keyword can appear on the {\bf update volume} as well
+ as the {\bf update slots} commands, and can
+ allows one of the following arguments: yes, true, no, false, archived,
+ 0, 1, 2. Where 0 corresponds to no or false, 1 corresponds to yes or true, and
+ 2 corresponds to archived. Archived volumes will not be used, nor will
+ the Media record in the catalog be pruned. Volumes that are not enabled,
+ will not be used for backup or restore.
+\item [done]
+ Used in the restore command. Takes no argument.
+\item [file]
+ Used in the restore command.
+\item [files]
+ Used in the list and llist commands. Takes no arguments.
+\item [fileset]
+\item [filesets]
+ Used in the show command. Takes no arguments.
+\item [help]
+ Used in the show command. Takes no arguments.
+\item [jobs]
+ Used in the show, list and llist commands. Takes no arguments.
+\item [jobmedia]
+ Used in the list and llist commands. Takes no arguments.
+\item [jobtotals]
+ Used in the list and llist commands. Takes no arguments.
+\item [jobid]
+ The JobId is the numeric jobid that is printed in the Job
+ Report output. It is the index of the database record for the
+ given job. While it is unique for all the existing Job records
+ in the catalog database, the same JobId can be reused once a
+ Job is removed from the catalog. Probably you will refer
+ specific Jobs that ran using their numeric JobId.
+\item [job | jobname]
+ The Job or Jobname keyword refers to the name you specified
+ in the Job resource, and hence it refers to any number of
+ Jobs that ran. It is typically useful if you want to list
+ all jobs of a particular name.
+\item [level]
+\item [listing]
+ Permitted on the estimate command. Takes no argument.
+\item [limit]
+\item [messages]
+ Used in the show command. Takes no arguments.
+\item [media]
+ Used in the list and llist commands. Takes no arguments.
+\item [nextvol | nextvolume]
+ Used in the list and llist commands. Takes no arguments.
+\item [on]
+ Takes no keyword.
+\item [off]
+ Takes no keyword.
+\item [pool]
+\item [pools]
+ Used in the show, list, and llist commands. Takes no arguments.
+\item [select]
+ Used in the restore command. Takes no argument.
+\item [storages]
+ Used in the show command. Takes no arguments.
+\item [schedules]
+ Used in the show command. Takes no arguments.
+\item [sd | store | storage]
+\item [ujobid]
+ The ujobid is a unique job identification that is printed
+ in the Job Report output. At the current time, it consists
+ of the Job name (from the Name directive for the job) appended
+ with the date and time the job was run. This keyword is useful
+ if you want to completely identify the Job instance run.
+\item [volume]
+\item [volumes]
+ Used in the list and llist commands. Takes no arguments.
+\item [where]
+ Used in the restore command.
+\item [yes]
+ Used in the restore command. Takes no argument.
+\end{description}
+
+\label{list}
+\section{Alphabetic List of Console Commands}
+\index[general]{Commands!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Commands}
+\index[general]{Commands!Alphabetic List of Console}
+\index[general]{Alphabetic List of Console Commands}
+
+The following commands are currently implemented:
+
+\begin{description}
+\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
+ jobid=\lt{}JobId\gt{}]} ]
+ \index[general]{add}
+ This command is used to add Volumes to an existing Pool. That is,
+ it creates the Volume name in the catalog and inserts into the Pool
+ in the catalog, but does not attempt to access the physical Volume.
+ Once
+ added, Bacula expects that Volume to exist and to be labeled.
+ This command is not normally used since Bacula will
+ automatically do the equivalent when Volumes are labeled. However,
+ there may be times when you have removed a Volume from the catalog
+ and want to later add it back.
+
+ Normally, the {\bf label} command is used rather than this command
+ because the {\bf label} command labels the physical media (tape, disk,
+ DVD, ...) and does the equivalent of the {\bf add} command. The {\bf
+ add} command affects only the Catalog and not the physical media (data
+ on Volumes). The physical media must exist and be labeled before use
+ (usually with the {\bf label} command). This command can, however, be
+ useful if you wish to add a number of Volumes to the Pool that will be
+ physically labeled at a later time. It can also be useful if you are
+ importing a tape from another site. Please see the {\bf label} command
+ below for the list of legal characters in a Volume name.
+
+\item [autodisplay on/off]
+ \index[general]{autodisplay on/off}
+ This command accepts {\bf on} or {\bf off} as an argument, and turns
+ auto-display of messages on or off respectively. The default for the
+ console program is {\bf off}, which means that you will be notified when
+ there are console messages pending, but they will not automatically be
+ displayed.
+
+ When autodisplay is turned off, you must explicitly retrieve the
+ messages with the {\bf messages} command. When autodisplay is turned
+ on, the messages will be displayed on the console as they are received.
+
+\item [automount on/off]
+ \index[general]{automount on/off}
+ This command accepts {\bf on} or {\bf off} as the argument, and turns
+ auto-mounting of the Volume after a {\bf label} command on or off
+ respectively. The default is {\bf on}. If {\bf automount} is turned
+ off, you must explicitly {\bf mount} tape Volumes after a label command to
+ use it.
+
+\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
+ \index[general]{cancel jobid}
+ This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
+ job=xxx} as an argument where nnn is replaced by the JobId and xxx is
+ replaced by the job name. If you do not specify a keyword, the Console
+ program will prompt you with the names of all the active jobs allowing
+ you to choose one.
+
+ Once a Job is marked to be canceled, it may take a bit of time
+ (generally within a minute but up to two hours) before the Job actually
+ terminates, depending on what operations it is doing.
+ Don't be surprised that you receive a Job not found message. That just
+ means that one of the three daemons had already canceled the job.
+ Messages numbered in the 1000's are from the Director, 2000's are from
+ the File daemon and 3000's from the Storage daemon.
+
+
+\item [{create [pool=\lt{}pool-name\gt{}]}]
+ \index[general]{create pool}
+ This command is not normally used as the Pool records are automatically
+ created by the Director when it starts based on what it finds in
+ the conf file. If needed, this command can be
+ to create a Pool record in the database using the
+ Pool resource record defined in the Director's configuration file. So
+ in a sense, this command simply transfers the information from the Pool
+ resource in the configuration file into the Catalog. Normally this
+ command is done automatically for you when the Director starts providing
+ the Pool is referenced within a Job resource. If you use this command
+ on an existing Pool, it will automatically update the Catalog to have
+ the same information as the Pool resource. After creating a Pool, you
+ will most likely use the {\bf label} command to label one or more
+ volumes and add their names to the Media database.
+
+ When starting a Job, if Bacula determines that there is no Pool record
+ in the database, but there is a Pool resource of the appropriate name,
+ it will create it for you. If you want the Pool record to appear in the
+ database immediately, simply use this command to force it to be created.
+
+\item [{delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
+ jobid=\lt{}id\gt{}]}]
+ \index[general]{delete}
+ The delete command is used to delete a Volume, Pool or Job record from
+ the Catalog as well as all associated catalog Volume records that were
+ created. This command operates only on the Catalog database and has no
+ effect on the actual data written to a Volume. This command can be
+ dangerous and we strongly recommend that you do not use it unless you
+ know what you are doing.
+
+ If the keyword {\bf Volume} appears on the command line, the named
+ Volume will be deleted from the catalog, if the keyword {\bf Pool}
+ appears on the command line, a Pool will be deleted, and if the keyword
+ {\bf Job} appears on the command line, a Job and all its associated
+ records (File and JobMedia) will be deleted from the catalog. The full
+ form of this command is:
+
+\begin{verbatim}
+delete pool=<pool-name>
+\end{verbatim}
+
+ or
+
+\begin{verbatim}
+delete volume=<volume-name> pool=<pool-name> or
+\end{verbatim}
+
+\begin{verbatim}
+delete JobId=<job-id> JobId=<job-id2> ... or
+\end{verbatim}
+
+\begin{verbatim}
+delete Job JobId=n,m,o-r,t ...
+\end{verbatim}
+
+ The first form deletes a Pool record from the catalog database. The
+ second form deletes a Volume record from the specified pool in the
+ catalog database. The third form deletes the specified Job record from
+ the catalog database. The last form deletes JobId records for JobIds
+ n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
+ number. That is a "delete jobid" accepts lists and ranges of
+ jobids.
+
+\item [disable job\lt{}job-name\gt{}]
+ \index[general]{disable}
+ This command permits you to disable a Job for automatic scheduling.
+ The job may have been previously enabled with the Job resource
+ {\bf Enabled} directive or using the console {\bf enable} command.
+ The next time the Director is restarted or the conf file is reloaded,
+ the Enable/Disable state will be set to the value in the Job resource
+ (default enabled) as defined in the bacula-dir.conf file.
+
+\item [enable job\lt{}job-name\gt{}]
+ \index[general]{enable}
+ This command permits you to enable a Job for automatic scheduling.
+ The job may have been previously disabled with the Job resource
+ {\bf Enabled} directive or using the console {\bf disable} command.
+ The next time the Director is restarted or the conf file is reloaded,
+ the Enable/Disable state will be set to the value in the Job resource
+ (default enabled) as defined in the bacula-dir.conf file.
+
+\label{estimate}
+\item [estimate]
+ \index[general]{estimate}
+ Using this command, you can get an idea how many files will be backed
+ up, or if you are unsure about your Include statements in your FileSet,
+ you can test them without doing an actual backup. The default is to
+ assume a Full backup. However, you can override this by specifying a
+ {\bf level=Incremental} or {\bf level=Differential} on the command line.
+ A Job name must be specified or you will be prompted for one, and
+ optionally a Client and FileSet may be specified on the command line.
+ It then contacts the client which computes the number of files and bytes
+ that would be backed up. Please note that this is an estimate
+ calculated from the number of blocks in the file rather than by reading
+ the actual bytes. As such, the estimated backup size will generally be
+ larger than an actual backup.
+
+ The \texttt{estimate} command can use the accurate code to detect changes
+ and give a better estimation. You can set the accurate behavior on command
+ line using \texttt{accurate=yes/no} or use the Job setting as default value.
+
+ Optionally you may specify the keyword {\bf listing} in which case, all the
+ files to be backed up will be listed. Note, it could take quite some time to
+ display them if the backup is large. The full form is:
+
+\begin{verbatim}
+estimate job=<job-name> listing client=<client-name> accurate=<yes/no>
+ fileset=<fileset-name> level=<level-name>
+\end{verbatim}
+
+ Specification of the {\bf job} is sufficient, but you can also override the
+ client, fileset, accurate and/or level by specifying them on the estimate
+ command line.
+
+
+As an example, you might do:
+
+\footnotesize
+\begin{verbatim}
+ @output /tmp/listing
+ estimate job=NightlySave listing level=Incremental
+ @output
+\end{verbatim}
+\normalsize
+
+ which will do a full listing of all files to be backed up for the Job {\bf
+ NightlySave} during an Incremental save and put it in the file {\bf
+ /tmp/listing}. Note, the byte estimate provided by this command is
+ based on the file size contained in the directory item. This can give
+ wildly incorrect estimates of the actual storage used if there are
+ sparse files on your systems. Sparse files are often found on 64 bit
+ systems for certain system files. The size that is returned is the size
+ Bacula will backup if the sparse option is not specified in the FileSet.
+ There is currently no way to get an estimate of the real file size that
+ would be found should the sparse option be enabled.
+
+\item [exit]
+ \index[general]{exit}
+ This command terminates the console program.
+
+\item [gui]
+ \index[general]{gui}
+ Invoke the non-interactive gui mode.
+\begin{verbatim}
+gui [on|off]
+\end{verbatim}
+
+\item [help]
+ \index[general]{help}
+ This command displays the list of commands available.
+
+\item [label]
+ \index[general]{label}
+ \index[general]{relabel}
+ \index[general]{label}
+ \index[general]{relabel}
+ This command is used to label physical volumes. The full form of this command
+ is:
+
+\begin{verbatim}
+label storage=<storage-name> volume=<volume-name>
+ slot=<slot>
+\end{verbatim}
+
+ If you leave out any part, you will be prompted for it. The media type
+ is automatically taken from the Storage resource definition that you
+ supply. Once the necessary information is obtained, the Console program
+ contacts the specified Storage daemon and requests that the Volume be
+ labeled. If the Volume labeling is successful, the Console program will
+ create a Volume record in the appropriate Pool.
+
+ The Volume name is restricted to letters, numbers, and the special
+ characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
+ period ({\bf .}). All other characters including a space are invalid.
+ This restriction is to ensure good readability of Volume names to reduce
+ operator errors.
+
+ Please note, when labeling a blank tape, Bacula will get {\bf read I/O
+ error} when it attempts to ensure that the tape is not already labeled. If
+ you wish to avoid getting these messages, please write an EOF mark on
+ your tape before attempting to label it:
+
+\footnotesize
+\begin{verbatim}
+ mt rewind
+ mt weof
+
+\end{verbatim}
+\normalsize
+
+The label command can fail for a number of reasons:
+
+\begin{enumerate}
+\item The Volume name you specify is already in the Volume database.
+
+\item The Storage daemon has a tape or other Volume already mounted on the
+ device, in which case you must {\bf unmount} the device, insert a blank
+ tape, then do the {\bf label} command.
+
+\item The Volume in the device is already a Bacula labeled Volume. (Bacula will
+ never relabel a Bacula labeled Volume unless it is recycled and you use the
+ {\bf relabel} command).
+
+\item There is no Volume in the drive.
+\end{enumerate}
+
+There are two ways to relabel a volume that already has a Bacula label. The
+brute force method is to write an end of file mark on the tape using the
+system {\bf mt} program, something like the following:
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/st0 rewind
+ mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+For a disk volume, you would manually delete the Volume.
+
+Then you use the {\bf label} command to add a new label. However, this could
+leave traces of the old volume in the catalog.
+
+The preferable method to relabel a Volume is to first {\bf purge} the volume,
+either automatically, or explicitly with the {\bf purge} command, then use
+the {\bf relabel} command described below.
+
+If your autochanger has barcode labels, you can label all the Volumes in
+your autochanger one after another by using the {\bf label barcodes}
+command. For each tape in the changer containing a barcode, Bacula will
+mount the tape and then label it with the same name as the barcode. An
+appropriate Media record will also be created in the catalog. Any barcode
+that begins with the same characters as specified on the
+"CleaningPrefix=xxx" directive in the Director's Pool resource, will be
+treated as a cleaning tape, and will not be labeled. However, an entry for
+the cleaning tape will be created in the catalog. For example with:
+
+\footnotesize
+\begin{verbatim}
+ Pool {
+ Name ...
+ Cleaning Prefix = "CLN"
+ }
+
+\end{verbatim}
+\normalsize
+
+Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
+and will not be mounted. Note, the full form of the command is:
+
+\footnotesize
+\begin{verbatim}
+label storage=xxx pool=yyy slots=1-5,10 barcodes
+\end{verbatim}
+\normalsize
+
+\item [list]
+ \index[general]{list}
+ The list command lists the requested contents of the Catalog. The
+ various fields of each record are listed on a single line. The various
+ forms of the list command are:
+\footnotesize
+\begin{verbatim}
+ list jobs
+
+ list jobid=<id> (list jobid id)
+
+ list ujobid=<unique job name> (list job with unique name)
+
+ list job=<job-name> (list all jobs with "job-name")
+
+ list jobname=<job-name> (same as above)
+
+ In the above, you can add "limit=nn" to limit the output to
+ nn jobs.
+
+ list jobmedia
+
+ list jobmedia jobid=<id>
+
+ list jobmedia job=<job-name>
+
+ list files jobid=<id>
+
+ list files job=<job-name>
+
+ list pools
+
+ list clients
+
+ list jobtotals
+
+ list volumes
+
+ list volumes jobid=<id>
+
+ list volumes pool=<pool-name>
+
+ list volumes job=<job-name>
+
+ list volume=<volume-name>
+
+ list nextvolume job=<job-name>
+
+ list nextvol job=<job-name>
+
+ list nextvol job=<job-name> days=nnn
+
+\end{verbatim}
+\normalsize
+
+ What most of the above commands do should be more or less obvious. In
+ general if you do not specify all the command line arguments, the
+ command will prompt you for what is needed.
+
+ The {\bf list nextvol} command will print the Volume name to be used by
+ the specified job. You should be aware that exactly what Volume will be
+ used depends on a lot of factors including the time and what a prior job
+ will do. It may fill a tape that is not full when you issue this
+ command. As a consequence, this command will give you a good estimate
+ of what Volume will be used but not a definitive answer. In addition,
+ this command may have certain side effect because it runs through the
+ same algorithm as a job, which means it may automatically purge or
+ recycle a Volume. By default, the job specified must run within the
+ next two days or no volume will be found. You can, however, use the
+ {\bf days=nnn} specification to specify up to 50 days. For example,
+ if on Friday, you want to see what Volume will be needed on Monday,
+ for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
+
+ If you wish to add specialized commands that list the contents of the
+ catalog, you can do so by adding them to the {\bf query.sql} file.
+ However, this takes some knowledge of programming SQL. Please see the
+ {\bf query} command below for additional information. See below for
+ listing the full contents of a catalog record with the {\bf llist}
+ command.
+
+ As an example, the command {\bf list pools} might produce the following
+ output:
+
+\footnotesize
+\begin{verbatim}
++------+---------+---------+---------+----------+-------------+
+| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
++------+---------+---------+---------+----------+-------------+
+| 1 | Default | 0 | 0 | Backup | * |
+| 2 | Recycle | 0 | 8 | Backup | File |
++------+---------+---------+---------+----------+-------------+
+\end{verbatim}
+\normalsize
+
+ As mentioned above, the {\bf list} command lists what is in the
+ database. Some things are put into the database immediately when Bacula
+ starts up, but in general, most things are put in only when they are
+ first used, which is the case for a Client as with Job records, etc.
+
+ Bacula should create a client record in the database the first time you
+ run a job for that client. Doing a {\bf status} will not cause a
+ database record to be created. The client database record will be
+ created whether or not the job fails, but it must at least start. When
+ the Client is actually contacted, additional info from the client will
+ be added to the client record (a "uname -a" output).
+
+ If you want to see what Client resources you have available in your conf
+ file, you use the Console command {\bf show clients}.
+
+\item [llist]
+ \index[general]{llist}
+ The llist or "long list" command takes all the same arguments that the
+ list command described above does. The difference is that the llist
+ command list the full contents of each database record selected. It
+ does so by listing the various fields of the record vertically, with one
+ field per line. It is possible to produce a very large number of output
+ lines with this command.
+
+ If instead of the {\bf list pools} as in the example above, you enter
+ {\bf llist pools} you might get the following output:
+
+\footnotesize
+\begin{verbatim}
+ PoolId: 1
+ Name: Default
+ NumVols: 0
+ MaxVols: 0
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 1,296,000
+ VolUseDuration: 86,400
+ MaxVolJobs: 0
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: *
+
+ PoolId: 2
+ Name: Recycle
+ NumVols: 0
+ MaxVols: 8
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 3,600
+ VolUseDuration: 3,600
+ MaxVolJobs: 1
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: File
+
+\end{verbatim}
+\normalsize
+
+\item [messages]
+ \index[general]{messages}
+ This command causes any pending console messages to be immediately displayed.
+
+\item [memory]
+ \index[general]{memory}
+ Print current memory usage.
+
+
+\item [mount]
+ \index[general]{mount}
+ The mount command is used to get Bacula to read a volume on a physical
+ device. It is a way to tell Bacula that you have mounted a tape and
+ that Bacula should examine the tape. This command is normally
+ used only after there was no Volume in a drive and Bacula requests you to mount a new
+ Volume or when you have specifically unmounted a Volume with the {\bf
+ unmount} console command, which causes Bacula to close the drive. If
+ you have an autoloader, the mount command will not cause Bacula to
+ operate the autoloader unless you specify a {\bf slot} and possibly a
+ {\bf drive}. The various forms of the mount command are:
+
+mount storage=\lt{}storage-name\gt{} [ slot=\lt{}num\gt{} ] [
+ drive=\lt{}num\gt{} ]
+
+mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
+
+ If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
+ Device resource, under most circumstances, Bacula will automatically access
+ the Volume unless you have explicitly {\bf unmount}ed it in the Console
+ program.
+
+\label{ManualPruning}
+\item [prune]
+ \index[general]{prune}
+ The Prune command allows you to safely remove expired database records from
+ Jobs, Volumes and Statistics. This command works only on the Catalog
+ database and does not affect data written to Volumes. In all cases, the
+ Prune command applies a retention period to the specified records. You can
+ Prune expired File entries from Job records; you can Prune expired Job
+ records from the database, and you can Prune both expired Job and File
+ records from specified Volumes.
+
+prune files|jobs|volume|stats client=\lt{}client-name\gt{}
+volume=\lt{}volume-name\gt{}
+
+ For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
+ Append, otherwise the pruning will not take place.
+
+\item [purge]
+ \index[general]{purge}
+ The Purge command will delete associated Catalog database records from
+ Jobs and Volumes without considering the retention period. {\bf Purge}
+ works only on the Catalog database and does not affect data written to
+ Volumes. This command can be dangerous because you can delete catalog
+ records associated with current backups of files, and we recommend that
+ you do not use it unless you know what you are doing. The permitted
+ forms of {\bf purge} are:
+
+purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
+
+purge jobs client=\lt{}client-name\gt{} (of all jobs)
+
+purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
+
+For the {\bf purge} command to work on Volume Catalog database records the
+{\bf VolStatus} must be Append, Full, Used, or Error.
+
+The actual data written to the Volume will be unaffected by this command.
+
+\item[python]
+ \index[general]{python}
+ The python command takes a single argument {\bf restart}:
+
+python restart
+
+ This causes the Python interpreter in the Director to be reinitialized.
+ This can be helpful for testing because once the Director starts and the
+ Python interpreter is initialized, there is no other way to make it
+ accept any changes to the startup script {\bf DirStartUp.py}. For more
+ details on Python scripting, please see the \ilink{Python
+ Scripting}{PythonChapter} chapter of this manual.
+
+\item [query]
+ \index[general]{query}
+ This command reads a predefined SQL query from the query file (the name and
+ location of the query file is defined with the QueryFile resource record in
+ the Director's configuration file). You are prompted to select a query from
+ the file, and possibly enter one or more parameters, then the command is
+ submitted to the Catalog database SQL engine.
+
+The following queries are currently available (version 2.2.7):
+
+\footnotesize
+\begin{verbatim}
+Available queries:
+1: List up to 20 places where a File is saved regardless of the directory
+2: List where the most recent copies of a file are saved
+3: List last 20 Full Backups for a Client
+4: List all backups for a Client after a specified time
+5: List all backups for a Client
+6: List Volume Attributes for a selected Volume
+7: List Volumes used by selected JobId
+8: List Volumes to Restore All Files
+9: List Pool Attributes for a selected Pool
+10: List total files/bytes by Job
+11: List total files/bytes by Volume
+12: List Files for a selected JobId
+13: List Jobs stored on a selected MediaId
+14: List Jobs stored for a given Volume name
+15: List Volumes Bacula thinks are in changer
+16: List Volumes likely to need replacement from age or errors
+Choose a query (1-16):
+\end{verbatim}
+\normalsize
+
+\item [quit]
+ \index[general]{quit}
+ This command terminates the console program. The console program sends the
+ {\bf quit} request to the Director and waits for acknowledgment. If the
+ Director is busy doing a previous command for you that has not terminated, it
+ may take some time. You may quit immediately by issuing the {\bf .quit}
+ command (i.e. quit preceded by a period).
+
+\item [relabel]
+ \index[general]{relabel}
+ \index[general]{relabel}
+ This command is used to label physical volumes. The full form of this
+ command is:
+
+relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
+ volume=\lt{}newvolume-name\gt{}
+
+ If you leave out any part, you will be prompted for it. In order for
+ the Volume (old-volume-name) to be relabeled, it must be in the catalog,
+ and the volume status must be marked {\bf Purged} or {\bf Recycle}.
+ This happens automatically as a result of applying retention periods, or
+ you may explicitly purge the volume using the {\bf purge} command.
+
+ Once the volume is physically relabeled, the old data previously written
+ on the Volume is lost and cannot be recovered.
+
+\item [release]
+ \index[general]{release}
+ This command is used to cause the Storage daemon to rewind (release) the
+ current tape in the drive, and to re-read the Volume label the next time
+ the tape is used.
+
+release storage=\lt{}storage-name\gt{}
+
+ After a release command, the device is still kept open by Bacula (unless
+ Always Open is set to No in the Storage Daemon's configuration) so it
+ cannot be used by another program. However, with some tape drives, the
+ operator can remove the current tape and to insert a different one, and
+ when the next Job starts, Bacula will know to re-read the tape label to
+ find out what tape is mounted. If you want to be able to use the drive
+ with another program (e.g. {\bf mt}), you must use the {\bf unmount}
+ command to cause Bacula to completely release (close) the device.
+
+\item [reload]
+ \index[general]{reload}
+ The reload command causes the Director to re-read its configuration
+ file and apply the new values. The new values will take effect
+ immediately for all new jobs. However, if you change schedules,
+ be aware that the scheduler pre-schedules jobs up to two hours in
+ advance, so any changes that are to take place during the next two
+ hours may be delayed. Jobs that have already been scheduled to run
+ (i.e. surpassed their requested start time) will continue with the
+ old values. New jobs will use the new values. Each time you issue
+ a reload command while jobs are running, the prior config values
+ will queued until all jobs that were running before issuing
+ the reload terminate, at which time the old config values will
+ be released from memory. The Directory permits keeping up to
+ ten prior set of configurations before it will refuse a reload
+ command. Once at least one old set of config values has been
+ released it will again accept new reload commands.
+
+ While it is possible to reload the Director's configuration on the fly,
+ even while jobs are executing, this is a complex operation and not
+ without side effects. Accordingly, if you have to reload the Director's
+ configuration while Bacula is running, it is advisable to restart the
+ Director at the next convenient opportunity.
+
+\label{restore_command}
+\item [restore]
+ \index[general]{restore}
+ The restore command allows you to select one or more Jobs (JobIds) to be
+ restored using various methods. Once the JobIds are selected, the File
+ records for those Jobs are placed in an internal Bacula directory tree,
+ and the restore enters a file selection mode that allows you to
+ interactively walk up and down the file tree selecting individual files
+ to be restored. This mode is somewhat similar to the standard Unix {\bf
+ restore} program's interactive file selection mode.
+
+restore storage=\lt{}storage-name\gt{} client=\lt{}backup-client-name\gt{}
+ where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
+ restoreclient=\lt{}restore-client-name\gt{}
+ select current all done
+
+ Where {\bf current}, if specified, tells the restore command to
+ automatically select a restore to the most current backup. If not
+ specified, you will be prompted. The {\bf all} specification tells the
+ restore command to restore all files. If it is not specified, you will
+ be prompted for the files to restore. For details of the {\bf restore}
+ command, please see the \ilink{Restore Chapter}{RestoreChapter} of this
+ manual.
+
+ The client keyword initially specifies the client from which the backup
+ was made and the client to which the restore will be make. However,
+ if the restoreclient keyword is specified, then the restore is written
+ to that client.
+
+\item [run]
+ \index[general]{run}
+ This command allows you to schedule jobs to be run immediately. The full form
+ of the command is:
+
+run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
+ fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
+ storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
+ when=\lt{}universal-time-specification\gt{} spooldata=yes|no yes
+
+ Any information that is needed but not specified will be listed for
+ selection, and before starting the job, you will be prompted to accept,
+ reject, or modify the parameters of the job to be run, unless you have
+ specified {\bf yes}, in which case the job will be immediately sent to
+ the scheduler.
+
+ On my system, when I enter a run command, I get the following prompt:
+
+\footnotesize
+\begin{verbatim}
+A job name must be specified.
+The defined Job resources are:
+ 1: Matou
+ 2: Polymatou
+ 3: Rufus
+ 4: Minimatou
+ 5: Minou
+ 6: PmatouVerify
+ 7: MatouVerify
+ 8: RufusVerify
+ 9: Watchdog
+Select Job resource (1-9):
+
+\end{verbatim}
+\normalsize
+
+If I then select number 5, I am prompted with:
+
+\footnotesize
+\begin{verbatim}
+Run Backup job
+JobName: Minou
+FileSet: Minou Full Set
+Level: Incremental
+Client: Minou
+Storage: DLTDrive
+Pool: Default
+When: 2003-04-23 17:08:18
+OK to run? (yes/mod/no):
+
+\end{verbatim}
+\normalsize
+
+If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
+be presented with the following prompt.
+
+\footnotesize
+\begin{verbatim}
+Parameters to modify:
+ 1: Level
+ 2: Storage
+ 3: Job
+ 4: FileSet
+ 5: Client
+ 6: When
+ 7: Pool
+Select parameter to modify (1-7):
+
+\end{verbatim}
+\normalsize
+
+If you wish to start a job at a later time, you can do so by setting the When
+time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
+desired start time in YYYY-MM-DD HH:MM:SS format.
+
+The spooldata argument of the run command cannot be modified through the menu
+and is only accessible by setting its value on the intial command line. If
+no spooldata flag is set, the job, storage or schedule flag is used.
+
+\item [setdebug]
+ \index[general]{setdebug}
+ \index[general]{setdebug}
+ \index[general]{debugging}
+ \index[general]{debugging Win32}
+ \index[general]{Windows!debugging}
+ This command is used to set the debug level in each daemon. The form of this
+ command is:
+
+setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
+ storage=\lt{}storage-name\gt{} | all]
+
+ If trace=1 is set, then tracing will be enabled, and the daemon will be
+ placed in trace mode, which means that all debug output as set by the
+ debug level will be directed to the file {\bf bacula.trace} in the
+ current directory of the daemon. Normally, tracing is needed only for
+ Win32 clients where the debug output cannot be written to a terminal or
+ redirected to a file. When tracing, each debug output message is
+ appended to the trace file. You must explicitly delete the file when
+ you are done.
+
+\item [setip]
+ \index[general]{setip}
+ Sets new client address -- if authorized.
+
+
+\item [show]
+ \index[general]{show}
+ \index[general]{show}
+ The show command will list the Director's resource records as defined in
+ the Director's configuration file (normally {\bf bacula-dir.conf}).
+ This command is used mainly for debugging purposes by developers.
+ The following keywords are accepted on the
+ show command line: catalogs, clients, counters, devices, directors,
+ filesets, jobs, messages, pools, schedules, storages, all, help.
+ Please don't confuse this command
+ with the {\bf list}, which displays the contents of the catalog.
+
+\item [sqlquery]
+ \index[general]{sqlquery}
+ The sqlquery command puts the Console program into SQL query mode where
+ each line you enter is concatenated to the previous line until a
+ semicolon (;) is seen. The semicolon terminates the command, which is
+ then passed directly to the SQL database engine. When the output from
+ the SQL engine is displayed, the formation of a new SQL command begins.
+ To terminate SQL query mode and return to the Console command prompt,
+ you enter a period (.) in column 1.
+
+ Using this command, you can query the SQL catalog database directly.
+ Note you should really know what you are doing otherwise you could
+ damage the catalog database. See the {\bf query} command below for
+ simpler and safer way of entering SQL queries.
+
+ Depending on what database engine you are using (MySQL, PostgreSQL or
+ SQLite), you will have somewhat different SQL commands available. For
+ more detailed information, please refer to the MySQL, PostgreSQL or
+ SQLite documentation.
+
+\item [status]
+ \index[general]{status}
+
+ This command will display the status of all components. For the director, it
+ will display the next jobs that are scheduled during the next 24 hours as
+ well as the status of currently running jobs. For the Storage Daemon, you
+ will have drive status or autochanger content. The File Daemon will give you
+ information about current jobs like average speed or file accounting. The
+ full form of this command is:
+
+status [all | dir=\lt{}dir-name\gt{} | director [days=nnn] |
+ client=\lt{}client-name\gt{} | [slots] storage=\lt{}storage-name\gt{}]
+
+ If you do a {\bf status dir}, the console will list any currently
+ running jobs, a summary of all jobs scheduled to be run in the next 24
+ hours, and a listing of the last ten terminated jobs with their statuses.
+ The scheduled jobs summary will include the Volume name to be used. You
+ should be aware of two things: 1. to obtain the volume name, the code
+ goes through the same code that will be used when the job runs, but it
+ does not do pruning nor recycling of Volumes; 2. The Volume listed is
+ at best a guess. The Volume actually used may be different because of
+ the time difference (more durations may expire when the job runs) and
+ another job could completely fill the Volume requiring a new one.
+
+ In the Running Jobs listing, you may find the following types of
+ information:
+
+
+\footnotesize
+\begin{verbatim}
+2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
+5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
+ priority jobs to finish
+5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
+5343 Full Rufus.2004-03-13_01.05.04 is running
+\end{verbatim}
+\normalsize
+
+ Looking at the above listing from bottom to top, obviously JobId 5343
+ (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
+ finish because it is using the Storage resource, hence the "waiting on
+ max Storage jobs". JobId 5349 has a lower priority than all the other
+ jobs so it is waiting for higher priority jobs to finish, and finally,
+ JobId 2507 (MatouVerify) is waiting because only one job can run at a
+ time, hence it is simply "waiting execution"
+
+ If you do a {\bf status dir}, it will by default list the first
+ occurrence of all jobs that are scheduled today and tomorrow. If you
+ wish to see the jobs that are scheduled in the next three days (e.g. on
+ Friday you want to see the first occurrence of what tapes are scheduled
+ to be used on Friday, the weekend, and Monday), you can add the {\bf
+ days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs
+ scheduled today only. If you have multiple run statements, the first
+ occurrence of each run statement for the job will be displayed for the
+ period specified.
+
+ If your job seems to be blocked, you can get a general idea of the
+ problem by doing a {\bf status dir}, but you can most often get a
+ much more specific indication of the problem by doing a
+ {\bf status storage=xxx}. For example, on an idle test system, when
+ I do {\bf status storage=File}, I get:
+\footnotesize
+\begin{verbatim}
+status storage=File
+Connecting to Storage daemon File at 192.168.68.112:8103
+
+rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
+Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
+
+Running Jobs:
+No Jobs running.
+====
+
+Jobs waiting to reserve a drive:
+====
+
+Terminated Jobs:
+ JobId Level Files Bytes Status Finished Name
+======================================================================
+ 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
+====
+
+Device status:
+Autochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
+Pool="*unknown*"
+ Slot 2 is loaded in drive 0.
+ Total Bytes Read=0 Blocks Read=0 Bytes/block=0
+ Positioned at File=0 Block=0
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+====
+
+In Use Volume status:
+====
+\end{verbatim}
+\normalsize
+
+Now, what this tells me is that no jobs are running and that none of
+the devices are in use. Now, if I {\bf unmount} the autochanger, which
+will not be used in this example, and then start a Job that uses the
+File device, the job will block. When I re-issue the status storage
+command, I get for the Device status:
+
+\footnotesize
+\begin{verbatim}
+status storage=File
+...
+Device status:
+Autochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is not open.
+ Device is BLOCKED. User unmounted.
+ Drive 0 is not loaded.
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+ Device is BLOCKED waiting for media.
+====
+...
+\end{verbatim}
+\normalsize
+
+Now, here it should be clear that if a job were running that wanted
+to use the Autochanger (with two devices), it would block because
+the user unmounted the device. The real problem for the Job I started
+using the "File" device is that the device is blocked waiting for
+media -- that is Bacula needs you to label a Volume.
+
+\item [time]
+ \index[general]{time}
+ Prints the current time.
+
+\item [trace]
+ \index[general]{trace}
+ Turn on/off trace to file.
+
+\item [umount]
+ \index[general]{umount}
+ For old-time Unix guys. See the unmount command for full details.
+
+\item [unmount]
+ \index[general]{unmount}
+ This command causes the indicated Bacula Storage daemon to unmount the
+ specified device. The forms of the command are the same as the mount command:
+\footnotesize
+\begin{verbatim}
+unmount storage=<storage-name> [ drive=<num> ]
+
+unmount [ jobid=<id> | job=<job-name> ]
+\end{verbatim}
+\normalsize
+
+ Once you unmount a storage device, Bacula will no longer be able to use
+ it until you issue a mount command for that device. If Bacula needs to
+ access that device, it will block and issue mount requests periodically
+ to the operator.
+
+ If the device you are unmounting is an autochanger, it will unload
+ the drive you have specified on the command line. If no drive is
+ specified, it will assume drive 1.
+
+\label{UpdateCommand}
+\item [update]
+ \index[general]{update}
+ This command will update the catalog for either a specific Pool record, a Volume
+ record, or the Slots in an autochanger with barcode capability. In the case
+ of updating a Pool record, the new information will be automatically taken
+ from the corresponding Director's configuration resource record. It can be
+ used to increase the maximum number of volumes permitted or to set a maximum
+ number of volumes. The following main keywords may be specified:
+\footnotesize
+\begin{verbatim}
+ media, volume, pool, slots, stats
+\end{verbatim}
+\normalsize
+
+In the case of updating a Volume, you will be prompted for which value you
+wish to change. The following Volume parameters may be changed:
+
+\footnotesize
+\begin{verbatim}
+
+ Volume Status
+ Volume Retention Period
+ Volume Use Duration
+ Maximum Volume Jobs
+ Maximum Volume Files
+ Maximum Volume Bytes
+ Recycle Flag
+ Recycle Pool
+ Slot
+ InChanger Flag
+ Pool
+ Volume Files
+ Volume from Pool
+ All Volumes from Pool
+ All Volumes from all Pools
+
+\end{verbatim}
+\normalsize
+
+ For slots {\bf update slots}, Bacula will obtain a list of slots and
+ their barcodes from the Storage daemon, and for each barcode found, it
+ will automatically update the slot in the catalog Media record to
+ correspond to the new value. This is very useful if you have moved
+ cassettes in the magazine, or if you have removed the magazine and
+ inserted a different one. As the slot of each Volume is updated, the
+ InChanger flag for that Volume will also be set, and any other Volumes
+ in the Pool that were last mounted on the same Storage device
+ will have their InChanger flag turned off. This permits
+ Bacula to know what magazine (tape holder) is currently in the
+ autochanger.
+
+ If you do not have barcodes, you can accomplish the same thing in
+ version 1.33 and later by using the {\bf update slots scan} command.
+ The {\bf scan} keyword tells Bacula to physically mount each tape and to
+ read its VolumeName.
+
+ For Pool {\bf update pool}, Bacula will move the Volume record from its
+ existing pool to the pool specified.
+
+ For {\bf Volume from Pool}, {\bf All Volumes from Pool} and {\bf All Volumes
+ from all Pools}, the following values are updated from the Pool record:
+ Recycle, RecyclePool, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles,
+ and MaxVolBytes. (RecyclePool feature is available with bacula 2.1.4 or
+ higher.)
+
+ The full form of the update command with all command line arguments is:
+
+\footnotesize
+\begin{verbatim}
+ update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
+ VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
+ slot=nnn enabled=n recyclepool=zzz
+
+\end{verbatim}
+\normalsize
+
+\item [use]
+ \index[general]{use}
+ This command allows you to specify which Catalog database to use. Normally,
+you will be using only one database so this will be done automatically. In
+the case that you are using more than one database, you can use this command
+to switch from one to another.
+
+use \lt{}database-name\gt{}
+
+\item [var]
+ \label{var}
+ \index[general]{var name}
+ This command takes a string or quoted string and does variable expansion on
+ it the same way variable expansion is done on the {\bf LabelFormat} string.
+ Thus, for the most part, you can test your LabelFormat strings. The
+ difference between the {\bf var} command and the actual LabelFormat process
+ is that during the var command, no job is running so "dummy" values are
+ used in place of Job specific variables. Generally, however, you will get a
+ good idea of what is going to happen in the real case.
+
+\item [version]
+ \index[general]{version}
+ The command prints the Director's version.
+
+\item [wait]
+ \index[general]{wait}
+ The wait command causes the Director to pause until there are no jobs
+ running. This command is useful in a batch situation such as regression
+ testing where you wish to start a job and wait until that job completes
+ before continuing. This command now has the following options:
+\footnotesize
+\begin{verbatim}
+ wait [jobid=nn] [jobuid=unique id] [job=job name]
+\end{verbatim}
+\normalsize
+ If specified with a specific JobId, ... the wait command will wait
+ for that particular job to terminate before continuing.
+
+\end{description}
+
+\label{dotcommands}
+\section{Special dot Commands}
+\index[general]{Commands!Special dot}
+\index[general]{Special dot Commands}
+
+There is a list of commands that are prefixed with a period (.). These
+commands are intended to be used either by batch programs or graphical user
+interface front-ends. They are not normally used by interactive users. Once
+GUI development begins, this list will be considerably expanded. The following
+is the list of dot commands:
+
+\footnotesize
+\begin{verbatim}
+.backups job=xxx list backups for specified job
+.clients list all client names
+.defaults client=xxx fileset=yyy list defaults for specified client
+.die cause the Director to segment fault (for debugging)
+.dir when in tree mode prints the equivalent to the dir command,
+ but with fields separated by commas rather than spaces.
+.exit quit
+.filesets list all fileset names
+.help help command output
+.jobs list all job names
+.levels list all levels
+.messages get quick messages
+.msgs return any queued messages
+.pools list all pool names
+.quit quit
+.status get status output
+.storage return storage resource names
+.types list job types
+\end{verbatim}
+\normalsize
+
+\label{atcommands}
+
+\section{Special At (@) Commands}
+\index[general]{Commands!Special At @}
+\index[general]{Special At (@) Commands}
+
+Normally, all commands entered to the Console program are immediately
+forwarded to the Director, which may be on another machine, to be executed.
+However, there is a small list of {\bf at} commands, all beginning with an at
+character (@), that will not be sent to the Director, but rather interpreted
+by the Console program directly. Note, these commands are implemented only in
+the tty console program and not in the Bat Console. These commands are:
+
+\begin{description}
+
+\item [@input \lt{}filename\gt{}]
+ \index[general]{@input \lt{}filename\gt{}}
+ Read and execute the commands contained in the file specified.
+
+\item [@output \lt{}filename\gt{} w/a]
+ \index[general]{@output \lt{}filename\gt{} w/a}
+ Send all following output to the filename specified either overwriting the
+file (w) or appending to the file (a). To redirect the output to the
+terminal, simply enter {\bf @output} without a filename specification.
+WARNING: be careful not to overwrite a valid file. A typical example during a
+regression test might be:
+
+\footnotesize
+\begin{verbatim}
+ @output /dev/null
+ commands ...
+ @output
+
+\end{verbatim}
+\normalsize
+
+\item [@tee \lt{}filename\gt{} w/a]
+ \index[general]{@tee \lt{}filename\gt{} w/a}
+ Send all subsequent output to both the specified file and the terminal. It is
+ turned off by specifying {\bf @tee} or {\bf @output} without a filename.
+
+\item [@sleep \lt{}seconds\gt{}]
+ \index[general]{@sleep \lt{}seconds\gt{}}
+ Sleep the specified number of seconds.
+
+\item [@time]
+ \index[general]{@time}
+ Print the current time and date.
+
+\item [@version]
+ \index[general]{@version}
+ Print the console's version.
+
+\item [@quit]
+ \index[general]{@quit}
+ quit
+
+\item [@exit]
+ \index[general]{@exit}
+ quit
+
+\item [@\# anything]
+ \index[general]{anything}
+ Comment
+
+\item [@help]
+ \index[general]{@help}
+ Get the list of every special @ commands.
+
+\item [@separator \lt{}char\gt{}]
+\index[general]{@separator}
+ When using bconsole with readline, you can set the command separator to one
+ of those characters to write commands who require multiple input on one line,
+ or to put multiple commands on a single line.
+\begin{verbatim}
+ !$%&'()*+,-/:;<>?[]^`{|}~
+\end{verbatim}
+
+ Note, if you use a semicolon (;) as a separator character, which is
+ common, you will not be able to use the {\bf sql} command, which
+ requires each command to be terminated by a semicolon.
+
+\end{description}
+
+\label{scripting}
+\section{Running the Console from a Shell Script}
+\index[general]{Script!Running the Console Program from a Shell}
+\index[general]{Running the Console Program from a Shell Script}
+
+You can automate many Console tasks by running the console program from a
+shell script. For example, if you have created a file containing the following
+commands:
+
+\footnotesize
+\begin{verbatim}
+ ./bconsole -c ./bconsole.conf <<END_OF_DATA
+ unmount storage=DDS-4
+ quit
+ END_OF_DATA
+\end{verbatim}
+\normalsize
+
+when that file is executed, it will unmount the current DDS-4 storage device.
+You might want to run this command during a Job by using the {\bf
+RunBeforeJob} or {\bf RunAfterJob} records.
+
+It is also possible to run the Console program from file input where the file
+contains the commands as follows:
+
+\footnotesize
+\begin{verbatim}
+./bconsole -c ./bconsole.conf <filename
+\end{verbatim}
+\normalsize
+
+where the file named {\bf filename} contains any set of console commands.
+
+As a real example, the following script is part of the Bacula regression
+tests. It labels a volume (a disk volume), runs a backup, then does a restore
+of the files saved.
+
+\footnotesize
+\begin{verbatim}
+bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
+@output /dev/null
+messages
+@output /tmp/log1.out
+label volume=TestVolume001
+run job=Client1 yes
+wait
+messages
+@#
+@# now do a restore
+@#
+@output /tmp/log2.out
+restore current all
+yes
+wait
+messages
+@output
+quit
+END_OF_DATA
+\end{verbatim}
+\normalsize
+
+The output from the backup is directed to /tmp/log1.out and the output from
+the restore is directed to /tmp/log2.out. To ensure that the backup and
+restore ran correctly, the output files are checked with:
+
+\footnotesize
+\begin{verbatim}
+grep "^Termination: *Backup OK" /tmp/log1.out
+backupstat=$?
+grep "^Termination: *Restore OK" /tmp/log2.out
+restorestat=$?
+\end{verbatim}
+\normalsize
+
+\section{Adding Volumes to a Pool}
+\index[general]{Adding Volumes to a Pool}
+\index[general]{Pool!Adding Volumes to a}
+
+If you have used the {\bf label} command to label a Volume, it will be
+automatically added to the Pool, and you will not need to add any media to the
+pool.
+
+Alternatively, you may choose to add a number of Volumes to the pool without
+labeling them. At a later time when the Volume is requested by {\bf Bacula}
+you will need to label it.
+
+Before adding a volume, you must know the following information:
+
+\begin{enumerate}
+\item The name of the Pool (normally "Default")
+\item The Media Type as specified in the Storage Resource in the Director's
+ configuration file (e.g. "DLT8000")
+\item The number and names of the Volumes you wish to create.
+\end{enumerate}
+
+For example, to add media to a Pool, you would issue the following commands to
+the console program:
+
+\footnotesize
+\begin{verbatim}
+*add
+Enter name of Pool to add Volumes to: Default
+Enter the Media Type: DLT8000
+Enter number of Media volumes to create. Max=1000: 10
+Enter base volume name: Save
+Enter the starting number: 1
+10 Volumes created in pool Default
+*
+\end{verbatim}
+\normalsize
+
+To see what you have added, enter:
+
+\footnotesize
+\begin{verbatim}
+*list media pool=Default
++-------+----------+---------+---------+-------+------------------+
+| MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
++-------+----------+---------+---------+-------+------------------+
+| 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
++-------+----------+---------+---------+-------+------------------+
+*
+\end{verbatim}
+\normalsize
+
+Notice that the console program automatically appended a number to the base
+Volume name that you specify (Save in this case). If you don't want it to
+append a number, you can simply answer 0 (zero) to the question "Enter number
+of Media volumes to create. Max=1000:", and in this case, it will create a
+single Volume with the exact name you specify.
+++ /dev/null
-%%
-%%
-
-\chapter{Bacula Console}
-\label{_ConsoleChapter}
-\index[general]{Console!Bacula}
-\index[general]{Bacula Console}
-\index[general]{Console!Bacula}
-\index[general]{Bacula Console}
-
-The {\bf Bacula Console} (sometimes called the User Agent) is a program that
-allows the user or the System Administrator, to interact with the Bacula
-Director daemon while the daemon is running.
-
-The current Bacula Console comes in two versions: a shell interface (TTY
-style), and a QT GUI interface (Bat). Both permit the administrator or
-authorized users to interact with Bacula. You can determine the status of a
-particular job, examine the contents of the Catalog as well as perform certain
-tape manipulations with the Console program.
-
-In addition, there is a bwx-console built with wxWidgets that allows a graphic
-restore of files. As of version 1.34.1 it is in an early stage of development,
-but it already is quite useful. Unfortunately, it has not been enhanced for
-some time now.
-
-Since the Console program interacts with the Director through the network, your
-Console and Director programs do not necessarily need to run on the same
-machine.
-
-In fact, a certain minimal knowledge of the Console program is needed in order
-for Bacula to be able to write on more than one tape, because when Bacula
-requests a new tape, it waits until the user, via the Console program,
-indicates that the new tape is mounted.
-
-\section{Console Configuration}
-\index[general]{Console Configuration}
-\index[general]{Configuration!Console}
-\index[general]{Console Configuration}
-\index[general]{Configuration!Console}
-
-When the Console starts, it reads a standard Bacula configuration file
-named {\bf bconsole.conf} or {\bf bat.conf} in the case of the Bat
-QT Console version from the current directory unless you specify the {\bf {-}c}
-command line option (see below). This file allows default configuration
-of the Console, and at the current time, the only Resource Record defined
-is the Director resource, which gives the Console the name and address of
-the Director. For more information on configuration of the Console
-program, please see the \ilink{Console Configuration
-File}{ConsoleConfChapter} Chapter of this document.
-
-\section{Running the Console Program}
-\index[general]{Running the Console Program}
-\index[general]{Program!Running the Console}
-\index[general]{Running the Console Program}
-\index[general]{Program!Running the Console}
-
-The console program can be run with the following options:
-\footnotesize
-\begin{verbatim}
-Usage: bconsole [-s] [-c config_file] [-d debug_level]
- -c <file> set configuration file to file
- -dnn set debug level to nn
- -n no conio
- -s no signals
- -u <nn> set command execution timeout to <nn> seconds
- -t test - read configuration and exit
- -? print this message.
-\end{verbatim}
-\normalsize
-
-
-After launching the Console program (bconsole), it will prompt you for the next
-command with an asterisk (*). Generally, for all commands, you can simply
-enter the command name and the Console program will prompt you for the
-necessary arguments. Alternatively, in most cases, you may enter the command
-followed by arguments. The general format is:
-
-\footnotesize
-\begin{verbatim}
- <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
-\end{verbatim}
-\normalsize
-
-where {\bf command} is one of the commands listed below; {\bf keyword} is one
-of the keywords listed below (usually followed by an argument); and {\bf
-argument} is the value. The command may be abbreviated to the shortest unique
-form. If two commands have the same starting letters, the one that will be
-selected is the one that appears first in the {\bf help} listing. If you want
-the second command, simply spell out the full command. None of the keywords
-following the command may be abbreviated.
-
-For example:
-
-\footnotesize
-\begin{verbatim}
-list files jobid=23
-\end{verbatim}
-\normalsize
-
-will list all files saved for JobId 23. Or:
-
-\footnotesize
-\begin{verbatim}
-show pools
-\end{verbatim}
-\normalsize
-
-will display all the Pool resource records.
-
-The maximum command line length is limited to 511 characters, so if you
-are scripting the console, you may need to take some care to limit the
-line length.
-
-\section{Stopping the Console Program}
-\index[general]{Program!Stopping the Console}
-\index[general]{Stopping the Console Program}
-\index[general]{Program!Stopping the Console}
-\index[general]{Stopping the Console Program}
-
-Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
-will terminate. However, it waits until the Director acknowledges the command.
-If the Director is already doing a lengthy command (e.g. prune), it may take
-some time. If you want to immediately terminate the Console program, enter the
-{\bf .quit} command.
-
-There is currently no way to interrupt a Console command once issued (i.e.
-Ctrl-C does not work). However, if you are at a prompt that is asking you to
-select one of several possibilities and you would like to abort the command,
-you can enter a period ({\bf .}), and in most cases, you will either be
-returned to the main command prompt or if appropriate the previous prompt (in
-the case of nested prompts). In a few places such as where it is asking for a
-Volume name, the period will be taken to be the Volume name. In that case, you
-will most likely be able to cancel at the next prompt.
-
-\label{keywords}
-\section{Alphabetic List of Console Keywords}
-\index[general]{Keywords!Alphabetic List of Console}
-\index[general]{Alphabetic List of Console Keywords}
-\index[general]{Keywords!Alphabetic List of Console}
-\index[general]{Alphabetic List of Console Keywords}
-Unless otherwise specified, each of the following keywords
-takes an argument, which is specified after the keyword following
-an equal sign. For example:
-
-\begin{verbatim}
-jobid=536
-\end{verbatim}
-
-Please note, this list is incomplete as it is currently in
-the process of being created and is not currently totally in
-alphabetic
-order ...
-
-\begin{description}
-\item [restart]
- Permitted on the python command, and causes the Python
- interpreter to be restarted. Takes no argument.
-\item [all]
- Permitted on the status and show commands to specify all components or
- resources respectively.
-\item [allfrompool]
- Permitted on the update command to specify that all Volumes in the
- pool (specified on the command line) should be updated.
-\item [allfrompools]
- Permitted on the update command to specify that all Volumes in all
- pools should be updated.
-\item [before]
- Used in the restore command.
-\item [bootstrap]
- Used in the restore command.
-\item [catalog]
- Allowed in the use command to specify the catalog name
- to be used.
-\item [catalogs]
- Used in the show command. Takes no arguments.
-\item [client | fd]
-\item [clients]
- Used in the show, list, and llist commands. Takes no arguments.
-\item [counters]
- Used in the show command. Takes no arguments.
-\item [current]
- Used in the restore command. Takes no argument.
-\item [days]
- Used to define the number of days the "list nextvol" command
- should consider when looking for jobs to be run. The days keyword
- can also be used on the "status dir" command so that it will display
- jobs scheduled for the number of days you want.
-\item [devices]
- Used in the show command. Takes no arguments.
-\item [dir | director]
-\item [directors]
- Used in the show command. Takes no arguments.
-\item [directory]
- Used in the restore command. Its argument specifies the directory
- to be restored.
-\item [enabled]
- This keyword can appear on the {\bf update volume} as well
- as the {\bf update slots} commands, and can
- allows one of the following arguments: yes, true, no, false, archived,
- 0, 1, 2. Where 0 corresponds to no or false, 1 corresponds to yes or true, and
- 2 corresponds to archived. Archived volumes will not be used, nor will
- the Media record in the catalog be pruned. Volumes that are not enabled,
- will not be used for backup or restore.
-\item [done]
- Used in the restore command. Takes no argument.
-\item [file]
- Used in the restore command.
-\item [files]
- Used in the list and llist commands. Takes no arguments.
-\item [fileset]
-\item [filesets]
- Used in the show command. Takes no arguments.
-\item [help]
- Used in the show command. Takes no arguments.
-\item [jobs]
- Used in the show, list and llist commands. Takes no arguments.
-\item [jobmedia]
- Used in the list and llist commands. Takes no arguments.
-\item [jobtotals]
- Used in the list and llist commands. Takes no arguments.
-\item [jobid]
- The JobId is the numeric jobid that is printed in the Job
- Report output. It is the index of the database record for the
- given job. While it is unique for all the existing Job records
- in the catalog database, the same JobId can be reused once a
- Job is removed from the catalog. Probably you will refer
- specific Jobs that ran using their numeric JobId.
-\item [job | jobname]
- The Job or Jobname keyword refers to the name you specified
- in the Job resource, and hence it refers to any number of
- Jobs that ran. It is typically useful if you want to list
- all jobs of a particular name.
-\item [level]
-\item [listing]
- Permitted on the estimate command. Takes no argument.
-\item [limit]
-\item [messages]
- Used in the show command. Takes no arguments.
-\item [media]
- Used in the list and llist commands. Takes no arguments.
-\item [nextvol | nextvolume]
- Used in the list and llist commands. Takes no arguments.
-\item [on]
- Takes no keyword.
-\item [off]
- Takes no keyword.
-\item [pool]
-\item [pools]
- Used in the show, list, and llist commands. Takes no arguments.
-\item [select]
- Used in the restore command. Takes no argument.
-\item [storages]
- Used in the show command. Takes no arguments.
-\item [schedules]
- Used in the show command. Takes no arguments.
-\item [sd | store | storage]
-\item [ujobid]
- The ujobid is a unique job identification that is printed
- in the Job Report output. At the current time, it consists
- of the Job name (from the Name directive for the job) appended
- with the date and time the job was run. This keyword is useful
- if you want to completely identify the Job instance run.
-\item [volume]
-\item [volumes]
- Used in the list and llist commands. Takes no arguments.
-\item [where]
- Used in the restore command.
-\item [yes]
- Used in the restore command. Takes no argument.
-\end{description}
-
-\label{list}
-\section{Alphabetic List of Console Commands}
-\index[general]{Commands!Alphabetic List of Console}
-\index[general]{Alphabetic List of Console Commands}
-\index[general]{Commands!Alphabetic List of Console}
-\index[general]{Alphabetic List of Console Commands}
-
-The following commands are currently implemented:
-
-\begin{description}
-\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
- jobid=\lt{}JobId\gt{}]} ]
- \index[general]{add}
- This command is used to add Volumes to an existing Pool. That is,
- it creates the Volume name in the catalog and inserts into the Pool
- in the catalog, but does not attempt to access the physical Volume.
- Once
- added, Bacula expects that Volume to exist and to be labeled.
- This command is not normally used since Bacula will
- automatically do the equivalent when Volumes are labeled. However,
- there may be times when you have removed a Volume from the catalog
- and want to later add it back.
-
- Normally, the {\bf label} command is used rather than this command
- because the {\bf label} command labels the physical media (tape, disk,
- DVD, ...) and does the equivalent of the {\bf add} command. The {\bf
- add} command affects only the Catalog and not the physical media (data
- on Volumes). The physical media must exist and be labeled before use
- (usually with the {\bf label} command). This command can, however, be
- useful if you wish to add a number of Volumes to the Pool that will be
- physically labeled at a later time. It can also be useful if you are
- importing a tape from another site. Please see the {\bf label} command
- below for the list of legal characters in a Volume name.
-
-\item [autodisplay on/off]
- \index[general]{autodisplay on/off}
- This command accepts {\bf on} or {\bf off} as an argument, and turns
- auto-display of messages on or off respectively. The default for the
- console program is {\bf off}, which means that you will be notified when
- there are console messages pending, but they will not automatically be
- displayed.
-
- When autodisplay is turned off, you must explicitly retrieve the
- messages with the {\bf messages} command. When autodisplay is turned
- on, the messages will be displayed on the console as they are received.
-
-\item [automount on/off]
- \index[general]{automount on/off}
- This command accepts {\bf on} or {\bf off} as the argument, and turns
- auto-mounting of the Volume after a {\bf label} command on or off
- respectively. The default is {\bf on}. If {\bf automount} is turned
- off, you must explicitly {\bf mount} tape Volumes after a label command to
- use it.
-
-\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
- \index[general]{cancel jobid}
- This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
- job=xxx} as an argument where nnn is replaced by the JobId and xxx is
- replaced by the job name. If you do not specify a keyword, the Console
- program will prompt you with the names of all the active jobs allowing
- you to choose one.
-
- Once a Job is marked to be canceled, it may take a bit of time
- (generally within a minute but up to two hours) before the Job actually
- terminates, depending on what operations it is doing.
- Don't be surprised that you receive a Job not found message. That just
- means that one of the three daemons had already canceled the job.
- Messages numbered in the 1000's are from the Director, 2000's are from
- the File daemon and 3000's from the Storage daemon.
-
-
-\item [{create [pool=\lt{}pool-name\gt{}]}]
- \index[general]{create pool}
- This command is not normally used as the Pool records are automatically
- created by the Director when it starts based on what it finds in
- the conf file. If needed, this command can be
- to create a Pool record in the database using the
- Pool resource record defined in the Director's configuration file. So
- in a sense, this command simply transfers the information from the Pool
- resource in the configuration file into the Catalog. Normally this
- command is done automatically for you when the Director starts providing
- the Pool is referenced within a Job resource. If you use this command
- on an existing Pool, it will automatically update the Catalog to have
- the same information as the Pool resource. After creating a Pool, you
- will most likely use the {\bf label} command to label one or more
- volumes and add their names to the Media database.
-
- When starting a Job, if Bacula determines that there is no Pool record
- in the database, but there is a Pool resource of the appropriate name,
- it will create it for you. If you want the Pool record to appear in the
- database immediately, simply use this command to force it to be created.
-
-\item [{delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
- jobid=\lt{}id\gt{}]}]
- \index[general]{delete}
- The delete command is used to delete a Volume, Pool or Job record from
- the Catalog as well as all associated catalog Volume records that were
- created. This command operates only on the Catalog database and has no
- effect on the actual data written to a Volume. This command can be
- dangerous and we strongly recommend that you do not use it unless you
- know what you are doing.
-
- If the keyword {\bf Volume} appears on the command line, the named
- Volume will be deleted from the catalog, if the keyword {\bf Pool}
- appears on the command line, a Pool will be deleted, and if the keyword
- {\bf Job} appears on the command line, a Job and all its associated
- records (File and JobMedia) will be deleted from the catalog. The full
- form of this command is:
-
-\begin{verbatim}
-delete pool=<pool-name>
-\end{verbatim}
-
- or
-
-\begin{verbatim}
-delete volume=<volume-name> pool=<pool-name> or
-\end{verbatim}
-
-\begin{verbatim}
-delete JobId=<job-id> JobId=<job-id2> ... or
-\end{verbatim}
-
-\begin{verbatim}
-delete Job JobId=n,m,o-r,t ...
-\end{verbatim}
-
- The first form deletes a Pool record from the catalog database. The
- second form deletes a Volume record from the specified pool in the
- catalog database. The third form deletes the specified Job record from
- the catalog database. The last form deletes JobId records for JobIds
- n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
- number. That is a "delete jobid" accepts lists and ranges of
- jobids.
-
-\item [disable job\lt{}job-name\gt{}]
- \index[general]{disable}
- This command permits you to disable a Job for automatic scheduling.
- The job may have been previously enabled with the Job resource
- {\bf Enabled} directive or using the console {\bf enable} command.
- The next time the Director is restarted or the conf file is reloaded,
- the Enable/Disable state will be set to the value in the Job resource
- (default enabled) as defined in the bacula-dir.conf file.
-
-\item [enable job\lt{}job-name\gt{}]
- \index[general]{enable}
- This command permits you to enable a Job for automatic scheduling.
- The job may have been previously disabled with the Job resource
- {\bf Enabled} directive or using the console {\bf disable} command.
- The next time the Director is restarted or the conf file is reloaded,
- the Enable/Disable state will be set to the value in the Job resource
- (default enabled) as defined in the bacula-dir.conf file.
-
-\label{estimate}
-\item [estimate]
- \index[general]{estimate}
- Using this command, you can get an idea how many files will be backed
- up, or if you are unsure about your Include statements in your FileSet,
- you can test them without doing an actual backup. The default is to
- assume a Full backup. However, you can override this by specifying a
- {\bf level=Incremental} or {\bf level=Differential} on the command line.
- A Job name must be specified or you will be prompted for one, and
- optionally a Client and FileSet may be specified on the command line.
- It then contacts the client which computes the number of files and bytes
- that would be backed up. Please note that this is an estimate
- calculated from the number of blocks in the file rather than by reading
- the actual bytes. As such, the estimated backup size will generally be
- larger than an actual backup.
-
- The \texttt{estimate} command can use the accurate code to detect changes
- and give a better estimation. You can set the accurate behavior on command
- line using \texttt{accurate=yes/no} or use the Job setting as default value.
-
- Optionally you may specify the keyword {\bf listing} in which case, all the
- files to be backed up will be listed. Note, it could take quite some time to
- display them if the backup is large. The full form is:
-
-\begin{verbatim}
-estimate job=<job-name> listing client=<client-name> accurate=<yes/no>
- fileset=<fileset-name> level=<level-name>
-\end{verbatim}
-
- Specification of the {\bf job} is sufficient, but you can also override the
- client, fileset, accurate and/or level by specifying them on the estimate
- command line.
-
-
-As an example, you might do:
-
-\footnotesize
-\begin{verbatim}
- @output /tmp/listing
- estimate job=NightlySave listing level=Incremental
- @output
-\end{verbatim}
-\normalsize
-
- which will do a full listing of all files to be backed up for the Job {\bf
- NightlySave} during an Incremental save and put it in the file {\bf
- /tmp/listing}. Note, the byte estimate provided by this command is
- based on the file size contained in the directory item. This can give
- wildly incorrect estimates of the actual storage used if there are
- sparse files on your systems. Sparse files are often found on 64 bit
- systems for certain system files. The size that is returned is the size
- Bacula will backup if the sparse option is not specified in the FileSet.
- There is currently no way to get an estimate of the real file size that
- would be found should the sparse option be enabled.
-
-\item [exit]
- \index[general]{exit}
- This command terminates the console program.
-
-\item [gui]
- \index[general]{gui}
- Invoke the non-interactive gui mode.
-\begin{verbatim}
-gui [on|off]
-\end{verbatim}
-
-\item [help]
- \index[general]{help}
- This command displays the list of commands available.
-
-\item [label]
- \index[general]{label}
- \index[general]{relabel}
- \index[general]{label}
- \index[general]{relabel}
- This command is used to label physical volumes. The full form of this command
- is:
-
-\begin{verbatim}
-label storage=<storage-name> volume=<volume-name>
- slot=<slot>
-\end{verbatim}
-
- If you leave out any part, you will be prompted for it. The media type
- is automatically taken from the Storage resource definition that you
- supply. Once the necessary information is obtained, the Console program
- contacts the specified Storage daemon and requests that the Volume be
- labeled. If the Volume labeling is successful, the Console program will
- create a Volume record in the appropriate Pool.
-
- The Volume name is restricted to letters, numbers, and the special
- characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
- period ({\bf .}). All other characters including a space are invalid.
- This restriction is to ensure good readability of Volume names to reduce
- operator errors.
-
- Please note, when labeling a blank tape, Bacula will get {\bf read I/O
- error} when it attempts to ensure that the tape is not already labeled. If
- you wish to avoid getting these messages, please write an EOF mark on
- your tape before attempting to label it:
-
-\footnotesize
-\begin{verbatim}
- mt rewind
- mt weof
-
-\end{verbatim}
-\normalsize
-
-The label command can fail for a number of reasons:
-
-\begin{enumerate}
-\item The Volume name you specify is already in the Volume database.
-
-\item The Storage daemon has a tape or other Volume already mounted on the
- device, in which case you must {\bf unmount} the device, insert a blank
- tape, then do the {\bf label} command.
-
-\item The Volume in the device is already a Bacula labeled Volume. (Bacula will
- never relabel a Bacula labeled Volume unless it is recycled and you use the
- {\bf relabel} command).
-
-\item There is no Volume in the drive.
-\end{enumerate}
-
-There are two ways to relabel a volume that already has a Bacula label. The
-brute force method is to write an end of file mark on the tape using the
-system {\bf mt} program, something like the following:
-
-\footnotesize
-\begin{verbatim}
- mt -f /dev/st0 rewind
- mt -f /dev/st0 weof
-\end{verbatim}
-\normalsize
-
-For a disk volume, you would manually delete the Volume.
-
-Then you use the {\bf label} command to add a new label. However, this could
-leave traces of the old volume in the catalog.
-
-The preferable method to relabel a Volume is to first {\bf purge} the volume,
-either automatically, or explicitly with the {\bf purge} command, then use
-the {\bf relabel} command described below.
-
-If your autochanger has barcode labels, you can label all the Volumes in
-your autochanger one after another by using the {\bf label barcodes}
-command. For each tape in the changer containing a barcode, Bacula will
-mount the tape and then label it with the same name as the barcode. An
-appropriate Media record will also be created in the catalog. Any barcode
-that begins with the same characters as specified on the
-"CleaningPrefix=xxx" directive in the Director's Pool resource, will be
-treated as a cleaning tape, and will not be labeled. However, an entry for
-the cleaning tape will be created in the catalog. For example with:
-
-\footnotesize
-\begin{verbatim}
- Pool {
- Name ...
- Cleaning Prefix = "CLN"
- }
-
-\end{verbatim}
-\normalsize
-
-Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
-and will not be mounted. Note, the full form of the command is:
-
-\footnotesize
-\begin{verbatim}
-label storage=xxx pool=yyy slots=1-5,10 barcodes
-\end{verbatim}
-\normalsize
-
-\item [list]
- \index[general]{list}
- The list command lists the requested contents of the Catalog. The
- various fields of each record are listed on a single line. The various
- forms of the list command are:
-\footnotesize
-\begin{verbatim}
- list jobs
-
- list jobid=<id> (list jobid id)
-
- list ujobid=<unique job name> (list job with unique name)
-
- list job=<job-name> (list all jobs with "job-name")
-
- list jobname=<job-name> (same as above)
-
- In the above, you can add "limit=nn" to limit the output to
- nn jobs.
-
- list jobmedia
-
- list jobmedia jobid=<id>
-
- list jobmedia job=<job-name>
-
- list files jobid=<id>
-
- list files job=<job-name>
-
- list pools
-
- list clients
-
- list jobtotals
-
- list volumes
-
- list volumes jobid=<id>
-
- list volumes pool=<pool-name>
-
- list volumes job=<job-name>
-
- list volume=<volume-name>
-
- list nextvolume job=<job-name>
-
- list nextvol job=<job-name>
-
- list nextvol job=<job-name> days=nnn
-
-\end{verbatim}
-\normalsize
-
- What most of the above commands do should be more or less obvious. In
- general if you do not specify all the command line arguments, the
- command will prompt you for what is needed.
-
- The {\bf list nextvol} command will print the Volume name to be used by
- the specified job. You should be aware that exactly what Volume will be
- used depends on a lot of factors including the time and what a prior job
- will do. It may fill a tape that is not full when you issue this
- command. As a consequence, this command will give you a good estimate
- of what Volume will be used but not a definitive answer. In addition,
- this command may have certain side effect because it runs through the
- same algorithm as a job, which means it may automatically purge or
- recycle a Volume. By default, the job specified must run within the
- next two days or no volume will be found. You can, however, use the
- {\bf days=nnn} specification to specify up to 50 days. For example,
- if on Friday, you want to see what Volume will be needed on Monday,
- for job MyJob, you would use {\bf list nextvol job=MyJob days=3}.
-
- If you wish to add specialized commands that list the contents of the
- catalog, you can do so by adding them to the {\bf query.sql} file.
- However, this takes some knowledge of programming SQL. Please see the
- {\bf query} command below for additional information. See below for
- listing the full contents of a catalog record with the {\bf llist}
- command.
-
- As an example, the command {\bf list pools} might produce the following
- output:
-
-\footnotesize
-\begin{verbatim}
-+------+---------+---------+---------+----------+-------------+
-| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
-+------+---------+---------+---------+----------+-------------+
-| 1 | Default | 0 | 0 | Backup | * |
-| 2 | Recycle | 0 | 8 | Backup | File |
-+------+---------+---------+---------+----------+-------------+
-\end{verbatim}
-\normalsize
-
- As mentioned above, the {\bf list} command lists what is in the
- database. Some things are put into the database immediately when Bacula
- starts up, but in general, most things are put in only when they are
- first used, which is the case for a Client as with Job records, etc.
-
- Bacula should create a client record in the database the first time you
- run a job for that client. Doing a {\bf status} will not cause a
- database record to be created. The client database record will be
- created whether or not the job fails, but it must at least start. When
- the Client is actually contacted, additional info from the client will
- be added to the client record (a "uname -a" output).
-
- If you want to see what Client resources you have available in your conf
- file, you use the Console command {\bf show clients}.
-
-\item [llist]
- \index[general]{llist}
- The llist or "long list" command takes all the same arguments that the
- list command described above does. The difference is that the llist
- command list the full contents of each database record selected. It
- does so by listing the various fields of the record vertically, with one
- field per line. It is possible to produce a very large number of output
- lines with this command.
-
- If instead of the {\bf list pools} as in the example above, you enter
- {\bf llist pools} you might get the following output:
-
-\footnotesize
-\begin{verbatim}
- PoolId: 1
- Name: Default
- NumVols: 0
- MaxVols: 0
- UseOnce: 0
- UseCatalog: 1
- AcceptAnyVolume: 1
- VolRetention: 1,296,000
- VolUseDuration: 86,400
- MaxVolJobs: 0
- MaxVolBytes: 0
- AutoPrune: 0
- Recycle: 1
- PoolType: Backup
- LabelFormat: *
-
- PoolId: 2
- Name: Recycle
- NumVols: 0
- MaxVols: 8
- UseOnce: 0
- UseCatalog: 1
- AcceptAnyVolume: 1
- VolRetention: 3,600
- VolUseDuration: 3,600
- MaxVolJobs: 1
- MaxVolBytes: 0
- AutoPrune: 0
- Recycle: 1
- PoolType: Backup
- LabelFormat: File
-
-\end{verbatim}
-\normalsize
-
-\item [messages]
- \index[general]{messages}
- This command causes any pending console messages to be immediately displayed.
-
-\item [memory]
- \index[general]{memory}
- Print current memory usage.
-
-
-\item [mount]
- \index[general]{mount}
- The mount command is used to get Bacula to read a volume on a physical
- device. It is a way to tell Bacula that you have mounted a tape and
- that Bacula should examine the tape. This command is normally
- used only after there was no Volume in a drive and Bacula requests you to mount a new
- Volume or when you have specifically unmounted a Volume with the {\bf
- unmount} console command, which causes Bacula to close the drive. If
- you have an autoloader, the mount command will not cause Bacula to
- operate the autoloader unless you specify a {\bf slot} and possibly a
- {\bf drive}. The various forms of the mount command are:
-
-mount storage=\lt{}storage-name\gt{} [ slot=\lt{}num\gt{} ] [
- drive=\lt{}num\gt{} ]
-
-mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
-
- If you have specified {\bf Automatic Mount = yes} in the Storage daemon's
- Device resource, under most circumstances, Bacula will automatically access
- the Volume unless you have explicitly {\bf unmount}ed it in the Console
- program.
-
-\label{ManualPruning}
-\item [prune]
- \index[general]{prune}
- The Prune command allows you to safely remove expired database records from
- Jobs, Volumes and Statistics. This command works only on the Catalog
- database and does not affect data written to Volumes. In all cases, the
- Prune command applies a retention period to the specified records. You can
- Prune expired File entries from Job records; you can Prune expired Job
- records from the database, and you can Prune both expired Job and File
- records from specified Volumes.
-
-prune files|jobs|volume|stats client=\lt{}client-name\gt{}
-volume=\lt{}volume-name\gt{}
-
- For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or
- Append, otherwise the pruning will not take place.
-
-\item [purge]
- \index[general]{purge}
- The Purge command will delete associated Catalog database records from
- Jobs and Volumes without considering the retention period. {\bf Purge}
- works only on the Catalog database and does not affect data written to
- Volumes. This command can be dangerous because you can delete catalog
- records associated with current backups of files, and we recommend that
- you do not use it unless you know what you are doing. The permitted
- forms of {\bf purge} are:
-
-purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
-
-purge jobs client=\lt{}client-name\gt{} (of all jobs)
-
-purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
-
-For the {\bf purge} command to work on Volume Catalog database records the
-{\bf VolStatus} must be Append, Full, Used, or Error.
-
-The actual data written to the Volume will be unaffected by this command.
-
-\item[python]
- \index[general]{python}
- The python command takes a single argument {\bf restart}:
-
-python restart
-
- This causes the Python interpreter in the Director to be reinitialized.
- This can be helpful for testing because once the Director starts and the
- Python interpreter is initialized, there is no other way to make it
- accept any changes to the startup script {\bf DirStartUp.py}. For more
- details on Python scripting, please see the \ilink{Python
- Scripting}{PythonChapter} chapter of this manual.
-
-\item [query]
- \index[general]{query}
- This command reads a predefined SQL query from the query file (the name and
- location of the query file is defined with the QueryFile resource record in
- the Director's configuration file). You are prompted to select a query from
- the file, and possibly enter one or more parameters, then the command is
- submitted to the Catalog database SQL engine.
-
-The following queries are currently available (version 2.2.7):
-
-\footnotesize
-\begin{verbatim}
-Available queries:
-1: List up to 20 places where a File is saved regardless of the directory
-2: List where the most recent copies of a file are saved
-3: List last 20 Full Backups for a Client
-4: List all backups for a Client after a specified time
-5: List all backups for a Client
-6: List Volume Attributes for a selected Volume
-7: List Volumes used by selected JobId
-8: List Volumes to Restore All Files
-9: List Pool Attributes for a selected Pool
-10: List total files/bytes by Job
-11: List total files/bytes by Volume
-12: List Files for a selected JobId
-13: List Jobs stored on a selected MediaId
-14: List Jobs stored for a given Volume name
-15: List Volumes Bacula thinks are in changer
-16: List Volumes likely to need replacement from age or errors
-Choose a query (1-16):
-\end{verbatim}
-\normalsize
-
-\item [quit]
- \index[general]{quit}
- This command terminates the console program. The console program sends the
- {\bf quit} request to the Director and waits for acknowledgment. If the
- Director is busy doing a previous command for you that has not terminated, it
- may take some time. You may quit immediately by issuing the {\bf .quit}
- command (i.e. quit preceded by a period).
-
-\item [relabel]
- \index[general]{relabel}
- \index[general]{relabel}
- This command is used to label physical volumes. The full form of this
- command is:
-
-relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
- volume=\lt{}newvolume-name\gt{}
-
- If you leave out any part, you will be prompted for it. In order for
- the Volume (old-volume-name) to be relabeled, it must be in the catalog,
- and the volume status must be marked {\bf Purged} or {\bf Recycle}.
- This happens automatically as a result of applying retention periods, or
- you may explicitly purge the volume using the {\bf purge} command.
-
- Once the volume is physically relabeled, the old data previously written
- on the Volume is lost and cannot be recovered.
-
-\item [release]
- \index[general]{release}
- This command is used to cause the Storage daemon to rewind (release) the
- current tape in the drive, and to re-read the Volume label the next time
- the tape is used.
-
-release storage=\lt{}storage-name\gt{}
-
- After a release command, the device is still kept open by Bacula (unless
- Always Open is set to No in the Storage Daemon's configuration) so it
- cannot be used by another program. However, with some tape drives, the
- operator can remove the current tape and to insert a different one, and
- when the next Job starts, Bacula will know to re-read the tape label to
- find out what tape is mounted. If you want to be able to use the drive
- with another program (e.g. {\bf mt}), you must use the {\bf unmount}
- command to cause Bacula to completely release (close) the device.
-
-\item [reload]
- \index[general]{reload}
- The reload command causes the Director to re-read its configuration
- file and apply the new values. The new values will take effect
- immediately for all new jobs. However, if you change schedules,
- be aware that the scheduler pre-schedules jobs up to two hours in
- advance, so any changes that are to take place during the next two
- hours may be delayed. Jobs that have already been scheduled to run
- (i.e. surpassed their requested start time) will continue with the
- old values. New jobs will use the new values. Each time you issue
- a reload command while jobs are running, the prior config values
- will queued until all jobs that were running before issuing
- the reload terminate, at which time the old config values will
- be released from memory. The Directory permits keeping up to
- ten prior set of configurations before it will refuse a reload
- command. Once at least one old set of config values has been
- released it will again accept new reload commands.
-
- While it is possible to reload the Director's configuration on the fly,
- even while jobs are executing, this is a complex operation and not
- without side effects. Accordingly, if you have to reload the Director's
- configuration while Bacula is running, it is advisable to restart the
- Director at the next convenient opportunity.
-
-\label{restore_command}
-\item [restore]
- \index[general]{restore}
- The restore command allows you to select one or more Jobs (JobIds) to be
- restored using various methods. Once the JobIds are selected, the File
- records for those Jobs are placed in an internal Bacula directory tree,
- and the restore enters a file selection mode that allows you to
- interactively walk up and down the file tree selecting individual files
- to be restored. This mode is somewhat similar to the standard Unix {\bf
- restore} program's interactive file selection mode.
-
-restore storage=\lt{}storage-name\gt{} client=\lt{}backup-client-name\gt{}
- where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
- restoreclient=\lt{}restore-client-name\gt{}
- select current all done
-
- Where {\bf current}, if specified, tells the restore command to
- automatically select a restore to the most current backup. If not
- specified, you will be prompted. The {\bf all} specification tells the
- restore command to restore all files. If it is not specified, you will
- be prompted for the files to restore. For details of the {\bf restore}
- command, please see the \ilink{Restore Chapter}{RestoreChapter} of this
- manual.
-
- The client keyword initially specifies the client from which the backup
- was made and the client to which the restore will be make. However,
- if the restoreclient keyword is specified, then the restore is written
- to that client.
-
-\item [run]
- \index[general]{run}
- This command allows you to schedule jobs to be run immediately. The full form
- of the command is:
-
-run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
- fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
- storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
- when=\lt{}universal-time-specification\gt{} spooldata=yes|no yes
-
- Any information that is needed but not specified will be listed for
- selection, and before starting the job, you will be prompted to accept,
- reject, or modify the parameters of the job to be run, unless you have
- specified {\bf yes}, in which case the job will be immediately sent to
- the scheduler.
-
- On my system, when I enter a run command, I get the following prompt:
-
-\footnotesize
-\begin{verbatim}
-A job name must be specified.
-The defined Job resources are:
- 1: Matou
- 2: Polymatou
- 3: Rufus
- 4: Minimatou
- 5: Minou
- 6: PmatouVerify
- 7: MatouVerify
- 8: RufusVerify
- 9: Watchdog
-Select Job resource (1-9):
-
-\end{verbatim}
-\normalsize
-
-If I then select number 5, I am prompted with:
-
-\footnotesize
-\begin{verbatim}
-Run Backup job
-JobName: Minou
-FileSet: Minou Full Set
-Level: Incremental
-Client: Minou
-Storage: DLTDrive
-Pool: Default
-When: 2003-04-23 17:08:18
-OK to run? (yes/mod/no):
-
-\end{verbatim}
-\normalsize
-
-If I now enter {\bf yes}, the Job will be run. If I enter {\bf mod}, I will
-be presented with the following prompt.
-
-\footnotesize
-\begin{verbatim}
-Parameters to modify:
- 1: Level
- 2: Storage
- 3: Job
- 4: FileSet
- 5: Client
- 6: When
- 7: Pool
-Select parameter to modify (1-7):
-
-\end{verbatim}
-\normalsize
-
-If you wish to start a job at a later time, you can do so by setting the When
-time. Use the {\bf mod} option and select {\bf When} (no. 6). Then enter the
-desired start time in YYYY-MM-DD HH:MM:SS format.
-
-The spooldata argument of the run command cannot be modified through the menu
-and is only accessible by setting its value on the intial command line. If
-no spooldata flag is set, the job, storage or schedule flag is used.
-
-\item [setdebug]
- \index[general]{setdebug}
- \index[general]{setdebug}
- \index[general]{debugging}
- \index[general]{debugging Win32}
- \index[general]{Windows!debugging}
- This command is used to set the debug level in each daemon. The form of this
- command is:
-
-setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
- storage=\lt{}storage-name\gt{} | all]
-
- If trace=1 is set, then tracing will be enabled, and the daemon will be
- placed in trace mode, which means that all debug output as set by the
- debug level will be directed to the file {\bf bacula.trace} in the
- current directory of the daemon. Normally, tracing is needed only for
- Win32 clients where the debug output cannot be written to a terminal or
- redirected to a file. When tracing, each debug output message is
- appended to the trace file. You must explicitly delete the file when
- you are done.
-
-\item [setip]
- \index[general]{setip}
- Sets new client address -- if authorized.
-
-
-\item [show]
- \index[general]{show}
- \index[general]{show}
- The show command will list the Director's resource records as defined in
- the Director's configuration file (normally {\bf bacula-dir.conf}).
- This command is used mainly for debugging purposes by developers.
- The following keywords are accepted on the
- show command line: catalogs, clients, counters, devices, directors,
- filesets, jobs, messages, pools, schedules, storages, all, help.
- Please don't confuse this command
- with the {\bf list}, which displays the contents of the catalog.
-
-\item [sqlquery]
- \index[general]{sqlquery}
- The sqlquery command puts the Console program into SQL query mode where
- each line you enter is concatenated to the previous line until a
- semicolon (;) is seen. The semicolon terminates the command, which is
- then passed directly to the SQL database engine. When the output from
- the SQL engine is displayed, the formation of a new SQL command begins.
- To terminate SQL query mode and return to the Console command prompt,
- you enter a period (.) in column 1.
-
- Using this command, you can query the SQL catalog database directly.
- Note you should really know what you are doing otherwise you could
- damage the catalog database. See the {\bf query} command below for
- simpler and safer way of entering SQL queries.
-
- Depending on what database engine you are using (MySQL, PostgreSQL or
- SQLite), you will have somewhat different SQL commands available. For
- more detailed information, please refer to the MySQL, PostgreSQL or
- SQLite documentation.
-
-\item [status]
- \index[general]{status}
-
- This command will display the status of all components. For the director, it
- will display the next jobs that are scheduled during the next 24 hours as
- well as the status of currently running jobs. For the Storage Daemon, you
- will have drive status or autochanger content. The File Daemon will give you
- information about current jobs like average speed or file accounting. The
- full form of this command is:
-
-status [all | dir=\lt{}dir-name\gt{} | director [days=nnn] |
- client=\lt{}client-name\gt{} | [slots] storage=\lt{}storage-name\gt{}]
-
- If you do a {\bf status dir}, the console will list any currently
- running jobs, a summary of all jobs scheduled to be run in the next 24
- hours, and a listing of the last ten terminated jobs with their statuses.
- The scheduled jobs summary will include the Volume name to be used. You
- should be aware of two things: 1. to obtain the volume name, the code
- goes through the same code that will be used when the job runs, but it
- does not do pruning nor recycling of Volumes; 2. The Volume listed is
- at best a guess. The Volume actually used may be different because of
- the time difference (more durations may expire when the job runs) and
- another job could completely fill the Volume requiring a new one.
-
- In the Running Jobs listing, you may find the following types of
- information:
-
-
-\footnotesize
-\begin{verbatim}
-2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
-5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
- priority jobs to finish
-5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
-5343 Full Rufus.2004-03-13_01.05.04 is running
-\end{verbatim}
-\normalsize
-
- Looking at the above listing from bottom to top, obviously JobId 5343
- (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to
- finish because it is using the Storage resource, hence the "waiting on
- max Storage jobs". JobId 5349 has a lower priority than all the other
- jobs so it is waiting for higher priority jobs to finish, and finally,
- JobId 2507 (MatouVerify) is waiting because only one job can run at a
- time, hence it is simply "waiting execution"
-
- If you do a {\bf status dir}, it will by default list the first
- occurrence of all jobs that are scheduled today and tomorrow. If you
- wish to see the jobs that are scheduled in the next three days (e.g. on
- Friday you want to see the first occurrence of what tapes are scheduled
- to be used on Friday, the weekend, and Monday), you can add the {\bf
- days=3} option. Note, a {\bf days=0} shows the first occurrence of jobs
- scheduled today only. If you have multiple run statements, the first
- occurrence of each run statement for the job will be displayed for the
- period specified.
-
- If your job seems to be blocked, you can get a general idea of the
- problem by doing a {\bf status dir}, but you can most often get a
- much more specific indication of the problem by doing a
- {\bf status storage=xxx}. For example, on an idle test system, when
- I do {\bf status storage=File}, I get:
-\footnotesize
-\begin{verbatim}
-status storage=File
-Connecting to Storage daemon File at 192.168.68.112:8103
-
-rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
-Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
-
-Running Jobs:
-No Jobs running.
-====
-
-Jobs waiting to reserve a drive:
-====
-
-Terminated Jobs:
- JobId Level Files Bytes Status Finished Name
-======================================================================
- 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
-====
-
-Device status:
-Autochanger "DDS-4-changer" with devices:
- "DDS-4" (/dev/nst0)
-Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
-Pool="*unknown*"
- Slot 2 is loaded in drive 0.
- Total Bytes Read=0 Blocks Read=0 Bytes/block=0
- Positioned at File=0 Block=0
-
-Device "DVD-Writer" (/dev/hdc) is not open.
-Device "File" (/tmp) is not open.
-====
-
-In Use Volume status:
-====
-\end{verbatim}
-\normalsize
-
-Now, what this tells me is that no jobs are running and that none of
-the devices are in use. Now, if I {\bf unmount} the autochanger, which
-will not be used in this example, and then start a Job that uses the
-File device, the job will block. When I re-issue the status storage
-command, I get for the Device status:
-
-\footnotesize
-\begin{verbatim}
-status storage=File
-...
-Device status:
-Autochanger "DDS-4-changer" with devices:
- "DDS-4" (/dev/nst0)
-Device "DDS-4" (/dev/nst0) is not open.
- Device is BLOCKED. User unmounted.
- Drive 0 is not loaded.
-
-Device "DVD-Writer" (/dev/hdc) is not open.
-Device "File" (/tmp) is not open.
- Device is BLOCKED waiting for media.
-====
-...
-\end{verbatim}
-\normalsize
-
-Now, here it should be clear that if a job were running that wanted
-to use the Autochanger (with two devices), it would block because
-the user unmounted the device. The real problem for the Job I started
-using the "File" device is that the device is blocked waiting for
-media -- that is Bacula needs you to label a Volume.
-
-\item [time]
- \index[general]{time}
- Prints the current time.
-
-\item [trace]
- \index[general]{trace}
- Turn on/off trace to file.
-
-\item [umount]
- \index[general]{umount}
- For old-time Unix guys. See the unmount command for full details.
-
-\item [unmount]
- \index[general]{unmount}
- This command causes the indicated Bacula Storage daemon to unmount the
- specified device. The forms of the command are the same as the mount command:
-\footnotesize
-\begin{verbatim}
-unmount storage=<storage-name> [ drive=<num> ]
-
-unmount [ jobid=<id> | job=<job-name> ]
-\end{verbatim}
-\normalsize
-
- Once you unmount a storage device, Bacula will no longer be able to use
- it until you issue a mount command for that device. If Bacula needs to
- access that device, it will block and issue mount requests periodically
- to the operator.
-
- If the device you are unmounting is an autochanger, it will unload
- the drive you have specified on the command line. If no drive is
- specified, it will assume drive 1.
-
-\label{UpdateCommand}
-\item [update]
- \index[general]{update}
- This command will update the catalog for either a specific Pool record, a Volume
- record, or the Slots in an autochanger with barcode capability. In the case
- of updating a Pool record, the new information will be automatically taken
- from the corresponding Director's configuration resource record. It can be
- used to increase the maximum number of volumes permitted or to set a maximum
- number of volumes. The following main keywords may be specified:
-\footnotesize
-\begin{verbatim}
- media, volume, pool, slots, stats
-\end{verbatim}
-\normalsize
-
-In the case of updating a Volume, you will be prompted for which value you
-wish to change. The following Volume parameters may be changed:
-
-\footnotesize
-\begin{verbatim}
-
- Volume Status
- Volume Retention Period
- Volume Use Duration
- Maximum Volume Jobs
- Maximum Volume Files
- Maximum Volume Bytes
- Recycle Flag
- Recycle Pool
- Slot
- InChanger Flag
- Pool
- Volume Files
- Volume from Pool
- All Volumes from Pool
- All Volumes from all Pools
-
-\end{verbatim}
-\normalsize
-
- For slots {\bf update slots}, Bacula will obtain a list of slots and
- their barcodes from the Storage daemon, and for each barcode found, it
- will automatically update the slot in the catalog Media record to
- correspond to the new value. This is very useful if you have moved
- cassettes in the magazine, or if you have removed the magazine and
- inserted a different one. As the slot of each Volume is updated, the
- InChanger flag for that Volume will also be set, and any other Volumes
- in the Pool that were last mounted on the same Storage device
- will have their InChanger flag turned off. This permits
- Bacula to know what magazine (tape holder) is currently in the
- autochanger.
-
- If you do not have barcodes, you can accomplish the same thing in
- version 1.33 and later by using the {\bf update slots scan} command.
- The {\bf scan} keyword tells Bacula to physically mount each tape and to
- read its VolumeName.
-
- For Pool {\bf update pool}, Bacula will move the Volume record from its
- existing pool to the pool specified.
-
- For {\bf Volume from Pool}, {\bf All Volumes from Pool} and {\bf All Volumes
- from all Pools}, the following values are updated from the Pool record:
- Recycle, RecyclePool, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles,
- and MaxVolBytes. (RecyclePool feature is available with bacula 2.1.4 or
- higher.)
-
- The full form of the update command with all command line arguments is:
-
-\footnotesize
-\begin{verbatim}
- update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
- VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
- slot=nnn enabled=n recyclepool=zzz
-
-\end{verbatim}
-\normalsize
-
-\item [use]
- \index[general]{use}
- This command allows you to specify which Catalog database to use. Normally,
-you will be using only one database so this will be done automatically. In
-the case that you are using more than one database, you can use this command
-to switch from one to another.
-
-use \lt{}database-name\gt{}
-
-\item [var]
- \label{var}
- \index[general]{var name}
- This command takes a string or quoted string and does variable expansion on
- it the same way variable expansion is done on the {\bf LabelFormat} string.
- Thus, for the most part, you can test your LabelFormat strings. The
- difference between the {\bf var} command and the actual LabelFormat process
- is that during the var command, no job is running so "dummy" values are
- used in place of Job specific variables. Generally, however, you will get a
- good idea of what is going to happen in the real case.
-
-\item [version]
- \index[general]{version}
- The command prints the Director's version.
-
-\item [wait]
- \index[general]{wait}
- The wait command causes the Director to pause until there are no jobs
- running. This command is useful in a batch situation such as regression
- testing where you wish to start a job and wait until that job completes
- before continuing. This command now has the following options:
-\footnotesize
-\begin{verbatim}
- wait [jobid=nn] [jobuid=unique id] [job=job name]
-\end{verbatim}
-\normalsize
- If specified with a specific JobId, ... the wait command will wait
- for that particular job to terminate before continuing.
-
-\end{description}
-
-\label{dotcommands}
-\section{Special dot Commands}
-\index[general]{Commands!Special dot}
-\index[general]{Special dot Commands}
-
-There is a list of commands that are prefixed with a period (.). These
-commands are intended to be used either by batch programs or graphical user
-interface front-ends. They are not normally used by interactive users. Once
-GUI development begins, this list will be considerably expanded. The following
-is the list of dot commands:
-
-\footnotesize
-\begin{verbatim}
-.backups job=xxx list backups for specified job
-.clients list all client names
-.defaults client=xxx fileset=yyy list defaults for specified client
-.die cause the Director to segment fault (for debugging)
-.dir when in tree mode prints the equivalent to the dir command,
- but with fields separated by commas rather than spaces.
-.exit quit
-.filesets list all fileset names
-.help help command output
-.jobs list all job names
-.levels list all levels
-.messages get quick messages
-.msgs return any queued messages
-.pools list all pool names
-.quit quit
-.status get status output
-.storage return storage resource names
-.types list job types
-\end{verbatim}
-\normalsize
-
-\label{atcommands}
-
-\section{Special At (@) Commands}
-\index[general]{Commands!Special At @}
-\index[general]{Special At (@) Commands}
-
-Normally, all commands entered to the Console program are immediately
-forwarded to the Director, which may be on another machine, to be executed.
-However, there is a small list of {\bf at} commands, all beginning with an at
-character (@), that will not be sent to the Director, but rather interpreted
-by the Console program directly. Note, these commands are implemented only in
-the tty console program and not in the Bat Console. These commands are:
-
-\begin{description}
-
-\item [@input \lt{}filename\gt{}]
- \index[general]{@input \lt{}filename\gt{}}
- Read and execute the commands contained in the file specified.
-
-\item [@output \lt{}filename\gt{} w/a]
- \index[general]{@output \lt{}filename\gt{} w/a}
- Send all following output to the filename specified either overwriting the
-file (w) or appending to the file (a). To redirect the output to the
-terminal, simply enter {\bf @output} without a filename specification.
-WARNING: be careful not to overwrite a valid file. A typical example during a
-regression test might be:
-
-\footnotesize
-\begin{verbatim}
- @output /dev/null
- commands ...
- @output
-
-\end{verbatim}
-\normalsize
-
-\item [@tee \lt{}filename\gt{} w/a]
- \index[general]{@tee \lt{}filename\gt{} w/a}
- Send all subsequent output to both the specified file and the terminal. It is
- turned off by specifying {\bf @tee} or {\bf @output} without a filename.
-
-\item [@sleep \lt{}seconds\gt{}]
- \index[general]{@sleep \lt{}seconds\gt{}}
- Sleep the specified number of seconds.
-
-\item [@time]
- \index[general]{@time}
- Print the current time and date.
-
-\item [@version]
- \index[general]{@version}
- Print the console's version.
-
-\item [@quit]
- \index[general]{@quit}
- quit
-
-\item [@exit]
- \index[general]{@exit}
- quit
-
-\item [@\# anything]
- \index[general]{anything}
- Comment
-
-\item [@help]
- \index[general]{@help}
- Get the list of every special @ commands.
-
-\item [@separator \lt{}char\gt{}]
-\index[general]{@separator}
- When using bconsole with readline, you can set the command separator to one
- of those characters to write commands who require multiple input on one line,
- or to put multiple commands on a single line.
-\begin{verbatim}
- !$%&'()*+,-/:;<>?[]^`{|}~
-\end{verbatim}
-
- Note, if you use a semicolon (;) as a separator character, which is
- common, you will not be able to use the {\bf sql} command, which
- requires each command to be terminated by a semicolon.
-
-\end{description}
-
-\label{scripting}
-\section{Running the Console from a Shell Script}
-\index[general]{Script!Running the Console Program from a Shell}
-\index[general]{Running the Console Program from a Shell Script}
-
-You can automate many Console tasks by running the console program from a
-shell script. For example, if you have created a file containing the following
-commands:
-
-\footnotesize
-\begin{verbatim}
- ./bconsole -c ./bconsole.conf <<END_OF_DATA
- unmount storage=DDS-4
- quit
- END_OF_DATA
-\end{verbatim}
-\normalsize
-
-when that file is executed, it will unmount the current DDS-4 storage device.
-You might want to run this command during a Job by using the {\bf
-RunBeforeJob} or {\bf RunAfterJob} records.
-
-It is also possible to run the Console program from file input where the file
-contains the commands as follows:
-
-\footnotesize
-\begin{verbatim}
-./bconsole -c ./bconsole.conf <filename
-\end{verbatim}
-\normalsize
-
-where the file named {\bf filename} contains any set of console commands.
-
-As a real example, the following script is part of the Bacula regression
-tests. It labels a volume (a disk volume), runs a backup, then does a restore
-of the files saved.
-
-\footnotesize
-\begin{verbatim}
-bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
-@output /dev/null
-messages
-@output /tmp/log1.out
-label volume=TestVolume001
-run job=Client1 yes
-wait
-messages
-@#
-@# now do a restore
-@#
-@output /tmp/log2.out
-restore current all
-yes
-wait
-messages
-@output
-quit
-END_OF_DATA
-\end{verbatim}
-\normalsize
-
-The output from the backup is directed to /tmp/log1.out and the output from
-the restore is directed to /tmp/log2.out. To ensure that the backup and
-restore ran correctly, the output files are checked with:
-
-\footnotesize
-\begin{verbatim}
-grep "^Termination: *Backup OK" /tmp/log1.out
-backupstat=$?
-grep "^Termination: *Restore OK" /tmp/log2.out
-restorestat=$?
-\end{verbatim}
-\normalsize
-
-\section{Adding Volumes to a Pool}
-\index[general]{Adding Volumes to a Pool}
-\index[general]{Pool!Adding Volumes to a}
-
-If you have used the {\bf label} command to label a Volume, it will be
-automatically added to the Pool, and you will not need to add any media to the
-pool.
-
-Alternatively, you may choose to add a number of Volumes to the pool without
-labeling them. At a later time when the Volume is requested by {\bf Bacula}
-you will need to label it.
-
-Before adding a volume, you must know the following information:
-
-\begin{enumerate}
-\item The name of the Pool (normally "Default")
-\item The Media Type as specified in the Storage Resource in the Director's
- configuration file (e.g. "DLT8000")
-\item The number and names of the Volumes you wish to create.
-\end{enumerate}
-
-For example, to add media to a Pool, you would issue the following commands to
-the console program:
-
-\footnotesize
-\begin{verbatim}
-*add
-Enter name of Pool to add Volumes to: Default
-Enter the Media Type: DLT8000
-Enter number of Media volumes to create. Max=1000: 10
-Enter base volume name: Save
-Enter the starting number: 1
-10 Volumes created in pool Default
-*
-\end{verbatim}
-\normalsize
-
-To see what you have added, enter:
-
-\footnotesize
-\begin{verbatim}
-*list media pool=Default
-+-------+----------+---------+---------+-------+------------------+
-| MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
-+-------+----------+---------+---------+-------+------------------+
-| 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-| 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
-+-------+----------+---------+---------+-------+------------------+
-*
-\end{verbatim}
-\normalsize
-
-Notice that the console program automatically appended a number to the base
-Volume name that you specify (Save in this case). If you don't want it to
-append a number, you can simply answer 0 (zero) to the question "Enter number
-of Media volumes to create. Max=1000:", and in this case, it will create a
-single Volume with the exact name you specify.
\tableofcontents
\clearpage
-\include{bconsole}
-\include{gui}
-\include{fdl}
+\include{bconsole-en}
+\include{fdl-en}
% The following line tells link_resolver.pl to not include these files:
--- /dev/null
+% TODO: maybe get rid of centering
+
+\chapter{GNU Free Documentation License}
+\index[general]{GNU Free Documentation License}
+\index[general]{License!GNU Free Documentation}
+
+\label{label_fdl}
+
+ \begin{center}
+
+ Version 1.2, November 2002
+
+
+ Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
+
+ \bigskip
+
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ \bigskip
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+\end{center}
+
+
+\begin{center}
+{\bf\large Preamble}
+\end{center}
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+\begin{center}
+{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
+\end{center}
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The \textbf{"Document"}, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as \textbf{"you"}. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A \textbf{"Modified Version"} of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The \textbf{"Cover Texts"} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The \textbf{"Title Page"} means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as \textbf{"Acknowledgements"},
+\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
+To \textbf{"Preserve the Title"}
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\begin{center}
+{\Large\bf 2. VERBATIM COPYING}
+\end{center}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\begin{center}
+{\Large\bf 3. COPYING IN QUANTITY}
+\end{center}
+
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+\begin{center}
+{\Large\bf 4. MODIFICATIONS}
+\end{center}
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+\begin{itemize}
+\item[A.]
+ Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+
+\item[B.]
+ List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+
+\item[C.]
+ State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+\item[D.]
+ Preserve all the copyright notices of the Document.
+
+\item[E.]
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+\item[F.]
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+
+\item[G.]
+ Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+
+\item[H.]
+ Include an unaltered copy of this License.
+
+\item[I.]
+ Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+
+\item[J.]
+ Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+
+\item[K.]
+ For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+
+\item[L.]
+ Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+
+\item[M.]
+ Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+\item[N.]
+ Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+
+\item[O.]
+ Preserve any Warranty Disclaimers.
+\end{itemize}
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+\begin{center}
+{\Large\bf 5. COMBINING DOCUMENTS}
+\end{center}
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+\begin{center}
+{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
+\end{center}
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+\begin{center}
+{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
+\end{center}
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+\begin{center}
+{\Large\bf 8. TRANSLATION}
+\end{center}
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+\begin{center}
+{\Large\bf 9. TERMINATION}
+\end{center}
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+\begin{center}
+{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
+\end{center}
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+\begin{center}
+{\Large\bf ADDENDUM: How to use this License for your documents}
+% TODO: this is too long for table of contents
+\end{center}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\bigskip
+\begin{quote}
+ Copyright \copyright YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+\end{quote}
+\bigskip
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+\bigskip
+\begin{quote}
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+\end{quote}
+\bigskip
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+%---------------------------------------------------------------------
+++ /dev/null
-% TODO: maybe get rid of centering
-
-\chapter{GNU Free Documentation License}
-\index[general]{GNU Free Documentation License}
-\index[general]{License!GNU Free Documentation}
-
-\label{label_fdl}
-
- \begin{center}
-
- Version 1.2, November 2002
-
-
- Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc.
-
- \bigskip
-
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
- \bigskip
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-\end{center}
-
-
-\begin{center}
-{\bf\large Preamble}
-\end{center}
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document "free" in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of "copyleft", which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
-
-\begin{center}
-{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
-\end{center}
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The \textbf{"Document"}, below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as \textbf{"you"}. You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A \textbf{"Modified Version"} of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License. If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
-Sections then there are none.
-
-The \textbf{"Cover Texts"} are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text. A copy that is not "Transparent" is called \textbf{"Opaque"}.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification. Examples of
-transparent image formats include PNG, XCF and JPG. Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The \textbf{"Title Page"} means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, "Title Page" means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language. (Here XYZ stands for a
-specific section name mentioned below, such as \textbf{"Acknowledgements"},
-\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.)
-To \textbf{"Preserve the Title"}
-of such a section when you modify the Document means that it remains a
-section "Entitled XYZ" according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-
-\begin{center}
-{\Large\bf 2. VERBATIM COPYING}
-\end{center}
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-
-\begin{center}
-{\Large\bf 3. COPYING IN QUANTITY}
-\end{center}
-
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-
-\begin{center}
-{\Large\bf 4. MODIFICATIONS}
-\end{center}
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
-\begin{itemize}
-\item[A.]
- Use in the Title Page (and on the covers, if any) a title distinct
- from that of the Document, and from those of previous versions
- (which should, if there were any, be listed in the History section
- of the Document). You may use the same title as a previous version
- if the original publisher of that version gives permission.
-
-\item[B.]
- List on the Title Page, as authors, one or more persons or entities
- responsible for authorship of the modifications in the Modified
- Version, together with at least five of the principal authors of the
- Document (all of its principal authors, if it has fewer than five),
- unless they release you from this requirement.
-
-\item[C.]
- State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-
-\item[D.]
- Preserve all the copyright notices of the Document.
-
-\item[E.]
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
-\item[F.]
- Include, immediately after the copyright notices, a license notice
- giving the public permission to use the Modified Version under the
- terms of this License, in the form shown in the Addendum below.
-
-\item[G.]
- Preserve in that license notice the full lists of Invariant Sections
- and required Cover Texts given in the Document's license notice.
-
-\item[H.]
- Include an unaltered copy of this License.
-
-\item[I.]
- Preserve the section Entitled "History", Preserve its Title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page. If
- there is no section Entitled "History" in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
-
-\item[J.]
- Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions
- it was based on. These may be placed in the "History" section.
- You may omit a network location for a work that was published at
- least four years before the Document itself, or if the original
- publisher of the version it refers to gives permission.
-
-\item[K.]
- For any section Entitled "Acknowledgements" or "Dedications",
- Preserve the Title of the section, and preserve in the section all
- the substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
-
-\item[L.]
- Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
-
-\item[M.]
- Delete any section Entitled "Endorsements". Such a section
- may not be included in the Modified Version.
-
-\item[N.]
- Do not retitle any existing section to be Entitled "Endorsements"
- or to conflict in title with any Invariant Section.
-
-\item[O.]
- Preserve any Warranty Disclaimers.
-\end{itemize}
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled "Endorsements", provided it contains
-nothing but endorsements of your Modified Version by various
-parties--for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-
-\begin{center}
-{\Large\bf 5. COMBINING DOCUMENTS}
-\end{center}
-
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled "History"
-in the various original documents, forming one section Entitled
-"History"; likewise combine any sections Entitled "Acknowledgements",
-and any sections Entitled "Dedications". You must delete all sections
-Entitled "Endorsements".
-
-\begin{center}
-{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
-\end{center}
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-
-\begin{center}
-{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
-\end{center}
-
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an "aggregate" if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-
-\begin{center}
-{\Large\bf 8. TRANSLATION}
-\end{center}
-
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled "Acknowledgements",
-"Dedications", or "History", the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-
-\begin{center}
-{\Large\bf 9. TERMINATION}
-\end{center}
-
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-
-\begin{center}
-{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
-\end{center}
-
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
-http://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License "or any later version" applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-
-
-\begin{center}
-{\Large\bf ADDENDUM: How to use this License for your documents}
-% TODO: this is too long for table of contents
-\end{center}
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-\bigskip
-\begin{quote}
- Copyright \copyright YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.2
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License".
-\end{quote}
-\bigskip
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the "with...Texts." line with this:
-
-\bigskip
-\begin{quote}
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-\end{quote}
-\bigskip
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-%---------------------------------------------------------------------
--- /dev/null
+%%
+%%
+
+\chapter{La console Bacula}
+\label{_ConsoleChapter}
+\index[general]{Console!Bacula}
+\index[general]{La console Bacula}
+\index[general]{Console!Bacula}
+\index[general]{LA console Bacula}
+\addcontentsline{toc}{section}{La console Bacula}
+
+\section{G\'en\'eralit\'es}
+\index[general]{G\'en\'eralit\'es}
+\addcontentsline{toc}{section}{G\'en\'eralit\'es}
+
+La {\bf console Bacula} (parfois d\'esign\'ee "Agent utilisateur") est un programme
+qui permet \`a l'utilisateur autoris\'e ou \`a l'administrateur syst\`eme d'interagir
+avec le Director.
+
+Actuellement, la console Bacula existe en deux versions : une interface shell
+(fa\c{c}on TTY), et une interface graphique GNOME. Avec la console Bacula, vous
+pouvez d\'eterminer l'\'etat d'un job particulier, examiner le contenu du
+catalogue et effectuer certaines manipulations de cartouches.
+
+Il existe d'autre part un programme nomm\'e bwx-console, b\^atie avec wxWidgets qui
+offre une interface graphique aux op\'erations de restauration.
+
+Etant donn\'e que la Console interagit avec le Director au travers du r\'eseau,
+il n'est pas n\'ecessaire que les deux programmes r\'esident sur la m\^eme machine.
+
+Bacula a besoin d'un minimum de retour de la Console afin de pouvoir utiliser plus
+d'une cartouche. En effet, lorsqu'il en r\'eclame une nouvelle, il attend jusqu'\`a
+ce qu'un op\'erateur lui indique, via la Console, qu'une nouvelle cartouche est mont\'ee.
+
+\section{Configuration de la Console}
+\index[general]{Configuration de la Console}
+\index[general]{Configuration!Console}
+\index[general]{Configuration de la Console}
+\index[general]{Configuration!Console}
+\addcontentsline{toc}{section}{Configuration de la Console}
+
+Lors de son lancement, la Console lit le fichier de configuration standard
+nomm\'e {\bf bconsole.conf} (ou {\bf gnome-console.conf} dans le cas de la version
+GNOME) Ce fichier d\'efinit une configuration par d\'efaut de la Console et, \`a l'heure
+actuelle, la seule ressource d\'efinie est la ressource Director, qui informe
+la Console du nom et de l'adresse du Director. Pour plus d'informations sur la
+configuration de la Console, voyez le chapitre \ilink{Configurer la Console}{_ChapterStart36}
+de ce manuel.
+
+\section{Utiliser la Console}
+\index[general]{Utiliser la Console}
+\index[general]{Console!Utiliser la}
+\index[general]{Utiliser la Console}
+\index[general]{Console!Utiliser la}
+\addcontentsline{toc}{section}{Utiliser la Console}
+
+Le programme Console admet les options suivantes :
+\footnotesize
+\begin{verbatim}
+Usage: bconsole [-s] [-c config_file] [-d debug_level]
+ -c <file> set configuration file to file
+ -dnn set debug level to nn
+ -n no conio
+ -s no signals
+ -t test - read configuration and exit
+ -? print this message.
+\end{verbatim}
+\normalsize
+
+Apr\`es son d\'emarrage, la Console est en attente de vos commandes, ce qui
+est indiqu\'e par une ast\'erisque (*) (ce n'est pas le cas dans la version
+GNOME o\`u vous saisissez vos commandes dans la boite texte en bas de l'\'ecran).
+Vous pouvez, pour toutes les commandes, vous contenter d'entrer le nom de la
+commande, la Console se chargera de vous demander les arguments n\'ecessaires,
+mais dans la plupart des cas, vous pouvez entrer les commandes suivies de leurs
+arguments. Le format g\'en\'eral est :
+
+\footnotesize
+\begin{verbatim}
+ <command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
+\end{verbatim}
+\normalsize
+
+O\`u {\bf command} est l'une des commandes \'enum\'er\'ees ci-dessous, {\bf keyword}
+est l'un des mots-clef \'enum\'er\'es ci-dessous (usuellement suivi d'un argument),
+et {\bf argument} est la valeur du mot-clef. La commande peut \^etre abr\'eg\'ee
+jusqu'\`a sa plus courte abr\'eviation unique. Si deux commandes commencent
+par les m\^emes lettres, c'est celle qui appara\^it en t\^ete dans la liste fournie
+par la commande {\bf help} qui sera s\'electionn\'ee si votre abr\'eviation est
+ambig\"ue. Aucun des mots-clef suivant la commande ne peut \^etre abr\'eg\'e.
+
+Par exemple :
+
+\footnotesize
+\begin{verbatim}
+list files jobid=23
+\end{verbatim}
+\normalsize
+
+\'enum\`ere les fichiers sauvegard\'es par le job de JobId 23.
+
+Cette autre commande :
+
+\footnotesize
+\begin{verbatim}
+show pools
+\end{verbatim}
+\normalsize
+
+affiche toutes les ressources Pool.
+
+\section{Quitter la Console}
+\index[general]{Console!Quitter}
+\index[general]{Quitter la Console}
+\index[general]{Console!Quitter}
+\index[general]{Quitter la Console}
+\addcontentsline{toc}{section}{Quitter la Console}
+
+Normalement, le programme Console se termine si vous saisissez {\bf quit}
+ou {\bf exit}. Cependant, il il attend jusq"\`a ce que le Director ait pris
+en compte la commande, ce qui peut prendre du temps si ce dernier est d\'ej\`a
+occup\'e \`a une t\^ache longue (par exemple, un \'elagage du catalogue). Si vous voulez
+quitter la Console imm\'ediatement, utilisez la commande {\bf .quit}.
+
+Il n'existe actuellement aucun moyen d'interrompre une commande de la Console
+une fois lanc\'ee (Ctrl-C ne marche pas). En revanche, \`a l'invite d'une commande
+vous demandant de choisir parmi plusieurs possibilit\'es, vous pouvez annuler
+la commande en entrant un point ({\bf .}), vous serez dans la plupart des cas
+ramen\'e \`a l'invite principal, ou \`a l'invite pr\'ec\'edente, dans le cas de choix
+imbriqu\'es. En quelques endroits, comme celui o\`u l'on vous demande un
+nom de volume, le point sera pris pour la r\'eponse (Bacula pensera que vous
+voulez nommer votre volume "."). Dans cette situation, vous serez la plupart
+du temps en mesure d'annuler \`a l'invite suivante.
+
+\label{keywords}
+\section{Index des mots-clef de la Console}
+\index[general]{Mots-clef!Index Console}
+\index[general]{Index des mots-clef de la Console}
+\index[general]{Mots-clef!Index Console}
+\index[general]{Index des mots-clef de la Console}
+\addcontentsline{toc}{section}{Index des mots-clef de la Console}
+Sauf sp\'ecification contraire, chacun des mots-clef suivant admet un argument,
+qui est sp\'ecifi\'e apr\`es le mot-clef suivi du signe \'egale. Par exemple :
+
+\begin{verbatim}
+jobid=536
+\end{verbatim}
+
+Notez que cette liste est probablement incompl\`ete, car le processus de cr\'eation
+est toujours en cours. Il se peut aussi qu'elle ne soit pas dans l'ordre
+alphab\'etique.
+
+\begin{description}
+\item [restart]
+ Permis dans la commande {\it python}, provoque le red\'emarrage de
+ l'interpr\'eteur Python. Ne prend pas d'arguments.
+\item [all]
+ Permis dans les commandes {\it status} et {\it show} pour sp\'ecifier, respectivement, tous les
+ composants ou toutes les ressources.
+\item [before]
+ Utilis\'e dans la commande {\it restore}.
+\item [bootstrap]
+ Utilis\'e dans la commande {\it restore}.
+\item [catalog]
+ Permis dans la commande {\it use} pour sp\'ecifier le nom de catalogue \`a utiliser.
+\item [catalogs]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments
+\item [client | fd]
+\item [clients]
+ Utilis\'e dans les commandes {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [counters]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [current]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [days]
+ Utilisé pour définir le nombre de jours que la commande "list nextvol" doit
+ prendre en compte dans son évaluation des prochains jobs à exécuter.
+ Le mot-clef "day" peut aussi être utilisé avec la commande "status dir"
+ afin qu'elle affiche les jobs planifiés pour la période spécifiés.
+\item [devices]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [dir | director]
+\item [directors]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [directory]
+ Utilis\'e dans la commande {\it restore}. Son argument spécifie
+ le répertoire à restaurer.
+\item [enabled]
+ Ce mot-clef peut être utilisé avec la commande {\bf update volume} et admet
+ l'un des arguments suivants : yes, true, no, false, archived, 0, 1, 2, où
+ 0 correspond à "no" ou "false", 1 à "yes" ou "true" et 2 à "archived". Les volumes
+ avec le statut "archived" ne seront pas utilisés, pas plus que ne seront élagués leurs
+ enregistrements dans le catalogue. Les volumes qui n'ont pas le statut "enabled"
+ ne seront pas utilisés pour des sauvegardes ou des restaurations.
+\item [done]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [file]
+ Utilis\'e dans la commande {\it restore}.
+\item [files]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [fileset]
+\item [filesets]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [help]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [jobs]
+ Utilis\'e dans les commandes {\it show}, {\it list} et {\it llist}. Ne prend pas d'arguments.
+\item [jobmedia]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [jobtotals]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [jobid]
+ Le JobId est le num\'ero de job qui est affich\'e dans le rapport de job.
+ C'est l'index du catalogue pour le job donn\'e. Bien qu'il soit unique
+ pour tous les jobs existant dans le catalogue, le m\^eme JobId peut
+ \^etre r\'eutilis\'e une fois qu'un job a \'et\'e supprim\'e du catalogue.
+ Vous d\'esignerez certainement les jobs sp\'ecifiques par leur JobId.
+\item [job | jobname]
+ Le mot-clef Job ou Jobname se r\'ef\`ere au nom que vous avez sp\'ecifi\'e
+ dans la ressource Job, et donc peut d\'esigner plusieurs jobs effectu\'es.
+ C'est particuli\`erement utile lorsque vous voulez la liste des jobs
+ execut\'es portant un nom particulier.
+\item [level]
+\item [listing]
+ Permis dans la commande {\it estimate}. Ne prend pas d'arguments.
+\item [limit]
+\item [messages]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [media]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [nextvol | nextvolume]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [on]
+ Ne prend pas d'arguments.
+\item [off]
+ Ne prend pas d'arguments.
+\item [pool]
+\item [pools]
+ Utilis\'e dans les commandes, {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [select]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [storages]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [schedules]
+ Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments.
+\item [sd | store | storage]
+\item [ujobid]
+ L'ujobid est un identificateur unique de job qui est affich\'e dans
+ le rapport du job. Actuellement, il consiste en le nom du job
+ (celui de la directive Name de ce job) suffix\'e de la date et de
+ l'heure d'ex\'ecution du job. Ce mot-clef est utile si vous voulez
+ identifier compl\`etement l'instance du job ex\'ecut\'e.
+\item [volume]
+\item [volumes]
+ Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments.
+\item [where]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\item [yes]
+ Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments.
+\end{description}
+
+\label{list}
+\section{Index des commandes de la Console}
+\index[general]{Commandes!Index des commandes de la Console}
+\index[general]{Index des commandes de la Console}
+\index[general]{Commandes!Index des commandes de la Console}
+\index[general]{Index des commandes de la Console}
+\addcontentsline{toc}{section}{Index des commandes de la Console}
+
+Les commandes suivantes sont actuellement impl\'ement\'ees :
+
+\begin{description}
+\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{}
+ jobid=\lt{}JobId\gt{}]} ]
+ \index[general]{add}
+Cette commande sert \`a ajouter des volumes \`a un pool existant. Les noms des
+volumes saisis sont plac\'es dans le catalogue et deviennent ainsi disponibles
+pour les sauvegardes. Normalement, on pr\'ef\`er utiliser la commande {\bf label}
+qui remplit les m\^emes fonctions en plus d'apposer une \'etiquette logicielle
+(label) sur les bandes, par opposition \`a {\bf add} qui se contente de
+r\'ef\'erencer le volume dans le catalogue. Ainsi, si vous utilisez {\bf add},
+le volume doit pr\'eexister et \^etre d\'ej\`a \'etiquet\'e. Cette commande peut
+cependant \^etre utile si vous voulez ajouter plusieurs cartouches dans un
+pool en ne les \'etiquettant que plus tard. Elle peut aussi se r\'ev\'eler utile
+si vous importez des cartouches provenant d'un autre site. Consultez le
+paragraphe sur la commande {\bf label} pour conna\^itre la liste des
+caract\`eres autoris\'es dans un nom de volume.
+
+\item [autodisplay on/off]
+ \index[general]{autodisplay on/off}
+ Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou
+ d\'esactive l'affichage automatique des messages. La valeur par d\'efaut dans
+ la Console est {\bf off}, ce qui signifie que les messages en attente
+ vous sont notifi\'es, mais qu'ils ne sont pas automatiquement affich\'es.
+ La valeur par d\'efaut pour la console GNOME est {\bf on}, ainsi les
+ messages sont affich\'es lorqu'ils sont re\c{c}us (habituellement dans les 5 secondes
+ apr\`es qu'ils aient \'et\'e g\'en\'er\'es).
+
+ Lorsque l'affichage automatique est d\'esactiv\'e, vous devez explicitement
+ en demander l'affichage avec la commande {\bf messages}.
+
+\item [automount on/off]
+ \index[general]{automount on/off}
+ Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou
+ d\'esactive le montage automatique de la cartouche apr\`es une commande {\bf label}.
+ La valeur par d\'efaut est {\bf on}. Si le montage automatique est d\'esactiv\'e,
+ vous devez explicitement monter la cartouche apr\`es avoir utilis\'e {\bf label}
+ pour pouvoir \'ecrire dessus.
+
+\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}]
+ \index[general]{cancel jobid}
+ Cette commande sert \`a supprimer un job et admet les arguments {\bf jobid=nnn}
+ ou {\bf job=xxx} o\`u nnn est \`a remplacer par le JobId et xxx par le nom de
+ job. Si vous lancez cette commande sans arguments, la Console vous propose
+ de choisir parmi les jobs actifs celui \`a supprimer.
+
+ Une fois qu'un job est marqu\'e "A supprimer", il peut se passer quelques instants
+ (en g\'en\'eral, moins d'une minute) avant qu'il se termine, en fonction des
+ op\'erations en cours.
+
+\item [{ create [pool=\lt{}pool-name\gt{}]}]
+ \index[general]{create pool}
+ Cette commande sert \`a cr\'eer un enregistrement Pool dans le catalogue
+ selon les ressources Pool d\'efinis dans le fichier de configuration
+ du Director. En un sens, cette commande se content de transf\'erer
+ l'information depuis la ressource Pool dans le fichier de configuration
+ vers le catalogue. En principe, cete commande est automatiquement
+ ex\'ecut\'ee au lancement du Director, pourvu que le pool soit r\'ef\'erenc\'e
+ dans une ressource Job. Si vous utilisez cette commande sur un pool
+ existant, elle met \`a jour le catalogue en foction des informations de
+ la ressource Pool. Apr\`es avoir cr\'e\'e un pool, vous uiliserez
+ probablement la commande {\bf label} pour \'etiqueter un ou plusieurs
+ volumes et enregistrer leurs noms dans le catalogue.
+
+ Si, au lancement d'un job, Bacula d\'etermine qu'il n'y a pas de pool
+ enregistr\'e dans le catalogue, mais qu'il existe une ressource Pool pour
+ le pool appropri\'e, alors il le cr\'e\'e pour vous. Si vous voulez le voir
+ appara\^itre imm\'ediatement dans le catalogue, utilisez cette commande pour
+ forcer sa cr\'eation imm\'ediate.
+
+\item [{ delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job
+ jobid=\lt{}id\gt{}]}]
+ \index[general]{delete}
+ Cette commande s'utilise pour supprimer un volume, un pool ou un job
+ du catalogue, ainsi que tous les enregistrements du catalogue qui leur
+ sont associ\'es. Cette commande op\`ere exclusivement sur le catalogue
+ et n'a aucune r\'epercussion sur les donn\'ees \'ecrites sur les cartouches.
+ Elle peut \^etre dangereuse, et nous vous recommandons fortement de ne
+ pas l'utiliser si vous ne savez pas exactement ce que vous faites.
+
+ Voici la forme compl\`ete de cette commande :
+
+\begin{verbatim}
+delete pool=\lt{}pool-name\gt{}
+\end{verbatim}
+
+ supprime un pool du catalogue.
+
+\begin{verbatim}
+delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{}
+\end{verbatim}
+
+ supprime du catalogue un volume du pool sp\'ecifi\'e.
+
+\begin{verbatim}
+delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ...
+\end{verbatim}
+
+ supprime du catalogue le job sp\'ecifi\'e.
+
+\begin{verbatim}
+delete Job JobId=n,m,o-r,t ...
+\end{verbatim}
+
+ supprime les job de JobIds m,n,o,p,q,r et t (o\`u m,n,... sont, bien sur, des
+ nombres). Ainsi, la commande "delete jobid" accepte les listes et les plages
+ de jobids.
+
+\item [disable job\lt{}job-name\gt{}]
+ \index[general]{enable}
+ Cette commande vous permet de d\'esactiver un job normalement planifi\'e
+ pour ex\'ecution. Le job peut avoir \'et\'e pr\'ealablement activ\'e par la
+ directive {\bf Enabled} dans la ressource Job, ou avec la commande
+ {\bf enable} dans la Console. Au prochain d\'emarrage du Director, ou
+ si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera
+ r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut
+ est enabled).
+
+\item [enable job\lt{}job-name\gt{}]
+ \index[general]{enable}
+ Cette commande vous permet de d'activer un job planifi\'e
+ pour ex\'ecution automatique. Le job peut avoir \'et\'e pr\'ealablement d\'esactiv\'e par la
+ directive {\bf Disabled} dans la ressource Job, ou avec la commande
+ {\bf disable} dans la Console. Au prochain d\'emarrage du Director, ou
+ si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera
+ r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut
+ est enabled).
+
+\label{estimate}
+\item [estimate]
+ \index[general]{estimate}
+ Avec cette commande, vous pouvez vous faire une id\'ee du nombre de fichier
+ seront sauvegard\'es. Vous pouvez aussi l'utiliser pour \'eprouver les
+ param\`etres Include de vos FileSets sans passer par une sauvegarde
+ r\'eelle. Par d\'efaut, l'estimation est faite pour une sauvegarde Full.
+ Cependant, vous pouvez passer outre ce comportement en sp\'ecifiant
+ {\bf level=Incremental} ou {\bf level=Differential} sur la ligne de
+ commande. Un nom de job doit \^etre sp\'ecifi\'e, faute de quoi il vous sera
+ demand\'e. Optionnellement, vous pouvez sp\'ecifier un client et un
+ FileSet sur la ligne de commande. Bacula contacte alors le client
+ et calcule le nombre de fichier et d'octets qui seraient
+ sauvegard\'es. Notez qu'il s'agit d'une estimation calcul\'ee d'apr\`es
+ le nombre de blocs dans les fichiers plut\^ot qu'en lisant le nombre
+ effectif d'octets. Aussi, la taille estim\'ee est g\'en\'eralement plus
+ importante que celle de la sauvegarde r\'eelle.
+
+ Optionnellement, vous pouvez ajouter le mot-clef {\bf listing}, auquel cas
+ tous les fichiers \`a sauvegarder seront affich\'es. Notez qu'un tel affichage
+ peut prendre un certain temps s'il s'agit d'une grosse sauvegarde.
+ Voici la forme compl\`ete de cette commande :
+
+\begin{verbatim}
+estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{}
+ fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{}
+\end{verbatim}
+
+ La sp\'ecification du {\bf job} est suffisante, mais vous pouvez aussi
+ passer outre le client, le FileSet et/ou le niveau en les
+ sp\'ecifiant sur la ligne de commande.
+
+ Par exemple, vous pourriez faire ceci :
+
+\footnotesize
+\begin{verbatim}
+ @output /tmp/listing
+ estimate job=NightlySave listing level=Incremental
+ @output
+\end{verbatim}
+\normalsize
+
+ce qui produirait une liste compl\`ete de tous les fichiers \`a sauvegarder pour
+le job {\bf NightlySave} au cours d'une sauvegarde incr\'ementale, et qui
+consignerait cette liste dans le fichier {\bf /tmp/listing}. Notez que l'évaluation
+produite par cette commande se base sur les tailles de fichiers contenues dans
+l'objet "répertoire", aussi l'estimation peut être très éloignée de la réalité si vous
+avez des fichiers creux (NDT : sparse files) sur votre système. Ce type de fichiers se
+rencontre souvent sur les systèmes 64 bits avec certains systèmes de fichiers.
+Le volume obtenu par l'évaluation est celui que sauvegardera Bacula si l'option
+sparse est désactivée. Il n'y a actuellement aucun moyen d'évaluer le volume de
+ce qui serait sauvegardé avec l'option sparse activée.
+
+\item [help]
+ \index[general]{help}
+ Cette commande affiche la liste des commandes disponibles.
+
+\item [label]
+ \index[general]{label}
+ \index[general]{relabel}
+ \index[general]{label}
+ \index[general]{relabel}
+ Cette commande est utilis\'ee pour \'etiqueter les volumes. La forme compl\`ete est :
+
+\begin{verbatim}
+ label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{}
+ slot=\lt{}slot\gt{}
+\end{verbatim}
+
+ Si vous omettez l'un quelconque des arguments, il vous sera r\'eclam\'e.
+ Le type de m\'edia est automatiquement r\'ecup\'er\'e de la ressource Storage.
+ Une fois que les informations requises sont r\'eunies, la Console
+ contacte le Storage Daemon sp\'ecifi\'e et lui ordonne d'\'etiqueter la
+ cartouche sp\'ecifi\'ee. Si l'\'etiquetage s'effectue correctement, la
+ Console cr\'e\'e un nouvel enregistrement dans le catalogue pour le
+ volume dans le pool appropri\'e.
+
+ Les noms de volumes ne doivent contenir que des lettres, chiffres et
+ les caract\`eres sp\'eciaux tiret ({\bf -}), sous-lign\'e ({\bf \_}), double-point
+ ({\bf :}), et point ({\bf .}). Tous les autres caract\`eres, y compris l'espace,
+ sont ill\'egaux. Cette restriction vise \`a assurer une bonne lisibilit\'e
+ des noms de volumes pour r\'eduire le risque d'erreurs humaines.
+
+ Notez que lors de l'\'etiquetage d'une cartouche vierge, Bacula obtient des
+ erreurs {\bf read I/O error} lorqu'il tente de v\'erifier si la cartouche
+ a d\'ej\`a un label. Si vous voulez \'eviter ce genre de message, placez un
+ indicateur de fin de fichier sur votre cartouche avant son \'etiquetage :
+
+\footnotesize
+\begin{verbatim}
+ mt rewind
+ mt weof
+
+\end{verbatim}
+\normalsize
+
+La commande label peut \'echouer pour plusieurs raisons :
+
+
+\begin{enumerate}
+\item Le nom de volume que vous avez sp\'ecifi\'e figure d\'ej\`a dans le catalogue.
+\item Le Storage Daemon a d\'ej\`a une cartouche mont\'ee dans le lecteur. Dans ce cas,
+ vous devez la d\'emonter ({\bf unmount}) et ins\'erer une cartouche vierge
+ avant de lancer la commande {\bf label}.
+\item La cartouche dans le lecteur porte d\'ej\`a une \'etiquette Bacula.
+ (Bacula ne r\'e-\'etiquette jamais une cartouche \`a moins qu'elle soit recycl\'ee
+ et que vous utilisiez la commande {\bf relabel} ).
+\item Il n'y a pas de cartouche dans le lecteur.
+\end{enumerate}
+
+Il existe deux moyens pour r\'e-\'etiqueter un volume qui porte d\'ej\`a une
+\'etiquette Bacula. La m\'ethode brutale consiste \`a \'ecrire une marque de fin de
+fichier sur la cartouche vec la commande du syst\`eme d'exploitation {\bf mt},
+quelque chose dans ce style :
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/st0 rewind
+ mt -f /dev/st0 weof
+\end{verbatim}
+\normalsize
+
+puis d'utiliser la commande {\bf label} pour ajouter une nouvelle \'etiquette.
+Cette m\'ethode peut cependant laisser des traces de l'ancien volume dans le
+catalogue.
+
+Il est pr\'ef\'erable d'utiliser la commande {\bf relabel} d\'ecrite ci-dessous sur
+un volume purg\'e (automatiquement ou avec la commande {\bf purge}).
+
+Si votre librairie comporte un lecteur de codes barres, vous pouvez
+\'etiqueter tous les volumes qu'elle contient en
+utilisant la commande {\bf label barcodes}. En effet, apr\`es le lancement de
+cette commande, Bacula monte chaque cartouche l'une apr\`es l'autre et
+l'\'etiquette du nom de son code barres. simultan\'ement, l'enregistrement
+appropri\'e est cr\'e\'e dans le catalogue. Toute cartouche dont le code barres
+commence par les m\^emes caract\`eres que ceux sp\'ecifi\'es par la directive
+"CleaningPrefix" de la ressource Pool du director est consid\'er\'ee comme
+une cartouche de nettoyage et ne re\c{c}oit donc pas d'\'etiquette, bien
+qu'une entr\'ee dans le catalogue lui soit d\'edi\'ee. Par exemple avec :
+
+\footnotesize
+\begin{verbatim}
+ Pool {
+ Name ...
+ Cleaning Prefix = "CLN"
+ }
+
+\end{verbatim}
+\normalsize
+
+tout slot contenant une cartouche de code barres CLNxxxxx sera trait\'ee en tant
+que cartouche de nettoyage et ne sera jamais mont\'ee. Notez que la forme
+compl\`ete de la commande est :
+
+\footnotesize
+\begin{verbatim}
+update storage=xxx pool=yyy slots=1-5,10 barcodes
+\end{verbatim}
+\normalsize
+
+\item [list]
+ \index[general]{list}
+ La commande {\bf list} extrait du catalogue les informations demand\'ees. Les
+ diff\'erentes champs de chaque enregistrement sont \'enum\'er\'es sur une simple
+ ligne. Voici les diff\'erentes formes de la commande :
+
+\footnotesize
+\begin{verbatim}
+ list jobs
+
+ list jobid=<id> (affiche le jobid id)
+
+ list ujobid=<unique job name> (affiche le job dont le nom unique est <unique job name>)
+
+ list job=<job-name> (Affiche tous les jobs dont le nom est "job-name")
+
+ list jobname=<job-name> (voir ci-dessus)
+
+ Dans cette commande, vous pouvez ajouter "limit=nn" pour limiter la sortie \`a nn jobs.
+
+ list jobmedia
+
+ list jobmedia jobid=<id>
+
+ list jobmedia job=<job-name>
+
+ list files jobid=<id>
+
+ list files job=<job-name>
+
+ list pools
+
+ list clients
+
+ list jobtotals
+
+ list volumes
+
+ list volumes jobid=<id>
+
+ list volumes pool=<pool-name>
+
+ list volumes job=<job-name>
+
+ list volume=<volume-name>
+
+ list nextvolume job=<job-name>
+
+ list nextvol job=<job-name>
+
+ list nextvol job=<job-name> days=nnn
+
+
+
+\end{verbatim}
+\normalsize
+
+ Ce que font la plupart des commandes ci-dessus devrait \^etre plus ou moins \'evident.
+ En g\'en\'eral, si vous ne sp\'ecifiez pas tous les arguments requis, la Console
+ vous sollicitera pour les arguments manquants.
+
+ La commande {\bf list nextvol} affiche le nom du volume qui dera utilis\'e par
+ le job sp\'ecifi\'e. Soyez conscient que le prochain volume utilis\'e
+ pour un job d\'epend de nombreux facteurs dont le temps, et les autres
+ jobs qui seront ex\'ecut\'es avant celui sp\'ecifi\'e, qui peuvent remplir une
+ cartouche qui \'etait vide au moment de l'ex\'ecution de {\bf list nextvol}.
+ Aussi, consid\'erez la r\'eponse fournie par cette commande comme une bonne
+ estimation plut\^ot que comme une r\'eponse d\'efinitive. De plus, cette commande
+ a certains effets de bord : \'etant donn\'e qu'elle ex\'ecute le m\^eme algorithme
+ qu'un job, elle est susceptible de purger ou recycler un volume. Par d\'efaut,
+ le job sp\'ecifi\'e doit \^etre ex\'ecut\'e dans les deux jours ou aucun volume
+ ne sera trouv\'e. Vous pouvez cependant sp\'ecifier jusqu'\`a 50 jours en avant
+ avec la directive {\bf days=nnn}. Si, par exemple, un vendredi, vous voulez
+ savoir quel volume sera requis lundi pour le job MyJob, utilisez
+ {\bf list nextvol job=MyJob days=3}.
+
+ Si vous souhaitez ajouter vos propres commandes pour interroger le
+ catalogue, vous pouvez les placer dans le fichier {\bf query.sql}.
+ Cela demande quelques connaissances du langage SQL. Voyez le
+ paragraphe sur la commande {\bf query} ci-dessous pour plus
+ d'informations. Voyez aussi le paragraphe sur la commande
+ {\bf llist} qui permet l'affichage complet des informations du
+ catalogue.
+
+ Voici un exemple d'affichage produit par la commande {\bf list pools} :
+
+\footnotesize
+\begin{verbatim}
++------+---------+---------+---------+----------+-------------+
+| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
++------+---------+---------+---------+----------+-------------+
+| 1 | Default | 0 | 0 | Backup | * |
+| 2 | Recycle | 0 | 8 | Backup | File |
++------+---------+---------+---------+----------+-------------+
+\end{verbatim}
+\normalsize
+
+ Comme mentionn\'e pr\'ec\'edemment, la commande {\bf list} affiche des
+ informations du catalogue. Certais \'el\'ements sont ajout\'es dans le catalogue
+ d\`es le d\'emarrage de Bacula, mais en g\'en\'eral, la plupart ne le sont que
+ lorsqu'ils sont utilis\'es pour la premi\`ere fois. C'est le cas des clients,
+ des jobs, etc.
+
+ Bacula cr\'e\'e une entr\'ee relative \`a un nouveau client dans le catalogue
+ la premi\`ere fois que vous ex\'ecut\'ez un job pour ce client. L'entr\'ee est
+ cr\'e\'ee que le job aboutisse ou qu'il \'echoue, mais il doit au moins d\'emarrer.
+ Lorsque le client est contact\'e, des informations suppl\'ementaires sont
+ r\'ecup\'er\'ees du client (le r\'esultat d'un "uname -a") et ajout\'ees au
+ catalogue. Un {\bf status} n'entra\^ine pas l'enregistrement dans le catalogue.
+
+ Si vous voulez visualiser les ressources Client disponibles dans votre
+ catalogue, utilisez la commande {\bf show clients}.
+
+\item [llist]
+ \index[general]{llist}
+ La commande {\bf llist} (pour "long list") admet les m\^emes arguments que la
+ commande list d\'ecrite ci-dessus. La diff\'erence est que {\bf llist} affiche
+ le contenu complet de chaque enregistrement du catalogue s\'electionn\'e.
+ L'affichage des diff\'erents champs est produit verticalement, un champ par
+ ligne. Cette commande peut \^etre tr\`es prolixe.
+
+ Si, au lieu du {\bf list pools} de l'exemple pr\'ec\'edent, vous saisissez
+ {\bf llist pools}, vous obtiendrez un affichage de ce genre :
+
+\footnotesize
+\begin{verbatim}
+ PoolId: 1
+ Name: Default
+ NumVols: 0
+ MaxVols: 0
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 1,296,000
+ VolUseDuration: 86,400
+ MaxVolJobs: 0
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: *
+
+ PoolId: 2
+ Name: Recycle
+ NumVols: 0
+ MaxVols: 8
+ UseOnce: 0
+ UseCatalog: 1
+ AcceptAnyVolume: 1
+ VolRetention: 3,600
+ VolUseDuration: 3,600
+ MaxVolJobs: 1
+ MaxVolBytes: 0
+ AutoPrune: 0
+ Recycle: 1
+ PoolType: Backup
+ LabelFormat: File
+
+\end{verbatim}
+\normalsize
+
+\item [messages]
+ \index[general]{messages}
+ Cette commande affiche imm\'ediatement tout message de la console en attente.
+
+
+\item [mount]
+ \index[general]{mount}
+
+ La commande {\bf mount} est utilis\'ee pour obtenir de Bacula qu'il lise
+ un volume charg\'e dans un lecteur. C'est un moyen d'indiquer \`a Bacula
+ que vous avez charg\'e une cartouche qu'il doit examiner. Cette commande
+ n'est utilis\'ee que lorsque Bacula a demand\'e votre intervention pour
+ charger un lecteur vide, ou lorsque vous avez explicitement d\'emont\'e
+ un volume avec la commande {\bf unmount} dans la Console, ce qui
+ provoque la fermeture du lecteur. Si vous avez une librairie, vous ne
+ ferez pas op\'erer Bacula dessus avec la commande mount. Voici les
+ diff\'erentes formes de cette commande :
+
+mount storage=\lt{}storage-name\gt{}
+
+mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ]
+
+ Si vous avez sp\'ecifi\'e {\bf Automatic Mount = yes} dans la ressource
+ Device du Storage Daemon, Alors Bacula pourra acc\'eder automatiquement
+ au volume, \`a moins que vous ne l'ayez explicitement d\'emont\'e ({\bf unmount})
+ dans la Console.
+
+\item[python]
+ \index[general]{python}
+ La commande {\bf python} n'admet qu'un argument : {\bf restart}.
+
+ La commande {\bf python} {\bf restart} r\'einitialise l'interpr\'eteur Python
+ du Director. Ceci peut \^etre tr\`es utile pour effectuer des tests, car une
+ fois que le Director est lanc\'e, et l'interpr\'eteur Python initialis\'e,
+ il n'y a pas d'autre moyen de lui faire int\'egrer des modifications
+ du script de d\'emarrage {\bf DirStartUp.py}. Pour plus de d\'etails sur
+ l'\'ecriture de scripts Python, consultez le chapitre \ilink{Ecrire des
+ scripts Python}{_ChapterStart60}.
+
+\label{ManualPruning}
+\item [prune]
+ \index[general]{prune}
+ La commande {\bf prune} permet d'\'elaguer en toute s\'ecurit\'e les
+ enregistrements expir\'es du catalogue pour les jobs et les volumes.
+ Cette commande n'affecte que le catalogue, et non les donn\'ees
+ \'ecrites sur les volumes. Dans tous les cas, la commande {\bf prune}
+ respecte les p\'eriodes de r\'etention des enregistrements sp\'ecifi\'es.
+ Vous pouvez \'elaguer les jobs expir\'es, ainsi que les jobs et fichiers
+ d'un volume sp\'ecifi\'e.
+
+prune files|jobs|volume client=\lt{}client-name\gt{}
+volume=\lt{}volume-name\gt{}
+
+ Pour qu'un volume soit \'elagu\'e, son {\bf VolStatus} doit \^etre Full,
+ Used, ou Append, faute de quoi l'\'elagage sera sans effet.
+
+\item [purge]
+ \index[general]{purge}
+ La commande {\bf purge} efface les enregistrements sp\'ecifi\'es du catalogue
+ sans \'egards pour les p\'eriodes de r\'etention. {\bf Purge} n'affecte que le
+ catalogue, et non les donn\'ees \'ecrites sur les volumes. Cette commande
+ peut se r\'ev\'eler tr\`es dangereuse car vous pouvez parfaitement supprimer
+ les enregistrements relatifs \`a des sauvegardes valides et r\'ecentes. Aussi,
+ nous vous recommandons de ne pas l'utiliser \`a moins de savoir exactement
+ ce que vous faites. Voici les diff\'erentes formes de la commande {\bf purge} :
+
+purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{}
+
+purge jobs client=\lt{}client-name\gt{} (of all jobs)
+
+purge volume|volume=\lt{}vol-name\gt{} (of all jobs)
+
+
+ Pour qu'un volume puisse \^etre purg\'e, son {\bf VolStatus} doit \^etre Full,
+ Used, ou Append, faute de quoi la purge sera sans effet.
+
+\item [relabel]
+ \index[general]{relabel}
+ \index[general]{relabel}
+ Cette commande sert \`a r\'e-\'etiqueter physiquement un volume. En voici
+ la forme compl\`ete :
+
+relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{}
+ volume=\lt{}newvolume-name\gt{}
+
+ Si vous omettez l'un quelconque des arguments, la console vous sollicitera
+ pour obtenir les informations manquantes. Pour qu'un volume puisse \^etre
+ r\'e-\'etiquet\'e, il doit figurer dans le catalogue, et avoir le statut
+ {\bf Purged} ou {\bf Recycle}. Cette situation peut se pr\'esenter
+ automatiquement par l'application des p\'eriodes de r\'etention, ou vous
+ pouvez l'obtenir par une {\bf purge} explicite du volume.
+
+ Une fois que le volume a \'et\'e physiquement r\'e-\'etiquet\'e, les donn\'ees
+ qu'il contenait sont d\'efinitivement et irr\'em\'ediablement perdues.
+
+\item [release]
+ \index[general]{release}
+ Cette commande ordonne au Storage Daemon de rembobiner la cartouche
+ dans le lecteur, et de relire son \'etiquette \`a la prochaine utilisation
+ de la cartouche.
+
+release storage=\lt{}storage-name\gt{}
+
+ Apr\`es cette commande, le lecteur est gard\'e \`a l'\'etat ouvert par Bacula
+ (sauf si l'option Always Open est d\'esactiv\'ee dans la configuration
+ du Storage Daemon), et il ne peut donc \^etre utilis\'e par un autre
+ programme. Toutefois, il est possible, avec certains lecteurs, de
+ changer la cartouche \`a ce stade. Lors du prochain job, Bacula saura
+ relire l'\'etiquette de la cartouche pour savoir laquelle est mont\'ee.
+ Si vous voulez \^etre en mesure d'utiliser le lecteur avec un autre
+ programme, par exemple {\bf mt}, vous devez uiliser la commande
+ {\bf unmount} pour que Bacula le lib\`ere compl\`etement.
+
+\item [reload]
+ \index[general]{reload}
+ Lorsqu'il re\c{c}oit la commande {\bf reload}, le Director relit ses fichiers
+ de configuration et applique les \'eventuelles modifications. Celles-ci
+ sont prises en compte imm\'ediatement, et donc effectives pour tous les
+ jobs \`a venir. Notez cependant qu'en ce qui concerne les modifications
+ apport\'ees aux Schedules, la prise en compte des nouvelles valeur peut
+ \^etre report\'ee au del\`a de l'ex\'ecution des jobs d\'ej\`a planifi\'es pour
+ les deux prochaines heures. Ceci est d\^u au planificateur qui pr\'evoit
+ "pr\'e-planifie" jusqu'\`a deux heures \`a l'avance les jobs \`a ex\'ecuter.
+ Ainsi, des jobs qui ont d\'ej\`a \'et\'e "pr\'e-planifi\'es" seront ex\'ecut\'es
+ suivant les valeurs sp\'ecifi\'ees par la ressource Schedule avant sa
+ modification. Les nouveaux jobs utiliseront les nouvelles valeurs.
+ A chaque fois que vous utilisez la commande {\bf reload} alors que
+ des jobs sont en cours d'ex\'ecution, les valeurs de la configuration
+ pr\'ec\'edente demeurent en vigueur jusqu'\`a ce que les ces jobs se terminent.
+ Le Director peut ainsi conserver jusqu'\`a 10 jeux de configurations
+ ant\'erieures avant de refuser une nouvelle commande {\bf reload}.
+ Une fois que l'un, au moins, des jeux de valeurs ant\'erieur a \'et\'e accept\'e,
+ il peut \`a nouveau accepter de nouvelles commandes {\bf reload}.
+
+ Bien qu'il soit possible de recharger la configuration du Director
+ \`a la vol\'ee, alors m\^eme que des jobs sont en cours d'ex\'ecution, il faut
+ garder \`a l'esprit que c'est une op\'eration complexe, qui n'est pas d\'enu\'ee
+ d'effets de bords. C'est pourquoi il est recommand\'e, si vous \^etes amen\'e \`a
+ utiliser la commande {\bf reload}, de red\'emarrer le Director d\`es que vous
+ en aurez l'opportunit\'e.
+
+\label{restore_command}
+\item [restore]
+ \index[general]{restore}
+ La commande {\bf restore} vous permet de s\'electionner un ou plusieurs jobs
+ (JobIds) \`a restaurer selon plusieurs m\'ethodes. Une fois que les JobIds ont
+ \'et\'e s\'electionn\'es, les enregistrements de fichiers sont plac\'es dans une
+ arborescence interne \`a Bacula, et la Console entre dans un mode de
+ s\'election interactif qui vous permet de naviguer dans cette arborescence
+ en s\'electionnant individuellement les fichiers ou r\'epertoires \`a restaurer.
+ Ce mode est assez similaire au mode de s\'election interactif du programme
+ Unix {\bf restore} standard.
+
+restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{}
+ where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{}
+ select current all done
+
+ O\`u l'option {\bf current}, si elle est sp\'ecifi\'ee, indique \`a la commande
+ {\bf restore} de s\'electionner automatiquement la sauvegarde la plus
+ r\'ecente (sinon, vous serez sollicit\'e \`a ce sujet). L'option {\bf all},
+ si elle est sp\'ecifi\'ee, indique \`a la commande {\bf restore} de restaurer
+ tous les fichiers (sinon, vous serez sollicit\'e \`a ce sujet). Pour plus de
+ d\'etails concernant la commande {\bf restore}, consultez le chapitre
+ \ilink{Restaurations avec Bacula}{_ChapterStart13}.
+
+\item [run]
+ \index[general]{run}
+ Cette commande vous permet d'ex\'ecuter imm\'ediatement vos jobs. Voici la forme
+ compl\`ete de cette commande :
+
+run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{}
+ fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{}
+ storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{}
+ when=\lt{}universal-time-specification\gt{} yes
+
+ Toute information omise quoique requise fait l'objet d'une liste de s\'election,
+ et avant le lancement du job, un bilan des param\`etres vous est pr\'esent\'e avec
+ options d'accord, refus et modification, \`a moins que vous ayez sp\'ecifi\'e
+ {\bf yes}, auquel cas le job est imm\'ediatement envoy\'e vers le planificateur.
+
+ Sur mon syst\`eme, j'obtiens ce qui suit lorsque je lance la commande run :
+
+\footnotesize
+\begin{verbatim}
+A job name must be specified.
+The defined Job resources are:
+ 1: Matou
+ 2: Polymatou
+ 3: Rufus
+ 4: Minimatou
+ 5: Minou
+ 6: PmatouVerify
+ 7: MatouVerify
+ 8: RufusVerify
+ 9: Watchdog
+Select Job resource (1-9):
+
+\end{verbatim}
+\normalsize
+
+Si je choisis le num\'ero 5, j'obtiens :
+
+\footnotesize
+\begin{verbatim}
+Run Backup job
+JobName: Minou
+FileSet: Minou Full Set
+Level: Incremental
+Client: Minou
+Storage: DLTDrive
+Pool: Default
+When: 2003-04-23 17:08:18
+OK to run? (yes/mod/no):
+
+\end{verbatim}
+\normalsize
+
+Si maintenant j'entre {\bf yes}, le job est ex\'ecut\'e. Si je choisis {\bf mod},
+voici les otpions qui me sont propos\'ees :
+
+\footnotesize
+\begin{verbatim}
+Parameters to modify:
+ 1: Level
+ 2: Storage
+ 3: Job
+ 4: FileSet
+ 5: Client
+ 6: When
+ 7: Pool
+Select parameter to modify (1-7):
+
+\end{verbatim}
+\normalsize
+
+Vous pouvez, si vous le souhaitez, d\'emarrer un job plus tard, en utilisant le
+param\`etre {\bf When}. Pour cela, faites le choix {\bf mod}, puis s\'electionnez
+{\bf When} (no. 6) et enfin, saisissez l'heure et le jour de lancement
+d\'esir\'es au format AAAA-MM-JJ HH:MM:SS.
+
+\item [setdebug]
+ \index[general]{setdebug}
+ \index[general]{setdebug}
+ \index[general]{debuggage}
+ \index[general]{debuggage Win32}
+ \index[general]{Windows!debuggage}
+
+ Cette commande est utilis\'ee pour param\'etrer le niveau de d\'ebuggage de chaque
+ {\it daemon}. Voici la forme compl\`ete de cette commande.
+
+setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director |
+ storage=\lt{}storage-name\gt{} | all]
+
+ Si le param\`etre de tra\c{c}age est actif (trace=1), alors le {\it daemon} est
+ plac\'e en mode tra\c{c}age, ce qui signifie que toutes les informations de
+ d\'ebuggage sont envoy\'ees vers le fichier {\bf bacula.trace} dans le
+ r\'epertoire courant du {\it daemon}. En principe, ce n'est n\'ecessaire
+ que pour le d\'ebuggage des clients Win32 o\`u les informations ne peuvent
+ \^etre envoy\'ees vers un terminal ou redirig\'ees vers un fichier. en mode
+ tra\c{c}age, chaque message de d\'ebuggage est ajout\'e au fichier, que vous devez
+ supprimer explicitement lorsque vous avez fini.
+
+\item [show]
+ \index[general]{show}
+ \index[general]{show}
+ LA commande {\bf show} \'enum\`ere les directives des ressources du Director
+ telles qu'ells sont d\'efinies dans son fichier de configuration.
+ Cette commande est surtout utilis\'ee par les d\'eveloppeurs \`a des fins
+ de d\'ebuggage. LEs mots-clef suivants sont accept\'es :
+ catalogs, clients, counters, devices, directors,
+ filesets, jobs, messages, pools, schedules, storages, all, help.
+ Ne confondez pas cette commande ave la commande {\bf list}, qui affiche
+ quand \`a elle le contenu du catalogue.
+
+\item [sqlquery]
+ \index[general]{sqlquery}
+ La commande {\bf sqlquery} place le programme Console en mode de
+ requ\^etes SQL, dans lequel chaque ligne que vousq tapez est concat\'en\'ee
+ \`a la pr\'ec\'edents jusqu'\`a ce qu'un point-virgule (;) soit rencontr\'e. Le
+ point-virgule termine la commande qui est alors directement envoy\'e au moteur
+ de base de donn\'ee SQL. Lorsque le r\'esultat issu de la base de donn\'ee SQL est
+ affich\'e, la Console est pr\`ete \`a recevoir une nouvelle commande SQL.
+ Pour sortir du mode {\bf sqlquery} et reevenir \`a l'invite de la Console,
+ entrez un point (.).
+
+ Cette commande vous permet d'interroger directement le catalogue. Notez
+ que vous devriez savoir exactement ce que vous faites en utilisant cette
+ commande, car vous pouvez endommager s\'erieusement votre catalogue.
+ Consultez le paragraphe relatif \`a la commande {\bf query} qui offre un
+ moyen \`a la fois plus simple et plus sur de saisir des requ\^etes SQL.
+
+ En fonction du moteur de base de donn\'ees que vous utilisez (MySQL,
+ PostgreSQL ou SQLite), vous disposerez de commandes quelque peu diff\'erentes.
+ Pour plus de d\'etails, r\'ef\'erez-vous aux documentations de MySQL, PostgreSQL
+ ou SQLite.
+
+\item [status]
+ \index[general]{status}
+ Cette commande produit un \'etat des prochains jobs planifi\'es au cours des
+ 24 prochanes heures, ainsi que l'\'etat des jobs en cours d'ex\'ecution. Voici
+ la forme compl\`ete de cette commande :
+
+status [all | dir=\lt{}dir-name\gt{} | director |
+ client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} |
+ days=nnn]
+
+ Si vous entrez {\bf status dir}, la Console \'enum\`ere tous les jobs en cours
+ d'ex\'ecution, un r\'esum\'e des jobs planifi\'e pour ex\'ecution au cours des prochaines
+ 24 heures incluant le volume qui sera probablement utilis\'e, et donne la liste
+ des dix derniers jobs ex\'ecut\'es avec leurs \'etats. Gardez \`a l'esprit les deux
+ \'el\'ements suivants :
+ \begin{itemize}
+ \item L'obtention du volume n\'ecessite d'appliquer le m\^eme algorithme que
+ celui utilis\'e lors de l'ex\'ecution d'un job, ce qui peut r\'esulter en un \'elagage
+ de cartouche.
+ \item Le volume affich\'e est, au mieux, une bonne supposition. En effet le
+ volume effectivement utilis\'e peut \^etre diff\'erent en raison du temps \'ecoul\'e
+ entre le status et l'ex\'ecution du job, un autre job ayant pu, entre temps,
+ remplir compl\`etement la cartouche.
+ \end{itemize}
+
+ Dans la liste des jobs en cours d'ex\'ecutions, vous pouvez trouver ce type
+ d'informations :
+
+\footnotesize
+\begin{verbatim}
+2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution
+5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher
+ priority jobs to finish
+5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs
+5343 Full Rufus.2004-03-13_01.05.04 is running
+\end{verbatim}
+\normalsize
+
+ La liste ci-dessus indique que le job de JobId 5343 (Rufus) est en cours.
+ Le job de JobId 5348 (Minou) est en attente de la fin du job 5343
+ qui utilise la m\^eme ressource Storage, ce qui provoque le "waiting
+ on max Storage jobs". Le job de JobId 5349 a une priorit\'e inf\'erieure
+ \`a celle de tous les autres jobs, aussi, il est en attente de la fin de
+ jobs de priorit\'es sup\'erieures. Finalement, le job de jobId 2508 (MatouVerify)
+ est en attente ("waiting execution") car un seul job peut \^etre ex\'ecut\'e
+ en m\^eme temps.
+
+ Si vous faites un {\bf status dir}, Bacula affiche par d\'efaut les premi\`eres
+ occurrences de tous les jobs pr\'evus pour ex\'ecution aujourd'hui et demain.
+ Si vous voulez voir les jobs pr\'evus pour les trois prochains jours,
+ (Si, par exemple vendredi, vous voulez voir les premi\`eres occurrences
+ des cartouches \`a utiliser vendredi, samedi, dimanche et lundi), vous
+ pouvez ajouter l'option {\bf days=3}. Notez, {\bf days=0} montre les
+ premi\`eres occurrences des jobs planifi\'es pour \^etre ex\'ecut\'es aujourd'hui
+ seulement. Si vous avez plusieurs ex\'ecutions planifi\'ees, pour chaque
+ job, seule la premi\`ere occurrence sera affich\'e pour la p\'eriode sp\'ecifi\'ee.
+
+ Si votre job para\^it bloqu\'e, vous pouvez avoir une id\'ee g\'en\'erale du probl\`eme
+ en utilisant {\bf status dir}, et obtenir une information plus sp\'ecifique
+ avec {\bf status storage=xxx}. Par exemple, si j'utilise cette derni\`ere
+ commande sur un syst\`eme inoccup\'e, j'obtiens :
+
+\footnotesize
+\begin{verbatim}
+status storage=File
+Connecting to Storage daemon File at 192.168.68.112:8103
+
+rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz)
+Daemon started 26-Mar-06 11:06, 0 Jobs run since started.
+
+Running Jobs:
+No Jobs running.
+====
+
+Jobs waiting to reserve a drive:
+====
+
+Terminated Jobs:
+ JobId Level Files Bytes Status Finished Name
+======================================================================
+ 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave
+====
+
+Device status:
+utochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002"
+Pool="*unknown*"
+ Slot 2 is loaded in drive 0.
+ Total Bytes Read=0 Blocks Read=0 Bytes/block=0
+ Positioned at File=0 Block=0
+Device "Dummy" is not open or does not exist.
+No DEVICE structure.
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+====
+
+In Use Volume status:
+====
+\end{verbatim}
+\normalsize
+
+Ce qui r\'ev\`ele qu'aucun job n'est en cours d'ex\'ecution, et qu'aucun des
+p\'eriph\'eriques n'est en cours d'utilisation. Si je d\'emonte la librairie
+({\bf unmount}), qui ne sera plus utilis\'ee dans cet exemple, et que je lance
+un job qui utilise le stockage File, le job se bloque. Si je demande \`a
+nouveau {\bf status storage=xxx}, j'obtiens :
+
+\footnotesize
+\begin{verbatim}
+status storage=File
+...
+Device status:
+Autochanger "DDS-4-changer" with devices:
+ "DDS-4" (/dev/nst0)
+Device "DDS-4" (/dev/nst0) is not open.
+ Device is BLOCKED. User unmounted.
+ Drive 0 is not loaded.
+Device "Dummy" is not open or does not exist.
+No DEVICE structure.
+
+Device "DVD-Writer" (/dev/hdc) is not open.
+Device "File" (/tmp) is not open.
+ Device is BLOCKED waiting for media.
+====
+...
+\end{verbatim}
+\normalsize
+
+Il devrait maintenant \^etre clair que si un job n\'ecessitant la librairie
+est ex\'ecut\'e, il bloquera en raison du d\'emontage de cette derni\`ere par
+l'utilisateur. Mais le probl\`eme pour le job que j'ai lanc\'e avec le
+p\'eriph\'erique "File" est que le p\'eriph\'erique est bloqu\'e en attente
+d'un media : Bacula a besoin que vous \'etiquetiez un volume.
+
+\item [unmount]
+ \index[general]{unmount}
+ Cette commande sert \`a ordonner au Storage Daemon de d\'emonter le p\'eriph\'erique
+ sp\'ecifi\'e. Les formes de cette commande sont les m\^emes que celle de la commande
+ mount :
+
+\footnotesize
+\begin{verbatim}
+unmount storage=<storage-name>
+
+unmount [ jobid=<id> | job=<job-name> ]
+\end{verbatim}
+\normalsize
+
+\label{UpdateCommand}
+\item [update]
+ \index[general]{update}
+ Cette commande met \`a jour le catalogue, que ce soit pour un pool sp\'ecifique,
+ un enregistrement de volume, ou les slots d'une librairie dot\'ee d'un lecteur
+ de codes barres. Dans le cas de la mise \`a jour d'un enregistrement de pool,
+ la nouvelle configuration est automatiquement r\'ecup\'er\'ee de la ressource
+ correspondante du fichier de configuration du Director. Cette commande peut
+ notamment servir \`a augmenter le nombre maxial de volumes dans un pool. Les
+ principaux mots-clef suivants peuvent \^etre utilis\'es :
+
+\footnotesize
+\begin{verbatim}
+ media, volume, pool, slots
+\end{verbatim}
+\normalsize
+
+Dans le cas de la mise \`a jour d'un volume, vous serez interrog\'e sur le
+param\`etre que vous voulez modifier. Voici ces param\`etres :
+
+\footnotesize
+\begin{verbatim}
+
+ Volume Status
+ Volume Retention Period
+ Volume Use Duration
+ Maximum Volume Jobs
+ Maximum Volume Files
+ Maximum Volume Bytes
+ Recycle Flag
+ Slot
+ InChanger Flag
+ Pool
+ Volume Files
+ Volume from Pool
+ All Volumes from Pool
+
+\end{verbatim}
+\normalsize
+
+ Pour le param\`etre slot, {\bf update slots}, Bacula obtient une liste
+ de tous les slots et de leurs codes barres du Storage Daemon,
+ pour chaque code barres trouv\'e, le slot est mis \`a jour dans
+ l'enregistrement Media du catalogue. C'est tr\`es pratique si vous
+ d\'eplacez des cartouches dans la librairie, ou si vous changez des
+ magasins de cartouches. Dans la foul\'ee, le drapeau InChanger est
+ aussi mis \`a jour.Ceci permet \`a BAcula de savoir quels cartouches sont
+ effectivement dans la librairie.
+
+ Si vous n'avez pas de lecteur de codes barres, vous pouvez faire la
+ m\^eme chose depuis la version 1.33 gr\^ace \`a la commande {\bf update slots scan}.
+ Le mot-clef {\bf scan} ordonne \`a Bacula de monter physiquement chaque
+ cartouche afin de lire son VolumeName.
+
+ Pour le param\`etre Pool, {\bf update pool}, Bacula d\'eplace le volume de
+ son pool courant vers le pool sp\'ecifi\'e.
+
+ Pour les parm\`etres {\bf Volume from Pool} et {\bf All Volumes from Pool},
+ les valeurs suivantes sont mises \`a jour depuis l'enregistrement
+ de pool : Recycle, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles,
+ and MaxVolBytes.
+
+ Voici la forme compl\`ete de la commande {\bf update} :
+
+\footnotesize
+\begin{verbatim}
+ update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd
+ VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no
+ slot=nnn enabled=n
+
+\end{verbatim}
+\normalsize
+
+\item [use]
+ \index[general]{use}
+ Cette commande vous perment de pr\'eciser le catalogue que vous voulez utiliser.
+ En principe, vous n'utiliserez qu'un seul catalogue, aussi vous n'aurez pas
+ besoin de faire ce choix. Sinon, utilisez cette commande pour passer de l'un
+ de vos catalogues \`a l'autre.
+
+use \lt{}database-name\gt{}
+
+\item [var]
+ \label{var}
+ \index[general]{var name}
+ Cette commande prend une cha\^ine \'eventuellement encadr\'ee de guillemets et effectue
+ l'expansion des variables comme elle serait effectu\'ee au niveau de la
+ directive {\bf LabelFormat}. Ainsi, vous pouvez tester vos cha\^ines
+ de format d'\'etiquetage. La diff\'erence entre la commande {\bf var} et le
+ processus effectif est que pour la premi\`ere, aucun job n'est en cours,
+ aussi des valeurs factices sont utilis\'ees au lieu des variables sp\'ecifiques
+ aux jobs. Cela vous permet cependant de vous faire une bonne id\'ee de ce qui
+ se passerait dans le cas r\'eel.
+
+\item [version]
+ \index[general]{version}
+ Cette commande affiche la version du Director.
+
+\item [quit]
+ \index[general]{quit}
+ Cette commande stoppe le programme Console. Celui-ci envoie la requ\^ete
+ {\bf quit} au Director et attend son accus\'e de r\'eception. Si le Director
+ est occup\'e, cela peut prendre un certain temps. Vous pouvez quitter
+ imm\'ediatement en utilisant la variante {\bf .quit} ({\bf quit} pr\'ec\'ed\'ee
+ d'un point).
+
+\item [query]
+ \index[general]{query}
+ Cette commande lit une requ\^ete SQL pr\'ed\'efinie dans le fichier de requ\^etes
+ (le nom et l'emplacement de ce fichier sont d\'efinis par la directive
+ QueryFile du fichier de configuration du Director). Il vous est alors
+ demand\'e de s\'electionner une requ\^ete du fichier, et \'eventuellement de
+ saisir un ou plusieurs param\`etres. La requ\^ete est alors soumise au
+ moteur de base de donn\'ees.
+
+Les requ\^etes suivantes sont actuellement (version 1.24) disponibles :
+
+\footnotesize
+\begin{verbatim}
+Available queries:
+ 1: List Job totals:
+ 2: List where a file is saved:
+ 3: List where the most recent copies of a file are saved:
+ 4: List total files/bytes by Job:
+ 5: List total files/bytes by Volume:
+ 6: List last 20 Full Backups for a Client:
+ 7: List Volumes used by selected JobId:
+ 8: List Volumes to Restore All Files:
+ 9: List where a File is saved:
+Choose a query (1-9):
+
+\end{verbatim}
+\normalsize
+
+\item [exit]
+ \index[general]{exit}
+ Cette commande termine le programme Console.
+
+\item [wait]
+ \index[general]{wait}
+ Cette commande place le Director en pause jusqu'\`a ce qu'il n'y ait plus
+ aucun job en ex\'ecution. Cette commande est utile dans des situation
+ d'utilisation automatis\'ee par scripts telles que les tests de r\'egression
+ o\`u vous voulez d\'emarrer un job, et attendre qu'il se termine avant de
+ poursuivre. Cette commande admet les options suivantes :
+
+\footnotesize
+\begin{verbatim}
+ wait [jobid=nn] [jobuid=unique id] [job=job name]
+\end{verbatim}
+\normalsize
+
+\end{description}
+
+\label{dotcommands}
+
+\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point}
+\index[general]{Commands!sp\'eciales, pr\'ec\'ed\'ees d'un point}
+\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point}
+\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point}
+
+Voici une liste de commandes pr\'efix\'ees d'un point (.). Elles ont pour vocation
+d'\^etre utilis\'ees soit dans des programmes {\it batch}, soit par des interfaces
+graphiques. Elles ne sont, en principe, pas utilis\'ees en mode interactif.
+Une fois que le d\'eveloppement d'interfaces graphiques aura d\'emarr\'e, cette liste
+s'accro\^itra consid\'erablement.
+
+\footnotesize
+\begin{verbatim}
+.backups job=xxx list backups for specified job
+.defaults client=xxx fileset=yyy list defaults for specified client
+.die cause the Director to segment fault (for debugging)
+.dir when in tree mode prints the equivalent to the dir command,
+ but with fields separated by commas rather than spaces.
+.jobs list all job names
+.levels list all levels
+.filesets list all fileset names
+.clients list all client names
+.pools list all pool names
+.types list job types
+.msgs return any queued messages
+.messages get quick messages
+.help help command output
+.quit quit
+.status get status output
+.exit quit
+\end{verbatim}
+\normalsize
+
+\label{atcommands}
+
+\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)}
+\index[general]{Commandes!sp\'eciales arobase @}
+\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)}
+\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)}
+
+Normalement, toutes les commandes saisies dans la Console sont imm\'ediatement
+transmises au Director, qui peut r\'esider sur une autre machine, afin d'y \^etre
+ex\'ecut\'ees. Il existe cependant quelques commandes, toutes pr\'ec\'ed\'ees du
+caract\`ere arobase (@), qui ne sont pas envoy\'ees au Director, mais
+directement interpr\'et\'ees par la Console. Notez que seule la Console
+tty impl\'emente ces commandes, et non la Console GNOME. En voici la liste :
+
+\begin{description}
+
+\item [@input \lt{}nom-de-fichier\gt{}]
+ \index[general]{@input \lt{}nom-de-fichier\gt{}}
+ Lit et ex\'ecute les commandes consign\'ees dans le fichier sp\'ecifi\'e.
+
+\item [@output \lt{}nom-de-fichier\gt{} w/a]
+ \index[general]{@output \lt{}nom-de-fichier\gt{} w/a}
+ Envoit l'ensemble des retours de la Console vers le fichier sp\'ecifi\'e,
+ avec \'ecrasement si l'option {\bf w} est sp\'ecifi\'ee, ou ajout \`a la suite si l'option
+ {\bf a} est sp\'ecifi\'ee. Pour rediriger la sortie vers le terminal, entrez
+ simplement {\bf output} sans sp\'ecifier de nom de fichier.
+ ATTENTION : prenez garde de ne pas \'ecraser un fichier valide.
+ Voici un exemple typique lors d'un test de r\'egression :
+
+\footnotesize
+\begin{verbatim}
+ @output /dev/null
+ commands ...
+ @output
+
+\end{verbatim}
+\normalsize
+
+\item [@tee \lt{}nom-de-fichier\gt{} w/a]
+ \index[general]{@tee \lt{}nom-de-fichier\gt{} w/a}
+ Comme la commande pr\'ec\'edente avec envoi simultan\'e vers le terminal. Pour
+ sortir de ce mode, vous pouvez utiliser {\bf @tee} ou {\bf @output} sans
+ sp\'ecifier de nom de fichier.
+
+\item [@sleep \lt{}seconds\gt{}]
+ \index[general]{@sleep \lt{}seconds\gt{}}
+ Met en sommeil pour une dur\'ee du nombre de secondes sp\'ecifi\'e.
+
+\item [@time]
+ \index[general]{@time}
+ Affiche la date et l'heure courantes.
+
+\item [@version]
+ \index[general]{@version}
+ Affiche la version de la Console.
+
+\item [@quit]
+ \index[general]{@quit}
+ Quitte.
+
+\item [@exit]
+ \index[general]{@exit}
+ Quitte.
+
+\item [@\# n-importe-quoi]
+ \index[general]{n-importe-quoi}
+ Commentaire.
+\end{description}
+
+\label{scripting}
+
+\section{Ex\'ecuter la Console depuis un script shell}
+\index[general]{Script!Ex\'ecuter la Console depuis un script shell}
+\index[general]{Ex\'ecuter la Console depuis un script shell}
+\addcontentsline{toc}{section}{Ex\'ecuter la Console depuis un script shell}
+Vous pouvez automatiser de nombreuses t\^aches effectu\'ees \`a la Console, en les
+ex\'ecutant dans un script shell. Par exemple, si vous avez cr\'e\'e un fichier
+contenant ceci :
+
+\footnotesize
+\begin{verbatim}
+ ./bconsole -c ./bconsole.conf <<END_OF_DATA
+ unmount storage=DDS-4
+ quit
+ END_OF_DATA
+\end{verbatim}
+\normalsize
+
+A l'ex\'ecution de ce fichier, le p\'eriph\'erique DDS-4 est d\'emont\'e.
+Vous pouvez, si vous le souhaitez, ex\'ecuter cette t\^ache lors d'un job avec
+les directives {\bf RunBeforeJob} ou {\bf RunAfterJob}.
+
+Il est aussi possible d'ex\'ecuter la Console \`a partir de l'entr\'ee d'un
+fichier contenant les commandes comme suit :
+
+\footnotesize
+\begin{verbatim}
+./bconsole -c ./bconsole.conf <filename
+\end{verbatim}
+\normalsize
+
+o\`u le fichier nomm\'e {\bf filename} contient un ensemble quelconque de
+commandes de la Console.
+
+Voici un exemple r\'eel, issu des tests de r\'egression de Bacula. Il
+\'etiquette un volume (sur disque) ex\'ecute une sauvegarde puis une
+restauration des fichiers sauvegard\'es.
+
+\footnotesize
+\begin{verbatim}
+bin/bconsole -c bin/bconsole.conf <<END_OF_DATA
+@output /dev/null
+messages
+@output /tmp/log1.out
+label volume=TestVolume001
+run job=Client1 yes
+wait
+messages
+@#
+@# now do a restore
+@#
+@output /tmp/log2.out
+restore current all
+yes
+wait
+messages
+@output
+quit
+END_OF_DATA
+\end{verbatim}
+\normalsize
+
+Les donn\'ees issues de la sauvegarde sont envoy\'ees vers /tmp/log1.out et
+celles de la restaurations vers /tmp/log2.out. Pour v\'erifier que les
+op\'erations se sont d\'eroul\'ees correctement, les fichiers de sorties
+sont contr\^ol\'es avec :
+
+\footnotesize
+\begin{verbatim}
+grep "^Termination: *Backup OK" /tmp/log1.out
+backupstat=$?
+grep "^Termination: *Restore OK" /tmp/log2.out
+restorestat=$?
+\end{verbatim}
+\normalsize
+
+\section{Ajouter des volumes \`a un pool}
+\index[general]{Ajouter des volumes \`a un pool}
+\index[general]{Pool!Ajouter des volumes \`a un}
+\addcontentsline{toc}{section}{Ajouter des volumes \`a un pool}
+
+Si vous avez utilis\'e la commande {\bf label} pour \'etiqueter un volume, alors
+celui-ci est automatiquement ajout\'e au pool, et vous n'avez pas besoin de le faire
+manuellement.
+
+Une alternative consiste \`a ajouter plusieurs volumes \`a un pool sans les
+\'etiqueter pr\'ealablement. Vous devrez alors les \'etiqueter plus tard, lorsque Bacula
+en aura besoin.
+
+Avant d'ajouter un volume \`a un pool, vous devez conna\^itre les informations
+suivantes :
+
+\begin{enumerate}
+\item Le nom du pool (normalement, "Default") ;
+\item Le type de media tel qu'il est sp\'ecifi\'e dans la ressource Storage
+du fichier de configuration du Director (par exemple, "DLT8000") ;
+\item Le nombre de volumes que vous voulez cr\'eer, et leurs noms.
+The number and names of the Volumes you wish to create.
+\end{enumerate}
+
+Par exemple, pour ajouter un media \`a un pool, vous utiliseriez les commandes
+suivantes dans la Console :
+
+\footnotesize
+\begin{verbatim}
+*add
+Enter name of Pool to add Volumes to: Default
+Enter the Media Type: DLT8000
+Enter number of Media volumes to create. Max=1000: 10
+Enter base volume name: Save
+Enter the starting number: 1
+10 Volumes created in pool Default
+*
+\end{verbatim}
+\normalsize
+
+Pour voir ce que vous avez ajout\'e, tapez :
+
+\footnotesize
+\begin{verbatim}
+*list media pool=Default
++-------+----------+---------+---------+-------+------------------+
+| MedId | VolumeNa | MediaTyp| VolStat | Bytes | LastWritten |
++-------+----------+---------+---------+-------+------------------+
+| 11 | Save0001 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 12 | Save0002 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 13 | Save0003 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 14 | Save0004 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 15 | Save0005 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 16 | Save0006 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 17 | Save0007 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 18 | Save0008 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 19 | Save0009 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
+| 20 | Save0010 | DLT8000 | Append | 0 | 0000-00-00 00:00 |
++-------+----------+---------+---------+-------+------------------+
+*
+\end{verbatim}
+\normalsize
+
+Notez que la Console a automatiquement ajout\'e un num\'ero au nom de volume de
+base que vous avez sp\'ecifi\'e ("Save" dans ce cas). Si vous ne souhaitez pas
+ce comportement, r\'epondez simplement 0 (z\'ero) \`a la queston "Enter number
+of Media volumes to create . Max=1000:" et un seul volume sera cr\'e\'e avec
+le nom exact que vous avez sp\'ecifi\'e.
projects / bacula / docs / commitdiff