--- /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.
-
-%---------------------------------------------------------------------
projects / bacula / docs / commitdiff