From: Kern Sibbald Date: Fri, 5 Mar 2010 13:59:40 +0000 (+0100) Subject: Setup es/console for translation X-Git-Tag: Release-5.2.1~145 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=56c967b51aa26916559fbc22a361d5d2944898c7;p=bacula%2Fdocs Setup es/console for translation --- diff --git a/docs/manuals/es/console/base/bconsole.tex b/docs/manuals/es/console/base/bconsole.tex new file mode 100644 index 00000000..f090374b --- /dev/null +++ b/docs/manuals/es/console/base/bconsole.tex @@ -0,0 +1,1642 @@ +%% +%% + +\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 set configuration file to file + -dnn set debug level to nn + -n no conio + -s no signals + -u set command execution timeout to 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} + [=] [=] ... +\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= +\end{verbatim} + + or + +\begin{verbatim} +delete volume= pool= or +\end{verbatim} + +\begin{verbatim} +delete JobId= JobId= ... 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= listing client= accurate= + fileset= level= +\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= volume= + 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= (list jobid id) + + list ujobid= (list job with unique name) + + list job= (list all jobs with "job-name") + + list jobname= (same as above) + + In the above, you can add "limit=nn" to limit the output to + nn jobs. + + list jobmedia + + list jobmedia jobid= + + list jobmedia job= + + list files jobid= + + list files job= + + list pools + + list clients + + list jobtotals + + list volumes + + list volumes jobid= + + list volumes pool= + + list volumes job= + + list volume= + + list nextvolume job= + + list nextvol job= + + list nextvol job= 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= [ drive= ] + +unmount [ jobid= | job= ] +\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 < set configuration file to file + -dnn set debug level to nn + -n no conio + -s no signals + -u set command execution timeout to 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} + [=] [=] ... +\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= +\end{verbatim} + + or + +\begin{verbatim} +delete volume= pool= or +\end{verbatim} + +\begin{verbatim} +delete JobId= JobId= ... 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= listing client= accurate= + fileset= level= +\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= volume= + 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= (list jobid id) + + list ujobid= (list job with unique name) + + list job= (list all jobs with "job-name") + + list jobname= (same as above) + + In the above, you can add "limit=nn" to limit the output to + nn jobs. + + list jobmedia + + list jobmedia jobid= + + list jobmedia job= + + list files jobid= + + list files job= + + list pools + + list clients + + list jobtotals + + list volumes + + list volumes jobid= + + list volumes pool= + + list volumes job= + + list volume= + + list nextvolume job= + + list nextvol job= + + list nextvol job= 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= [ drive= ] + +unmount [ jobid= | job= ] +\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 < set configuration file to file - -dnn set debug level to nn - -n no conio - -s no signals - -u set command execution timeout to 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} - [=] [=] ... -\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= -\end{verbatim} - - or - -\begin{verbatim} -delete volume= pool= or -\end{verbatim} - -\begin{verbatim} -delete JobId= JobId= ... 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= listing client= accurate= - fileset= level= -\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= volume= - 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= (list jobid id) - - list ujobid= (list job with unique name) - - list job= (list all jobs with "job-name") - - list jobname= (same as above) - - In the above, you can add "limit=nn" to limit the output to - nn jobs. - - list jobmedia - - list jobmedia jobid= - - list jobmedia job= - - list files jobid= - - list files job= - - list pools - - list clients - - list jobtotals - - list volumes - - list volumes jobid= - - list volumes pool= - - list volumes job= - - list volume= - - list nextvolume job= - - list nextvol job= - - list nextvol job= 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= [ drive= ] - -unmount [ jobid= | job= ] -\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 <