From: Kern Sibbald Date: Wed, 3 Mar 2010 17:35:40 +0000 (+0100) Subject: Setup fr/console X-Git-Tag: Release-5.2.1~149 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=ecaab32958a72d6db9359b59a6373a051744ef5b;p=bacula%2Fdocs Setup fr/console --- diff --git a/docs/manuals/en/console/console.tex b/docs/manuals/en/console/console.tex index 95f9c659..beae121e 100644 --- a/docs/manuals/en/console/console.tex +++ b/docs/manuals/en/console/console.tex @@ -67,7 +67,6 @@ \clearpage \include{bconsole} -\include{gui} \include{fdl} diff --git a/docs/manuals/fr/console/base/bconsole.tex b/docs/manuals/fr/console/base/bconsole.tex new file mode 100644 index 00000000..f090374b --- /dev/null +++ b/docs/manuals/fr/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 < set configuration file to file + -dnn set debug level to nn + -n no conio + -s no signals + -t test - read configuration and exit + -? print this message. +\end{verbatim} +\normalsize + +Apr\`es son d\'emarrage, la Console est en attente de vos commandes, ce qui +est indiqu\'e par une ast\'erisque (*) (ce n'est pas le cas dans la version +GNOME o\`u vous saisissez vos commandes dans la boite texte en bas de l'\'ecran). +Vous pouvez, pour toutes les commandes, vous contenter d'entrer le nom de la +commande, la Console se chargera de vous demander les arguments n\'ecessaires, +mais dans la plupart des cas, vous pouvez entrer les commandes suivies de leurs +arguments. Le format g\'en\'eral est : + +\footnotesize +\begin{verbatim} + [=] [=] ... +\end{verbatim} +\normalsize + +O\`u {\bf command} est l'une des commandes \'enum\'er\'ees ci-dessous, {\bf keyword} +est l'un des mots-clef \'enum\'er\'es ci-dessous (usuellement suivi d'un argument), +et {\bf argument} est la valeur du mot-clef. La commande peut \^etre abr\'eg\'ee +jusqu'\`a sa plus courte abr\'eviation unique. Si deux commandes commencent +par les m\^emes lettres, c'est celle qui appara\^it en t\^ete dans la liste fournie +par la commande {\bf help} qui sera s\'electionn\'ee si votre abr\'eviation est +ambig\"ue. Aucun des mots-clef suivant la commande ne peut \^etre abr\'eg\'e. + +Par exemple : + +\footnotesize +\begin{verbatim} +list files jobid=23 +\end{verbatim} +\normalsize + +\'enum\`ere les fichiers sauvegard\'es par le job de JobId 23. + +Cette autre commande : + +\footnotesize +\begin{verbatim} +show pools +\end{verbatim} +\normalsize + +affiche toutes les ressources Pool. + +\section{Quitter la Console} +\index[general]{Console!Quitter} +\index[general]{Quitter la Console} +\index[general]{Console!Quitter} +\index[general]{Quitter la Console} +\addcontentsline{toc}{section}{Quitter la Console} + +Normalement, le programme Console se termine si vous saisissez {\bf quit} +ou {\bf exit}. Cependant, il il attend jusq"\`a ce que le Director ait pris +en compte la commande, ce qui peut prendre du temps si ce dernier est d\'ej\`a +occup\'e \`a une t\^ache longue (par exemple, un \'elagage du catalogue). Si vous voulez +quitter la Console imm\'ediatement, utilisez la commande {\bf .quit}. + +Il n'existe actuellement aucun moyen d'interrompre une commande de la Console +une fois lanc\'ee (Ctrl-C ne marche pas). En revanche, \`a l'invite d'une commande +vous demandant de choisir parmi plusieurs possibilit\'es, vous pouvez annuler +la commande en entrant un point ({\bf .}), vous serez dans la plupart des cas +ramen\'e \`a l'invite principal, ou \`a l'invite pr\'ec\'edente, dans le cas de choix +imbriqu\'es. En quelques endroits, comme celui o\`u l'on vous demande un +nom de volume, le point sera pris pour la r\'eponse (Bacula pensera que vous +voulez nommer votre volume "."). Dans cette situation, vous serez la plupart +du temps en mesure d'annuler \`a l'invite suivante. + +\label{keywords} +\section{Index des mots-clef de la Console} +\index[general]{Mots-clef!Index Console} +\index[general]{Index des mots-clef de la Console} +\index[general]{Mots-clef!Index Console} +\index[general]{Index des mots-clef de la Console} +\addcontentsline{toc}{section}{Index des mots-clef de la Console} +Sauf sp\'ecification contraire, chacun des mots-clef suivant admet un argument, +qui est sp\'ecifi\'e apr\`es le mot-clef suivi du signe \'egale. Par exemple : + +\begin{verbatim} +jobid=536 +\end{verbatim} + +Notez que cette liste est probablement incompl\`ete, car le processus de cr\'eation +est toujours en cours. Il se peut aussi qu'elle ne soit pas dans l'ordre +alphab\'etique. + +\begin{description} +\item [restart] + Permis dans la commande {\it python}, provoque le red\'emarrage de + l'interpr\'eteur Python. Ne prend pas d'arguments. +\item [all] + Permis dans les commandes {\it status} et {\it show} pour sp\'ecifier, respectivement, tous les + composants ou toutes les ressources. +\item [before] + Utilis\'e dans la commande {\it restore}. +\item [bootstrap] + Utilis\'e dans la commande {\it restore}. +\item [catalog] + Permis dans la commande {\it use} pour sp\'ecifier le nom de catalogue \`a utiliser. +\item [catalogs] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments +\item [client | fd] +\item [clients] + Utilis\'e dans les commandes {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [counters] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [current] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [days] + Utilisé pour définir le nombre de jours que la commande "list nextvol" doit + prendre en compte dans son évaluation des prochains jobs à exécuter. + Le mot-clef "day" peut aussi être utilisé avec la commande "status dir" + afin qu'elle affiche les jobs planifiés pour la période spécifiés. +\item [devices] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [dir | director] +\item [directors] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [directory] + Utilis\'e dans la commande {\it restore}. Son argument spécifie + le répertoire à restaurer. +\item [enabled] + Ce mot-clef peut être utilisé avec la commande {\bf update volume} et admet + l'un des arguments suivants : yes, true, no, false, archived, 0, 1, 2, où + 0 correspond à "no" ou "false", 1 à "yes" ou "true" et 2 à "archived". Les volumes + avec le statut "archived" ne seront pas utilisés, pas plus que ne seront élagués leurs + enregistrements dans le catalogue. Les volumes qui n'ont pas le statut "enabled" + ne seront pas utilisés pour des sauvegardes ou des restaurations. +\item [done] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [file] + Utilis\'e dans la commande {\it restore}. +\item [files] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [fileset] +\item [filesets] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [help] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [jobs] + Utilis\'e dans les commandes {\it show}, {\it list} et {\it llist}. Ne prend pas d'arguments. +\item [jobmedia] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [jobtotals] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [jobid] + Le JobId est le num\'ero de job qui est affich\'e dans le rapport de job. + C'est l'index du catalogue pour le job donn\'e. Bien qu'il soit unique + pour tous les jobs existant dans le catalogue, le m\^eme JobId peut + \^etre r\'eutilis\'e une fois qu'un job a \'et\'e supprim\'e du catalogue. + Vous d\'esignerez certainement les jobs sp\'ecifiques par leur JobId. +\item [job | jobname] + Le mot-clef Job ou Jobname se r\'ef\`ere au nom que vous avez sp\'ecifi\'e + dans la ressource Job, et donc peut d\'esigner plusieurs jobs effectu\'es. + C'est particuli\`erement utile lorsque vous voulez la liste des jobs + execut\'es portant un nom particulier. +\item [level] +\item [listing] + Permis dans la commande {\it estimate}. Ne prend pas d'arguments. +\item [limit] +\item [messages] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [media] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [nextvol | nextvolume] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [on] + Ne prend pas d'arguments. +\item [off] + Ne prend pas d'arguments. +\item [pool] +\item [pools] + Utilis\'e dans les commandes, {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [select] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [storages] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [schedules] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [sd | store | storage] +\item [ujobid] + L'ujobid est un identificateur unique de job qui est affich\'e dans + le rapport du job. Actuellement, il consiste en le nom du job + (celui de la directive Name de ce job) suffix\'e de la date et de + l'heure d'ex\'ecution du job. Ce mot-clef est utile si vous voulez + identifier compl\`etement l'instance du job ex\'ecut\'e. +\item [volume] +\item [volumes] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [where] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [yes] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\end{description} + +\label{list} +\section{Index des commandes de la Console} +\index[general]{Commandes!Index des commandes de la Console} +\index[general]{Index des commandes de la Console} +\index[general]{Commandes!Index des commandes de la Console} +\index[general]{Index des commandes de la Console} +\addcontentsline{toc}{section}{Index des commandes de la Console} + +Les commandes suivantes sont actuellement impl\'ement\'ees : + +\begin{description} +\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{} + jobid=\lt{}JobId\gt{}]} ] + \index[general]{add} +Cette commande sert \`a ajouter des volumes \`a un pool existant. Les noms des +volumes saisis sont plac\'es dans le catalogue et deviennent ainsi disponibles +pour les sauvegardes. Normalement, on pr\'ef\`er utiliser la commande {\bf label} +qui remplit les m\^emes fonctions en plus d'apposer une \'etiquette logicielle +(label) sur les bandes, par opposition \`a {\bf add} qui se contente de +r\'ef\'erencer le volume dans le catalogue. Ainsi, si vous utilisez {\bf add}, +le volume doit pr\'eexister et \^etre d\'ej\`a \'etiquet\'e. Cette commande peut +cependant \^etre utile si vous voulez ajouter plusieurs cartouches dans un +pool en ne les \'etiquettant que plus tard. Elle peut aussi se r\'ev\'eler utile +si vous importez des cartouches provenant d'un autre site. Consultez le +paragraphe sur la commande {\bf label} pour conna\^itre la liste des +caract\`eres autoris\'es dans un nom de volume. + +\item [autodisplay on/off] + \index[general]{autodisplay on/off} + Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou + d\'esactive l'affichage automatique des messages. La valeur par d\'efaut dans + la Console est {\bf off}, ce qui signifie que les messages en attente + vous sont notifi\'es, mais qu'ils ne sont pas automatiquement affich\'es. + La valeur par d\'efaut pour la console GNOME est {\bf on}, ainsi les + messages sont affich\'es lorqu'ils sont re\c{c}us (habituellement dans les 5 secondes + apr\`es qu'ils aient \'et\'e g\'en\'er\'es). + + Lorsque l'affichage automatique est d\'esactiv\'e, vous devez explicitement + en demander l'affichage avec la commande {\bf messages}. + +\item [automount on/off] + \index[general]{automount on/off} + Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou + d\'esactive le montage automatique de la cartouche apr\`es une commande {\bf label}. + La valeur par d\'efaut est {\bf on}. Si le montage automatique est d\'esactiv\'e, + vous devez explicitement monter la cartouche apr\`es avoir utilis\'e {\bf label} + pour pouvoir \'ecrire dessus. + +\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}] + \index[general]{cancel jobid} + Cette commande sert \`a supprimer un job et admet les arguments {\bf jobid=nnn} + ou {\bf job=xxx} o\`u nnn est \`a remplacer par le JobId et xxx par le nom de + job. Si vous lancez cette commande sans arguments, la Console vous propose + de choisir parmi les jobs actifs celui \`a supprimer. + + Une fois qu'un job est marqu\'e "A supprimer", il peut se passer quelques instants + (en g\'en\'eral, moins d'une minute) avant qu'il se termine, en fonction des + op\'erations en cours. + +\item [{ create [pool=\lt{}pool-name\gt{}]}] + \index[general]{create pool} + Cette commande sert \`a cr\'eer un enregistrement Pool dans le catalogue + selon les ressources Pool d\'efinis dans le fichier de configuration + du Director. En un sens, cette commande se content de transf\'erer + l'information depuis la ressource Pool dans le fichier de configuration + vers le catalogue. En principe, cete commande est automatiquement + ex\'ecut\'ee au lancement du Director, pourvu que le pool soit r\'ef\'erenc\'e + dans une ressource Job. Si vous utilisez cette commande sur un pool + existant, elle met \`a jour le catalogue en foction des informations de + la ressource Pool. Apr\`es avoir cr\'e\'e un pool, vous uiliserez + probablement la commande {\bf label} pour \'etiqueter un ou plusieurs + volumes et enregistrer leurs noms dans le catalogue. + + Si, au lancement d'un job, Bacula d\'etermine qu'il n'y a pas de pool + enregistr\'e dans le catalogue, mais qu'il existe une ressource Pool pour + le pool appropri\'e, alors il le cr\'e\'e pour vous. Si vous voulez le voir + appara\^itre imm\'ediatement dans le catalogue, utilisez cette commande pour + forcer sa cr\'eation imm\'ediate. + +\item [{ delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job + jobid=\lt{}id\gt{}]}] + \index[general]{delete} + Cette commande s'utilise pour supprimer un volume, un pool ou un job + du catalogue, ainsi que tous les enregistrements du catalogue qui leur + sont associ\'es. Cette commande op\`ere exclusivement sur le catalogue + et n'a aucune r\'epercussion sur les donn\'ees \'ecrites sur les cartouches. + Elle peut \^etre dangereuse, et nous vous recommandons fortement de ne + pas l'utiliser si vous ne savez pas exactement ce que vous faites. + + Voici la forme compl\`ete de cette commande : + +\begin{verbatim} +delete pool=\lt{}pool-name\gt{} +\end{verbatim} + + supprime un pool du catalogue. + +\begin{verbatim} +delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{} +\end{verbatim} + + supprime du catalogue un volume du pool sp\'ecifi\'e. + +\begin{verbatim} +delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ... +\end{verbatim} + + supprime du catalogue le job sp\'ecifi\'e. + +\begin{verbatim} +delete Job JobId=n,m,o-r,t ... +\end{verbatim} + + supprime les job de JobIds m,n,o,p,q,r et t (o\`u m,n,... sont, bien sur, des + nombres). Ainsi, la commande "delete jobid" accepte les listes et les plages + de jobids. + +\item [disable job\lt{}job-name\gt{}] + \index[general]{enable} + Cette commande vous permet de d\'esactiver un job normalement planifi\'e + pour ex\'ecution. Le job peut avoir \'et\'e pr\'ealablement activ\'e par la + directive {\bf Enabled} dans la ressource Job, ou avec la commande + {\bf enable} dans la Console. Au prochain d\'emarrage du Director, ou + si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera + r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut + est enabled). + +\item [enable job\lt{}job-name\gt{}] + \index[general]{enable} + Cette commande vous permet de d'activer un job planifi\'e + pour ex\'ecution automatique. Le job peut avoir \'et\'e pr\'ealablement d\'esactiv\'e par la + directive {\bf Disabled} dans la ressource Job, ou avec la commande + {\bf disable} dans la Console. Au prochain d\'emarrage du Director, ou + si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera + r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut + est enabled). + +\label{estimate} +\item [estimate] + \index[general]{estimate} + Avec cette commande, vous pouvez vous faire une id\'ee du nombre de fichier + seront sauvegard\'es. Vous pouvez aussi l'utiliser pour \'eprouver les + param\`etres Include de vos FileSets sans passer par une sauvegarde + r\'eelle. Par d\'efaut, l'estimation est faite pour une sauvegarde Full. + Cependant, vous pouvez passer outre ce comportement en sp\'ecifiant + {\bf level=Incremental} ou {\bf level=Differential} sur la ligne de + commande. Un nom de job doit \^etre sp\'ecifi\'e, faute de quoi il vous sera + demand\'e. Optionnellement, vous pouvez sp\'ecifier un client et un + FileSet sur la ligne de commande. Bacula contacte alors le client + et calcule le nombre de fichier et d'octets qui seraient + sauvegard\'es. Notez qu'il s'agit d'une estimation calcul\'ee d'apr\`es + le nombre de blocs dans les fichiers plut\^ot qu'en lisant le nombre + effectif d'octets. Aussi, la taille estim\'ee est g\'en\'eralement plus + importante que celle de la sauvegarde r\'eelle. + + Optionnellement, vous pouvez ajouter le mot-clef {\bf listing}, auquel cas + tous les fichiers \`a sauvegarder seront affich\'es. Notez qu'un tel affichage + peut prendre un certain temps s'il s'agit d'une grosse sauvegarde. + Voici la forme compl\`ete de cette commande : + +\begin{verbatim} +estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{} + fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{} +\end{verbatim} + + La sp\'ecification du {\bf job} est suffisante, mais vous pouvez aussi + passer outre le client, le FileSet et/ou le niveau en les + sp\'ecifiant sur la ligne de commande. + + Par exemple, vous pourriez faire ceci : + +\footnotesize +\begin{verbatim} + @output /tmp/listing + estimate job=NightlySave listing level=Incremental + @output +\end{verbatim} +\normalsize + +ce qui produirait une liste compl\`ete de tous les fichiers \`a sauvegarder pour +le job {\bf NightlySave} au cours d'une sauvegarde incr\'ementale, et qui +consignerait cette liste dans le fichier {\bf /tmp/listing}. Notez que l'évaluation +produite par cette commande se base sur les tailles de fichiers contenues dans +l'objet "répertoire", aussi l'estimation peut être très éloignée de la réalité si vous +avez des fichiers creux (NDT : sparse files) sur votre système. Ce type de fichiers se +rencontre souvent sur les systèmes 64 bits avec certains systèmes de fichiers. +Le volume obtenu par l'évaluation est celui que sauvegardera Bacula si l'option +sparse est désactivée. Il n'y a actuellement aucun moyen d'évaluer le volume de +ce qui serait sauvegardé avec l'option sparse activée. + +\item [help] + \index[general]{help} + Cette commande affiche la liste des commandes disponibles. + +\item [label] + \index[general]{label} + \index[general]{relabel} + \index[general]{label} + \index[general]{relabel} + Cette commande est utilis\'ee pour \'etiqueter les volumes. La forme compl\`ete est : + +\begin{verbatim} + label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{} + slot=\lt{}slot\gt{} +\end{verbatim} + + Si vous omettez l'un quelconque des arguments, il vous sera r\'eclam\'e. + Le type de m\'edia est automatiquement r\'ecup\'er\'e de la ressource Storage. + Une fois que les informations requises sont r\'eunies, la Console + contacte le Storage Daemon sp\'ecifi\'e et lui ordonne d'\'etiqueter la + cartouche sp\'ecifi\'ee. Si l'\'etiquetage s'effectue correctement, la + Console cr\'e\'e un nouvel enregistrement dans le catalogue pour le + volume dans le pool appropri\'e. + + Les noms de volumes ne doivent contenir que des lettres, chiffres et + les caract\`eres sp\'eciaux tiret ({\bf -}), sous-lign\'e ({\bf \_}), double-point + ({\bf :}), et point ({\bf .}). Tous les autres caract\`eres, y compris l'espace, + sont ill\'egaux. Cette restriction vise \`a assurer une bonne lisibilit\'e + des noms de volumes pour r\'eduire le risque d'erreurs humaines. + + Notez que lors de l'\'etiquetage d'une cartouche vierge, Bacula obtient des + erreurs {\bf read I/O error} lorqu'il tente de v\'erifier si la cartouche + a d\'ej\`a un label. Si vous voulez \'eviter ce genre de message, placez un + indicateur de fin de fichier sur votre cartouche avant son \'etiquetage : + +\footnotesize +\begin{verbatim} + mt rewind + mt weof + +\end{verbatim} +\normalsize + +La commande label peut \'echouer pour plusieurs raisons : + + +\begin{enumerate} +\item Le nom de volume que vous avez sp\'ecifi\'e figure d\'ej\`a dans le catalogue. +\item Le Storage Daemon a d\'ej\`a une cartouche mont\'ee dans le lecteur. Dans ce cas, + vous devez la d\'emonter ({\bf unmount}) et ins\'erer une cartouche vierge + avant de lancer la commande {\bf label}. +\item La cartouche dans le lecteur porte d\'ej\`a une \'etiquette Bacula. + (Bacula ne r\'e-\'etiquette jamais une cartouche \`a moins qu'elle soit recycl\'ee + et que vous utilisiez la commande {\bf relabel} ). +\item Il n'y a pas de cartouche dans le lecteur. +\end{enumerate} + +Il existe deux moyens pour r\'e-\'etiqueter un volume qui porte d\'ej\`a une +\'etiquette Bacula. La m\'ethode brutale consiste \`a \'ecrire une marque de fin de +fichier sur la cartouche vec la commande du syst\`eme d'exploitation {\bf mt}, +quelque chose dans ce style : + +\footnotesize +\begin{verbatim} + mt -f /dev/st0 rewind + mt -f /dev/st0 weof +\end{verbatim} +\normalsize + +puis d'utiliser la commande {\bf label} pour ajouter une nouvelle \'etiquette. +Cette m\'ethode peut cependant laisser des traces de l'ancien volume dans le +catalogue. + +Il est pr\'ef\'erable d'utiliser la commande {\bf relabel} d\'ecrite ci-dessous sur +un volume purg\'e (automatiquement ou avec la commande {\bf purge}). + +Si votre librairie comporte un lecteur de codes barres, vous pouvez +\'etiqueter tous les volumes qu'elle contient en +utilisant la commande {\bf label barcodes}. En effet, apr\`es le lancement de +cette commande, Bacula monte chaque cartouche l'une apr\`es l'autre et +l'\'etiquette du nom de son code barres. simultan\'ement, l'enregistrement +appropri\'e est cr\'e\'e dans le catalogue. Toute cartouche dont le code barres +commence par les m\^emes caract\`eres que ceux sp\'ecifi\'es par la directive +"CleaningPrefix" de la ressource Pool du director est consid\'er\'ee comme +une cartouche de nettoyage et ne re\c{c}oit donc pas d'\'etiquette, bien +qu'une entr\'ee dans le catalogue lui soit d\'edi\'ee. Par exemple avec : + +\footnotesize +\begin{verbatim} + Pool { + Name ... + Cleaning Prefix = "CLN" + } + +\end{verbatim} +\normalsize + +tout slot contenant une cartouche de code barres CLNxxxxx sera trait\'ee en tant +que cartouche de nettoyage et ne sera jamais mont\'ee. Notez que la forme +compl\`ete de la commande est : + +\footnotesize +\begin{verbatim} +update storage=xxx pool=yyy slots=1-5,10 barcodes +\end{verbatim} +\normalsize + +\item [list] + \index[general]{list} + La commande {\bf list} extrait du catalogue les informations demand\'ees. Les + diff\'erentes champs de chaque enregistrement sont \'enum\'er\'es sur une simple + ligne. Voici les diff\'erentes formes de la commande : + +\footnotesize +\begin{verbatim} + list jobs + + list jobid= (affiche le jobid id) + + list ujobid= (affiche le job dont le nom unique est ) + + list job= (Affiche tous les jobs dont le nom est "job-name") + + list jobname= (voir ci-dessus) + + Dans cette commande, vous pouvez ajouter "limit=nn" pour limiter la sortie \`a 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 + + Ce que font la plupart des commandes ci-dessus devrait \^etre plus ou moins \'evident. + En g\'en\'eral, si vous ne sp\'ecifiez pas tous les arguments requis, la Console + vous sollicitera pour les arguments manquants. + + La commande {\bf list nextvol} affiche le nom du volume qui dera utilis\'e par + le job sp\'ecifi\'e. Soyez conscient que le prochain volume utilis\'e + pour un job d\'epend de nombreux facteurs dont le temps, et les autres + jobs qui seront ex\'ecut\'es avant celui sp\'ecifi\'e, qui peuvent remplir une + cartouche qui \'etait vide au moment de l'ex\'ecution de {\bf list nextvol}. + Aussi, consid\'erez la r\'eponse fournie par cette commande comme une bonne + estimation plut\^ot que comme une r\'eponse d\'efinitive. De plus, cette commande + a certains effets de bord : \'etant donn\'e qu'elle ex\'ecute le m\^eme algorithme + qu'un job, elle est susceptible de purger ou recycler un volume. Par d\'efaut, + le job sp\'ecifi\'e doit \^etre ex\'ecut\'e dans les deux jours ou aucun volume + ne sera trouv\'e. Vous pouvez cependant sp\'ecifier jusqu'\`a 50 jours en avant + avec la directive {\bf days=nnn}. Si, par exemple, un vendredi, vous voulez + savoir quel volume sera requis lundi pour le job MyJob, utilisez + {\bf list nextvol job=MyJob days=3}. + + Si vous souhaitez ajouter vos propres commandes pour interroger le + catalogue, vous pouvez les placer dans le fichier {\bf query.sql}. + Cela demande quelques connaissances du langage SQL. Voyez le + paragraphe sur la commande {\bf query} ci-dessous pour plus + d'informations. Voyez aussi le paragraphe sur la commande + {\bf llist} qui permet l'affichage complet des informations du + catalogue. + + Voici un exemple d'affichage produit par la commande {\bf list pools} : + +\footnotesize +\begin{verbatim} ++------+---------+---------+---------+----------+-------------+ +| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat | ++------+---------+---------+---------+----------+-------------+ +| 1 | Default | 0 | 0 | Backup | * | +| 2 | Recycle | 0 | 8 | Backup | File | ++------+---------+---------+---------+----------+-------------+ +\end{verbatim} +\normalsize + + Comme mentionn\'e pr\'ec\'edemment, la commande {\bf list} affiche des + informations du catalogue. Certais \'el\'ements sont ajout\'es dans le catalogue + d\`es le d\'emarrage de Bacula, mais en g\'en\'eral, la plupart ne le sont que + lorsqu'ils sont utilis\'es pour la premi\`ere fois. C'est le cas des clients, + des jobs, etc. + + Bacula cr\'e\'e une entr\'ee relative \`a un nouveau client dans le catalogue + la premi\`ere fois que vous ex\'ecut\'ez un job pour ce client. L'entr\'ee est + cr\'e\'ee que le job aboutisse ou qu'il \'echoue, mais il doit au moins d\'emarrer. + Lorsque le client est contact\'e, des informations suppl\'ementaires sont + r\'ecup\'er\'ees du client (le r\'esultat d'un "uname -a") et ajout\'ees au + catalogue. Un {\bf status} n'entra\^ine pas l'enregistrement dans le catalogue. + + Si vous voulez visualiser les ressources Client disponibles dans votre + catalogue, utilisez la commande {\bf show clients}. + +\item [llist] + \index[general]{llist} + La commande {\bf llist} (pour "long list") admet les m\^emes arguments que la + commande list d\'ecrite ci-dessus. La diff\'erence est que {\bf llist} affiche + le contenu complet de chaque enregistrement du catalogue s\'electionn\'e. + L'affichage des diff\'erents champs est produit verticalement, un champ par + ligne. Cette commande peut \^etre tr\`es prolixe. + + Si, au lieu du {\bf list pools} de l'exemple pr\'ec\'edent, vous saisissez + {\bf llist pools}, vous obtiendrez un affichage de ce genre : + +\footnotesize +\begin{verbatim} + PoolId: 1 + Name: Default + NumVols: 0 + MaxVols: 0 + UseOnce: 0 + UseCatalog: 1 + AcceptAnyVolume: 1 + VolRetention: 1,296,000 + VolUseDuration: 86,400 + MaxVolJobs: 0 + MaxVolBytes: 0 + AutoPrune: 0 + Recycle: 1 + PoolType: Backup + LabelFormat: * + + PoolId: 2 + Name: Recycle + NumVols: 0 + MaxVols: 8 + UseOnce: 0 + UseCatalog: 1 + AcceptAnyVolume: 1 + VolRetention: 3,600 + VolUseDuration: 3,600 + MaxVolJobs: 1 + MaxVolBytes: 0 + AutoPrune: 0 + Recycle: 1 + PoolType: Backup + LabelFormat: File + +\end{verbatim} +\normalsize + +\item [messages] + \index[general]{messages} + Cette commande affiche imm\'ediatement tout message de la console en attente. + + +\item [mount] + \index[general]{mount} + + La commande {\bf mount} est utilis\'ee pour obtenir de Bacula qu'il lise + un volume charg\'e dans un lecteur. C'est un moyen d'indiquer \`a Bacula + que vous avez charg\'e une cartouche qu'il doit examiner. Cette commande + n'est utilis\'ee que lorsque Bacula a demand\'e votre intervention pour + charger un lecteur vide, ou lorsque vous avez explicitement d\'emont\'e + un volume avec la commande {\bf unmount} dans la Console, ce qui + provoque la fermeture du lecteur. Si vous avez une librairie, vous ne + ferez pas op\'erer Bacula dessus avec la commande mount. Voici les + diff\'erentes formes de cette commande : + +mount storage=\lt{}storage-name\gt{} + +mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ] + + Si vous avez sp\'ecifi\'e {\bf Automatic Mount = yes} dans la ressource + Device du Storage Daemon, Alors Bacula pourra acc\'eder automatiquement + au volume, \`a moins que vous ne l'ayez explicitement d\'emont\'e ({\bf unmount}) + dans la Console. + +\item[python] + \index[general]{python} + La commande {\bf python} n'admet qu'un argument : {\bf restart}. + + La commande {\bf python} {\bf restart} r\'einitialise l'interpr\'eteur Python + du Director. Ceci peut \^etre tr\`es utile pour effectuer des tests, car une + fois que le Director est lanc\'e, et l'interpr\'eteur Python initialis\'e, + il n'y a pas d'autre moyen de lui faire int\'egrer des modifications + du script de d\'emarrage {\bf DirStartUp.py}. Pour plus de d\'etails sur + l'\'ecriture de scripts Python, consultez le chapitre \ilink{Ecrire des + scripts Python}{_ChapterStart60}. + +\label{ManualPruning} +\item [prune] + \index[general]{prune} + La commande {\bf prune} permet d'\'elaguer en toute s\'ecurit\'e les + enregistrements expir\'es du catalogue pour les jobs et les volumes. + Cette commande n'affecte que le catalogue, et non les donn\'ees + \'ecrites sur les volumes. Dans tous les cas, la commande {\bf prune} + respecte les p\'eriodes de r\'etention des enregistrements sp\'ecifi\'es. + Vous pouvez \'elaguer les jobs expir\'es, ainsi que les jobs et fichiers + d'un volume sp\'ecifi\'e. + +prune files|jobs|volume client=\lt{}client-name\gt{} +volume=\lt{}volume-name\gt{} + + Pour qu'un volume soit \'elagu\'e, son {\bf VolStatus} doit \^etre Full, + Used, ou Append, faute de quoi l'\'elagage sera sans effet. + +\item [purge] + \index[general]{purge} + La commande {\bf purge} efface les enregistrements sp\'ecifi\'es du catalogue + sans \'egards pour les p\'eriodes de r\'etention. {\bf Purge} n'affecte que le + catalogue, et non les donn\'ees \'ecrites sur les volumes. Cette commande + peut se r\'ev\'eler tr\`es dangereuse car vous pouvez parfaitement supprimer + les enregistrements relatifs \`a des sauvegardes valides et r\'ecentes. Aussi, + nous vous recommandons de ne pas l'utiliser \`a moins de savoir exactement + ce que vous faites. Voici les diff\'erentes formes de la commande {\bf purge} : + +purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{} + +purge jobs client=\lt{}client-name\gt{} (of all jobs) + +purge volume|volume=\lt{}vol-name\gt{} (of all jobs) + + + Pour qu'un volume puisse \^etre purg\'e, son {\bf VolStatus} doit \^etre Full, + Used, ou Append, faute de quoi la purge sera sans effet. + +\item [relabel] + \index[general]{relabel} + \index[general]{relabel} + Cette commande sert \`a r\'e-\'etiqueter physiquement un volume. En voici + la forme compl\`ete : + +relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{} + volume=\lt{}newvolume-name\gt{} + + Si vous omettez l'un quelconque des arguments, la console vous sollicitera + pour obtenir les informations manquantes. Pour qu'un volume puisse \^etre + r\'e-\'etiquet\'e, il doit figurer dans le catalogue, et avoir le statut + {\bf Purged} ou {\bf Recycle}. Cette situation peut se pr\'esenter + automatiquement par l'application des p\'eriodes de r\'etention, ou vous + pouvez l'obtenir par une {\bf purge} explicite du volume. + + Une fois que le volume a \'et\'e physiquement r\'e-\'etiquet\'e, les donn\'ees + qu'il contenait sont d\'efinitivement et irr\'em\'ediablement perdues. + +\item [release] + \index[general]{release} + Cette commande ordonne au Storage Daemon de rembobiner la cartouche + dans le lecteur, et de relire son \'etiquette \`a la prochaine utilisation + de la cartouche. + +release storage=\lt{}storage-name\gt{} + + Apr\`es cette commande, le lecteur est gard\'e \`a l'\'etat ouvert par Bacula + (sauf si l'option Always Open est d\'esactiv\'ee dans la configuration + du Storage Daemon), et il ne peut donc \^etre utilis\'e par un autre + programme. Toutefois, il est possible, avec certains lecteurs, de + changer la cartouche \`a ce stade. Lors du prochain job, Bacula saura + relire l'\'etiquette de la cartouche pour savoir laquelle est mont\'ee. + Si vous voulez \^etre en mesure d'utiliser le lecteur avec un autre + programme, par exemple {\bf mt}, vous devez uiliser la commande + {\bf unmount} pour que Bacula le lib\`ere compl\`etement. + +\item [reload] + \index[general]{reload} + Lorsqu'il re\c{c}oit la commande {\bf reload}, le Director relit ses fichiers + de configuration et applique les \'eventuelles modifications. Celles-ci + sont prises en compte imm\'ediatement, et donc effectives pour tous les + jobs \`a venir. Notez cependant qu'en ce qui concerne les modifications + apport\'ees aux Schedules, la prise en compte des nouvelles valeur peut + \^etre report\'ee au del\`a de l'ex\'ecution des jobs d\'ej\`a planifi\'es pour + les deux prochaines heures. Ceci est d\^u au planificateur qui pr\'evoit + "pr\'e-planifie" jusqu'\`a deux heures \`a l'avance les jobs \`a ex\'ecuter. + Ainsi, des jobs qui ont d\'ej\`a \'et\'e "pr\'e-planifi\'es" seront ex\'ecut\'es + suivant les valeurs sp\'ecifi\'ees par la ressource Schedule avant sa + modification. Les nouveaux jobs utiliseront les nouvelles valeurs. + A chaque fois que vous utilisez la commande {\bf reload} alors que + des jobs sont en cours d'ex\'ecution, les valeurs de la configuration + pr\'ec\'edente demeurent en vigueur jusqu'\`a ce que les ces jobs se terminent. + Le Director peut ainsi conserver jusqu'\`a 10 jeux de configurations + ant\'erieures avant de refuser une nouvelle commande {\bf reload}. + Une fois que l'un, au moins, des jeux de valeurs ant\'erieur a \'et\'e accept\'e, + il peut \`a nouveau accepter de nouvelles commandes {\bf reload}. + + Bien qu'il soit possible de recharger la configuration du Director + \`a la vol\'ee, alors m\^eme que des jobs sont en cours d'ex\'ecution, il faut + garder \`a l'esprit que c'est une op\'eration complexe, qui n'est pas d\'enu\'ee + d'effets de bords. C'est pourquoi il est recommand\'e, si vous \^etes amen\'e \`a + utiliser la commande {\bf reload}, de red\'emarrer le Director d\`es que vous + en aurez l'opportunit\'e. + +\label{restore_command} +\item [restore] + \index[general]{restore} + La commande {\bf restore} vous permet de s\'electionner un ou plusieurs jobs + (JobIds) \`a restaurer selon plusieurs m\'ethodes. Une fois que les JobIds ont + \'et\'e s\'electionn\'es, les enregistrements de fichiers sont plac\'es dans une + arborescence interne \`a Bacula, et la Console entre dans un mode de + s\'election interactif qui vous permet de naviguer dans cette arborescence + en s\'electionnant individuellement les fichiers ou r\'epertoires \`a restaurer. + Ce mode est assez similaire au mode de s\'election interactif du programme + Unix {\bf restore} standard. + +restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{} + where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{} + select current all done + + O\`u l'option {\bf current}, si elle est sp\'ecifi\'ee, indique \`a la commande + {\bf restore} de s\'electionner automatiquement la sauvegarde la plus + r\'ecente (sinon, vous serez sollicit\'e \`a ce sujet). L'option {\bf all}, + si elle est sp\'ecifi\'ee, indique \`a la commande {\bf restore} de restaurer + tous les fichiers (sinon, vous serez sollicit\'e \`a ce sujet). Pour plus de + d\'etails concernant la commande {\bf restore}, consultez le chapitre + \ilink{Restaurations avec Bacula}{_ChapterStart13}. + +\item [run] + \index[general]{run} + Cette commande vous permet d'ex\'ecuter imm\'ediatement vos jobs. Voici la forme + compl\`ete de cette commande : + +run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{} + fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{} + storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{} + when=\lt{}universal-time-specification\gt{} yes + + Toute information omise quoique requise fait l'objet d'une liste de s\'election, + et avant le lancement du job, un bilan des param\`etres vous est pr\'esent\'e avec + options d'accord, refus et modification, \`a moins que vous ayez sp\'ecifi\'e + {\bf yes}, auquel cas le job est imm\'ediatement envoy\'e vers le planificateur. + + Sur mon syst\`eme, j'obtiens ce qui suit lorsque je lance la commande run : + +\footnotesize +\begin{verbatim} +A job name must be specified. +The defined Job resources are: + 1: Matou + 2: Polymatou + 3: Rufus + 4: Minimatou + 5: Minou + 6: PmatouVerify + 7: MatouVerify + 8: RufusVerify + 9: Watchdog +Select Job resource (1-9): + +\end{verbatim} +\normalsize + +Si je choisis le num\'ero 5, j'obtiens : + +\footnotesize +\begin{verbatim} +Run Backup job +JobName: Minou +FileSet: Minou Full Set +Level: Incremental +Client: Minou +Storage: DLTDrive +Pool: Default +When: 2003-04-23 17:08:18 +OK to run? (yes/mod/no): + +\end{verbatim} +\normalsize + +Si maintenant j'entre {\bf yes}, le job est ex\'ecut\'e. Si je choisis {\bf mod}, +voici les otpions qui me sont propos\'ees : + +\footnotesize +\begin{verbatim} +Parameters to modify: + 1: Level + 2: Storage + 3: Job + 4: FileSet + 5: Client + 6: When + 7: Pool +Select parameter to modify (1-7): + +\end{verbatim} +\normalsize + +Vous pouvez, si vous le souhaitez, d\'emarrer un job plus tard, en utilisant le +param\`etre {\bf When}. Pour cela, faites le choix {\bf mod}, puis s\'electionnez +{\bf When} (no. 6) et enfin, saisissez l'heure et le jour de lancement +d\'esir\'es au format AAAA-MM-JJ HH:MM:SS. + +\item [setdebug] + \index[general]{setdebug} + \index[general]{setdebug} + \index[general]{debuggage} + \index[general]{debuggage Win32} + \index[general]{Windows!debuggage} + + Cette commande est utilis\'ee pour param\'etrer le niveau de d\'ebuggage de chaque + {\it daemon}. Voici la forme compl\`ete de cette commande. + +setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director | + storage=\lt{}storage-name\gt{} | all] + + Si le param\`etre de tra\c{c}age est actif (trace=1), alors le {\it daemon} est + plac\'e en mode tra\c{c}age, ce qui signifie que toutes les informations de + d\'ebuggage sont envoy\'ees vers le fichier {\bf bacula.trace} dans le + r\'epertoire courant du {\it daemon}. En principe, ce n'est n\'ecessaire + que pour le d\'ebuggage des clients Win32 o\`u les informations ne peuvent + \^etre envoy\'ees vers un terminal ou redirig\'ees vers un fichier. en mode + tra\c{c}age, chaque message de d\'ebuggage est ajout\'e au fichier, que vous devez + supprimer explicitement lorsque vous avez fini. + +\item [show] + \index[general]{show} + \index[general]{show} + LA commande {\bf show} \'enum\`ere les directives des ressources du Director + telles qu'ells sont d\'efinies dans son fichier de configuration. + Cette commande est surtout utilis\'ee par les d\'eveloppeurs \`a des fins + de d\'ebuggage. LEs mots-clef suivants sont accept\'es : + catalogs, clients, counters, devices, directors, + filesets, jobs, messages, pools, schedules, storages, all, help. + Ne confondez pas cette commande ave la commande {\bf list}, qui affiche + quand \`a elle le contenu du catalogue. + +\item [sqlquery] + \index[general]{sqlquery} + La commande {\bf sqlquery} place le programme Console en mode de + requ\^etes SQL, dans lequel chaque ligne que vousq tapez est concat\'en\'ee + \`a la pr\'ec\'edents jusqu'\`a ce qu'un point-virgule (;) soit rencontr\'e. Le + point-virgule termine la commande qui est alors directement envoy\'e au moteur + de base de donn\'ee SQL. Lorsque le r\'esultat issu de la base de donn\'ee SQL est + affich\'e, la Console est pr\`ete \`a recevoir une nouvelle commande SQL. + Pour sortir du mode {\bf sqlquery} et reevenir \`a l'invite de la Console, + entrez un point (.). + + Cette commande vous permet d'interroger directement le catalogue. Notez + que vous devriez savoir exactement ce que vous faites en utilisant cette + commande, car vous pouvez endommager s\'erieusement votre catalogue. + Consultez le paragraphe relatif \`a la commande {\bf query} qui offre un + moyen \`a la fois plus simple et plus sur de saisir des requ\^etes SQL. + + En fonction du moteur de base de donn\'ees que vous utilisez (MySQL, + PostgreSQL ou SQLite), vous disposerez de commandes quelque peu diff\'erentes. + Pour plus de d\'etails, r\'ef\'erez-vous aux documentations de MySQL, PostgreSQL + ou SQLite. + +\item [status] + \index[general]{status} + Cette commande produit un \'etat des prochains jobs planifi\'es au cours des + 24 prochanes heures, ainsi que l'\'etat des jobs en cours d'ex\'ecution. Voici + la forme compl\`ete de cette commande : + +status [all | dir=\lt{}dir-name\gt{} | director | + client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} | + days=nnn] + + Si vous entrez {\bf status dir}, la Console \'enum\`ere tous les jobs en cours + d'ex\'ecution, un r\'esum\'e des jobs planifi\'e pour ex\'ecution au cours des prochaines + 24 heures incluant le volume qui sera probablement utilis\'e, et donne la liste + des dix derniers jobs ex\'ecut\'es avec leurs \'etats. Gardez \`a l'esprit les deux + \'el\'ements suivants : + \begin{itemize} + \item L'obtention du volume n\'ecessite d'appliquer le m\^eme algorithme que + celui utilis\'e lors de l'ex\'ecution d'un job, ce qui peut r\'esulter en un \'elagage + de cartouche. + \item Le volume affich\'e est, au mieux, une bonne supposition. En effet le + volume effectivement utilis\'e peut \^etre diff\'erent en raison du temps \'ecoul\'e + entre le status et l'ex\'ecution du job, un autre job ayant pu, entre temps, + remplir compl\`etement la cartouche. + \end{itemize} + + Dans la liste des jobs en cours d'ex\'ecutions, vous pouvez trouver ce type + d'informations : + +\footnotesize +\begin{verbatim} +2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution +5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher + priority jobs to finish +5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs +5343 Full Rufus.2004-03-13_01.05.04 is running +\end{verbatim} +\normalsize + + La liste ci-dessus indique que le job de JobId 5343 (Rufus) est en cours. + Le job de JobId 5348 (Minou) est en attente de la fin du job 5343 + qui utilise la m\^eme ressource Storage, ce qui provoque le "waiting + on max Storage jobs". Le job de JobId 5349 a une priorit\'e inf\'erieure + \`a celle de tous les autres jobs, aussi, il est en attente de la fin de + jobs de priorit\'es sup\'erieures. Finalement, le job de jobId 2508 (MatouVerify) + est en attente ("waiting execution") car un seul job peut \^etre ex\'ecut\'e + en m\^eme temps. + + Si vous faites un {\bf status dir}, Bacula affiche par d\'efaut les premi\`eres + occurrences de tous les jobs pr\'evus pour ex\'ecution aujourd'hui et demain. + Si vous voulez voir les jobs pr\'evus pour les trois prochains jours, + (Si, par exemple vendredi, vous voulez voir les premi\`eres occurrences + des cartouches \`a utiliser vendredi, samedi, dimanche et lundi), vous + pouvez ajouter l'option {\bf days=3}. Notez, {\bf days=0} montre les + premi\`eres occurrences des jobs planifi\'es pour \^etre ex\'ecut\'es aujourd'hui + seulement. Si vous avez plusieurs ex\'ecutions planifi\'ees, pour chaque + job, seule la premi\`ere occurrence sera affich\'e pour la p\'eriode sp\'ecifi\'ee. + + Si votre job para\^it bloqu\'e, vous pouvez avoir une id\'ee g\'en\'erale du probl\`eme + en utilisant {\bf status dir}, et obtenir une information plus sp\'ecifique + avec {\bf status storage=xxx}. Par exemple, si j'utilise cette derni\`ere + commande sur un syst\`eme inoccup\'e, j'obtiens : + +\footnotesize +\begin{verbatim} +status storage=File +Connecting to Storage daemon File at 192.168.68.112:8103 + +rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz) +Daemon started 26-Mar-06 11:06, 0 Jobs run since started. + +Running Jobs: +No Jobs running. +==== + +Jobs waiting to reserve a drive: +==== + +Terminated Jobs: + JobId Level Files Bytes Status Finished Name +====================================================================== + 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave +==== + +Device status: +utochanger "DDS-4-changer" with devices: + "DDS-4" (/dev/nst0) +Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002" +Pool="*unknown*" + Slot 2 is loaded in drive 0. + Total Bytes Read=0 Blocks Read=0 Bytes/block=0 + Positioned at File=0 Block=0 +Device "Dummy" is not open or does not exist. +No DEVICE structure. + +Device "DVD-Writer" (/dev/hdc) is not open. +Device "File" (/tmp) is not open. +==== + +In Use Volume status: +==== +\end{verbatim} +\normalsize + +Ce qui r\'ev\`ele qu'aucun job n'est en cours d'ex\'ecution, et qu'aucun des +p\'eriph\'eriques n'est en cours d'utilisation. Si je d\'emonte la librairie +({\bf unmount}), qui ne sera plus utilis\'ee dans cet exemple, et que je lance +un job qui utilise le stockage File, le job se bloque. Si je demande \`a +nouveau {\bf status storage=xxx}, j'obtiens : + +\footnotesize +\begin{verbatim} +status storage=File +... +Device status: +Autochanger "DDS-4-changer" with devices: + "DDS-4" (/dev/nst0) +Device "DDS-4" (/dev/nst0) is not open. + Device is BLOCKED. User unmounted. + Drive 0 is not loaded. +Device "Dummy" is not open or does not exist. +No DEVICE structure. + +Device "DVD-Writer" (/dev/hdc) is not open. +Device "File" (/tmp) is not open. + Device is BLOCKED waiting for media. +==== +... +\end{verbatim} +\normalsize + +Il devrait maintenant \^etre clair que si un job n\'ecessitant la librairie +est ex\'ecut\'e, il bloquera en raison du d\'emontage de cette derni\`ere par +l'utilisateur. Mais le probl\`eme pour le job que j'ai lanc\'e avec le +p\'eriph\'erique "File" est que le p\'eriph\'erique est bloqu\'e en attente +d'un media : Bacula a besoin que vous \'etiquetiez un volume. + +\item [unmount] + \index[general]{unmount} + Cette commande sert \`a ordonner au Storage Daemon de d\'emonter le p\'eriph\'erique + sp\'ecifi\'e. Les formes de cette commande sont les m\^emes que celle de la commande + mount : + +\footnotesize +\begin{verbatim} +unmount storage= + +unmount [ jobid= | job= ] +\end{verbatim} +\normalsize + +\label{UpdateCommand} +\item [update] + \index[general]{update} + Cette commande met \`a jour le catalogue, que ce soit pour un pool sp\'ecifique, + un enregistrement de volume, ou les slots d'une librairie dot\'ee d'un lecteur + de codes barres. Dans le cas de la mise \`a jour d'un enregistrement de pool, + la nouvelle configuration est automatiquement r\'ecup\'er\'ee de la ressource + correspondante du fichier de configuration du Director. Cette commande peut + notamment servir \`a augmenter le nombre maxial de volumes dans un pool. Les + principaux mots-clef suivants peuvent \^etre utilis\'es : + +\footnotesize +\begin{verbatim} + media, volume, pool, slots +\end{verbatim} +\normalsize + +Dans le cas de la mise \`a jour d'un volume, vous serez interrog\'e sur le +param\`etre que vous voulez modifier. Voici ces param\`etres : + +\footnotesize +\begin{verbatim} + + Volume Status + Volume Retention Period + Volume Use Duration + Maximum Volume Jobs + Maximum Volume Files + Maximum Volume Bytes + Recycle Flag + Slot + InChanger Flag + Pool + Volume Files + Volume from Pool + All Volumes from Pool + +\end{verbatim} +\normalsize + + Pour le param\`etre slot, {\bf update slots}, Bacula obtient une liste + de tous les slots et de leurs codes barres du Storage Daemon, + pour chaque code barres trouv\'e, le slot est mis \`a jour dans + l'enregistrement Media du catalogue. C'est tr\`es pratique si vous + d\'eplacez des cartouches dans la librairie, ou si vous changez des + magasins de cartouches. Dans la foul\'ee, le drapeau InChanger est + aussi mis \`a jour.Ceci permet \`a BAcula de savoir quels cartouches sont + effectivement dans la librairie. + + Si vous n'avez pas de lecteur de codes barres, vous pouvez faire la + m\^eme chose depuis la version 1.33 gr\^ace \`a la commande {\bf update slots scan}. + Le mot-clef {\bf scan} ordonne \`a Bacula de monter physiquement chaque + cartouche afin de lire son VolumeName. + + Pour le param\`etre Pool, {\bf update pool}, Bacula d\'eplace le volume de + son pool courant vers le pool sp\'ecifi\'e. + + Pour les parm\`etres {\bf Volume from Pool} et {\bf All Volumes from Pool}, + les valeurs suivantes sont mises \`a jour depuis l'enregistrement + de pool : Recycle, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, + and MaxVolBytes. + + Voici la forme compl\`ete de la commande {\bf update} : + +\footnotesize +\begin{verbatim} + update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd + VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no + slot=nnn enabled=n + +\end{verbatim} +\normalsize + +\item [use] + \index[general]{use} + Cette commande vous perment de pr\'eciser le catalogue que vous voulez utiliser. + En principe, vous n'utiliserez qu'un seul catalogue, aussi vous n'aurez pas + besoin de faire ce choix. Sinon, utilisez cette commande pour passer de l'un + de vos catalogues \`a l'autre. + +use \lt{}database-name\gt{} + +\item [var] + \label{var} + \index[general]{var name} + Cette commande prend une cha\^ine \'eventuellement encadr\'ee de guillemets et effectue + l'expansion des variables comme elle serait effectu\'ee au niveau de la + directive {\bf LabelFormat}. Ainsi, vous pouvez tester vos cha\^ines + de format d'\'etiquetage. La diff\'erence entre la commande {\bf var} et le + processus effectif est que pour la premi\`ere, aucun job n'est en cours, + aussi des valeurs factices sont utilis\'ees au lieu des variables sp\'ecifiques + aux jobs. Cela vous permet cependant de vous faire une bonne id\'ee de ce qui + se passerait dans le cas r\'eel. + +\item [version] + \index[general]{version} + Cette commande affiche la version du Director. + +\item [quit] + \index[general]{quit} + Cette commande stoppe le programme Console. Celui-ci envoie la requ\^ete + {\bf quit} au Director et attend son accus\'e de r\'eception. Si le Director + est occup\'e, cela peut prendre un certain temps. Vous pouvez quitter + imm\'ediatement en utilisant la variante {\bf .quit} ({\bf quit} pr\'ec\'ed\'ee + d'un point). + +\item [query] + \index[general]{query} + Cette commande lit une requ\^ete SQL pr\'ed\'efinie dans le fichier de requ\^etes + (le nom et l'emplacement de ce fichier sont d\'efinis par la directive + QueryFile du fichier de configuration du Director). Il vous est alors + demand\'e de s\'electionner une requ\^ete du fichier, et \'eventuellement de + saisir un ou plusieurs param\`etres. La requ\^ete est alors soumise au + moteur de base de donn\'ees. + +Les requ\^etes suivantes sont actuellement (version 1.24) disponibles : + +\footnotesize +\begin{verbatim} +Available queries: + 1: List Job totals: + 2: List where a file is saved: + 3: List where the most recent copies of a file are saved: + 4: List total files/bytes by Job: + 5: List total files/bytes by Volume: + 6: List last 20 Full Backups for a Client: + 7: List Volumes used by selected JobId: + 8: List Volumes to Restore All Files: + 9: List where a File is saved: +Choose a query (1-9): + +\end{verbatim} +\normalsize + +\item [exit] + \index[general]{exit} + Cette commande termine le programme Console. + +\item [wait] + \index[general]{wait} + Cette commande place le Director en pause jusqu'\`a ce qu'il n'y ait plus + aucun job en ex\'ecution. Cette commande est utile dans des situation + d'utilisation automatis\'ee par scripts telles que les tests de r\'egression + o\`u vous voulez d\'emarrer un job, et attendre qu'il se termine avant de + poursuivre. Cette commande admet les options suivantes : + +\footnotesize +\begin{verbatim} + wait [jobid=nn] [jobuid=unique id] [job=job name] +\end{verbatim} +\normalsize + +\end{description} + +\label{dotcommands} + +\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point} +\index[general]{Commands!sp\'eciales, pr\'ec\'ed\'ees d'un point} +\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point} +\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point} + +Voici une liste de commandes pr\'efix\'ees d'un point (.). Elles ont pour vocation +d'\^etre utilis\'ees soit dans des programmes {\it batch}, soit par des interfaces +graphiques. Elles ne sont, en principe, pas utilis\'ees en mode interactif. +Une fois que le d\'eveloppement d'interfaces graphiques aura d\'emarr\'e, cette liste +s'accro\^itra consid\'erablement. + +\footnotesize +\begin{verbatim} +.backups job=xxx list backups for specified job +.defaults client=xxx fileset=yyy list defaults for specified client +.die cause the Director to segment fault (for debugging) +.dir when in tree mode prints the equivalent to the dir command, + but with fields separated by commas rather than spaces. +.jobs list all job names +.levels list all levels +.filesets list all fileset names +.clients list all client names +.pools list all pool names +.types list job types +.msgs return any queued messages +.messages get quick messages +.help help command output +.quit quit +.status get status output +.exit quit +\end{verbatim} +\normalsize + +\label{atcommands} + +\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)} +\index[general]{Commandes!sp\'eciales arobase @} +\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)} +\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)} + +Normalement, toutes les commandes saisies dans la Console sont imm\'ediatement +transmises au Director, qui peut r\'esider sur une autre machine, afin d'y \^etre +ex\'ecut\'ees. Il existe cependant quelques commandes, toutes pr\'ec\'ed\'ees du +caract\`ere arobase (@), qui ne sont pas envoy\'ees au Director, mais +directement interpr\'et\'ees par la Console. Notez que seule la Console +tty impl\'emente ces commandes, et non la Console GNOME. En voici la liste : + +\begin{description} + +\item [@input \lt{}nom-de-fichier\gt{}] + \index[general]{@input \lt{}nom-de-fichier\gt{}} + Lit et ex\'ecute les commandes consign\'ees dans le fichier sp\'ecifi\'e. + +\item [@output \lt{}nom-de-fichier\gt{} w/a] + \index[general]{@output \lt{}nom-de-fichier\gt{} w/a} + Envoit l'ensemble des retours de la Console vers le fichier sp\'ecifi\'e, + avec \'ecrasement si l'option {\bf w} est sp\'ecifi\'ee, ou ajout \`a la suite si l'option + {\bf a} est sp\'ecifi\'ee. Pour rediriger la sortie vers le terminal, entrez + simplement {\bf output} sans sp\'ecifier de nom de fichier. + ATTENTION : prenez garde de ne pas \'ecraser un fichier valide. + Voici un exemple typique lors d'un test de r\'egression : + +\footnotesize +\begin{verbatim} + @output /dev/null + commands ... + @output + +\end{verbatim} +\normalsize + +\item [@tee \lt{}nom-de-fichier\gt{} w/a] + \index[general]{@tee \lt{}nom-de-fichier\gt{} w/a} + Comme la commande pr\'ec\'edente avec envoi simultan\'e vers le terminal. Pour + sortir de ce mode, vous pouvez utiliser {\bf @tee} ou {\bf @output} sans + sp\'ecifier de nom de fichier. + +\item [@sleep \lt{}seconds\gt{}] + \index[general]{@sleep \lt{}seconds\gt{}} + Met en sommeil pour une dur\'ee du nombre de secondes sp\'ecifi\'e. + +\item [@time] + \index[general]{@time} + Affiche la date et l'heure courantes. + +\item [@version] + \index[general]{@version} + Affiche la version de la Console. + +\item [@quit] + \index[general]{@quit} + Quitte. + +\item [@exit] + \index[general]{@exit} + Quitte. + +\item [@\# n-importe-quoi] + \index[general]{n-importe-quoi} + Commentaire. +\end{description} + +\label{scripting} + +\section{Ex\'ecuter la Console depuis un script shell} +\index[general]{Script!Ex\'ecuter la Console depuis un script shell} +\index[general]{Ex\'ecuter la Console depuis un script shell} +\addcontentsline{toc}{section}{Ex\'ecuter la Console depuis un script shell} +Vous pouvez automatiser de nombreuses t\^aches effectu\'ees \`a la Console, en les +ex\'ecutant dans un script shell. Par exemple, si vous avez cr\'e\'e un fichier +contenant ceci : + +\footnotesize +\begin{verbatim} + ./bconsole -c ./bconsole.conf <