Debian Codegraph @

manuals/en/main/dirdconf.tex

raw
1 \chapter{Configuring the Director}
2 \label{blb:DirectorChapter}
3 \index[general]{Director!Configuring the}
4 \index[general]{Configuring the Director}
5
6 Of all the configuration files needed to run \bacula{}, the Director's is
7 the most complicated, and the one that you will need to modify the most often
8 as you add clients or modify the FileSets.
9
10 For a general discussion of configuration files and resources including the
11 data types recognized by \bacula{}, please see the
12 \bilink{Configuration}{blb:ConfigureChapter} chapter of this manual.
13
14 \section{Director Resource Types}
15 \index[general]{Types!Director Resource}
16 \index[general]{Director Resource Types}
17
18 Director resource types may be the following:
19
20 Job, JobDefs, Client, Storage/Autochanger, Catalog, Schedule, FileSet, Pool,
21 Director, Console, Counter, and Messages. We present them here in the most
22 logical order for defining them.
23
24 Note, everything revolves around a job and is tied to a job in one
25 way or another.
26
27 \begin{bitemize}
28 \item
29 \bilink{Director}{blb:DirectorResource} -- to define the Director's
30 name and its access password used for authenticating the Console program.
31 Only a single Director resource definition may appear in the Director's
32 configuration file. If you have either \btool{/dev/random} or \btool{bc} on your
33 machine, \bacula{} will generate a random password during the configuration
34 process, otherwise it will be left blank.
35 \item
36 \bilink{Job}{blb:JobResource} -- to define the backup/restore Jobs
37 and to tie together the Client, FileSet and Schedule resources to be used
38 for each Job. Normally, you will have Jobs of different names corresponding
39 to each client (i.\,e., one Job per client, but a different one with a different name
40 for each client).
41 \item
42 \bilink{JobDefs}{blb:JobDefsResource} -- optional resource for
43 providing defaults for Job resources.
44 \item
45 \bilink{Schedule}{blb:ScheduleResource} -- to define when a Job is to
46 be automatically run by \bacula{}'s internal scheduler. You
47 may have any number of Schedules, but each job will reference only
48 one.
49 \item
50 \bilink{FileSet}{blb:FileSetResource} -- to define the set of files
51 to be backed up with each job. You may have any number of
52 FileSets but each Job will reference only one.
53 \item
54 \bilink{Client}{blb:ClientResource2} -- to define what Client is to be
55 backed up. You will generally have multiple Client definitions. Each
56 Job will reference only a single client.
57
58 \item \bilink{Storage}{blb:StorageResource} (or Autochanger) -- to define on what
59 physical device the Volumes should be mounted. You may have one or more
60 Storage definitions.
61 \item
62 \bilink{Pool}{blb:PoolResource} -- to define the pool of Volumes
63 that can be used for a particular Job.% Most people use a
64 %single default Pool. However, if you have a large number
65 % -- I don't think this is true...
66 If there is a large number
67 of clients or volumes, you may want to have multiple Pools.
68 Pools allow you to restrict a Job (or a Client) to use
69 only a particular set of Volumes.
70 \item
71 \bilink{Catalog}{blb:CatalogResource} -- to define in what database to
72 keep the list of files and the Volume names where they are backed up.
73 Most people only use a single catalog. However, if you want to
74 scale the Director to many clients, multiple catalogs can be helpful.
75 Multiple catalogs require a bit more management because in general
76 you must know what catalog contains what data. Currently, all
77 Pools are defined in each catalog. This restriction will be removed
78 in a later release.
79 % Is the statement above actuall / still true?
80 \item \bilink{Console}{blb:ConsoleResource1} -- to define how the administrator
81 or user can interact with the Director.
82 \item \bilink{Counter}{blb:CounterResource} -- to define a counter variable that
83 can be accessed by variable expansion used for creating Volume labels.
84 \item
85 \bilink{Messages}{blb:MessagesChapter} -- to define where error and
86 information messages are to be sent or logged. You may define
87 multiple different message resources and hence direct particular
88 classes of messages to different users or locations (files, \ldots{}).
89 \end{bitemize}
90
91 \bwebdoc{blb:DirectorResource}
92 \section{The Director Resource}
93 \index[general]{Director Resource}
94 \index[general]{Resource!Director}
95
96 The Director resource defines the attributes of the Directors running on the
97 network. In the current implementation, there is only a single Director
98 resource, but a future design may contain multiple Directors to maintain
99 index and media database redundancy.
100
101 \begin{bdescription}
102
103 \item [Director]
104 \index[dir]{Director}
105 Start of the Director resource. One and only one director resource must be
106 supplied.
107
108 \bwebdoc{Director:Director:Name}
109 \item [Name = \bbracket{name}]
110 \index[dir]{Name}
111 \index[dir]{Directive!Name}
112 The director name used by the system administrator. This directive is
113 required.
114
115 \bwebdoc{Director:Director:Description}
116 \item [Description = \bbracket{text}]
117 \index[dir]{Description}
118 \index[dir]{Directive!Description}
119 The text field contains a description of the Director that will be displayed
120 in the graphical user interface. This directive is optional.
121
122 \bwebdoc{Director:Director:Password}
123 \item [Password = \bbracket{UA-password}]
124 \index[dir]{Password}
125 \index[dir]{Directive!Password}
126 Specifies the password that must be supplied for the default \bacula{}
127 Console to be authorized. The same password must appear in the \bresourcename{Director}
128 resource of the Console configuration file. For added
129 security, the password is never passed across the network but instead a
130 challenge response hash code created from the password. This directive
131 is required. If you have either \btool{/dev/random} or \btool{bc} on your
132 machine, \bacula{} will generate a random password during the configuration
133 process, otherwise it will be left blank and you must manually supply
134 it.
135
136 The password is plain text. It is not generated through any special
137 process but as noted above, it is better to use random text for
138 security reasons.
139
140 \bwebdoc{Director:Director:Messages}
141 \item [Messages = \bbracket{Messages-resource-name}]
142 \index[dir]{Directive!Messages}
143 The messages resource specifies where to deliver Director messages that are
144 not associated with a specific Job. Most messages are specific to a job and
145 will be directed to the Messages resource specified by the job. However,
146 there are a few messages that can occur when no job is running. This
147 directive is required.
148
149 \bwebdoc{Director:Director:WorkingDirectory}
150 \item [Working Directory = \bbracket{Directory}]
151 \index[dir]{Working Directory}
152 \index[dir]{Directive!Working Directory}
153 This directive is mandatory and specifies a directory in which the Director
154 may put its status files. This directory should be used only by \bacula{} but
155 may be shared by other \bacula{} daemons. However, please note, if this
156 directory is shared with other \bacula{} daemons (the File daemon and Storage
157 daemon), you must ensure that the \bdirectivename{Name} given to each daemon is
158 unique so that the temporary filenames used do not collide. By default
159 the \bacula{} configure process creates unique daemon names by postfixing them
160 with \texttt{-dir}, \texttt{-fd}, and \texttt{-sd}. Standard shell expansion of
161 the \bdirectivename{Working Directory} is done when the configuration file is read so that values such
162 as \textbf{\$HOME} will be properly expanded. This directive is required.
163
164 The working directory specified must already exist and be
165 readable and writable by the \bacula{} daemon referencing it.
166
167 If you have specified a Director user and/or a Director group on your
168 \btool{./configure} line with \bkeyword{{-}{-}with-dir-user} and/or
169 \bkeyword{{-}{-}with-dir-group} the Working Directory owner and group will
170 be set to those values.
171
172 \bwebdoc{Director:Director:PidDirectory}
173 \item [Pid Directory = \bbracket{Directory}]
174 \index[dir]{Pid Directory}
175 \index[dir]{Directive!Pid Directory}
176 This directive is mandatory and specifies a directory in which the Director
177 may put its process Id file. The process Id file is used to shutdown
178 \bacula{} and to prevent multiple copies of \bacula{} from running simultaneously.
179 Standard shell expansion of the \bdirectivename{Pid Directory} is done when the
180 configuration file is read so that values such as \textbf{\$HOME} will be
181 properly expanded.
182
183 The PID directory specified must already exist and be
184 readable and writable by the \bacula{} daemon referencing it
185
186 Typically on Linux systems, you will set this to: \bdirectoryname{/var/run}. If you are
187 not installing \bacula{} in the system directories, you can use the
188 \bresourcename{Working Directory} as defined above. This directive is required.
189
190 \bwebdoc{Director:Director:ScriptsDirectory}
191 \item [Scripts Directory = \bbracket{Directory}]
192 \index[dir]{Scripts Directory}
193 \index[dir]{Directive!Scripts Directory}
194 This directive is optional and, if defined, specifies a directory in
195 which the Director and the Storage daemon will look for many of the
196 scripts that it needs to use during particular operations such as
197 starting/stopping, the \btool{mtx-changer} script, tape alerts, as well as
198 catalog updates.
199 This directory may be shared by other \bacula{} daemons.
200 Standard shell expansion of the directory is done when the configuration
201 file is read so that values such as \textbf{\$HOME} will be properly
202 expanded.
203
204 \bwebdoc{Director:Director:QueryFile}
205 \item [QueryFile = \bbracket{Path}]
206 \index[dir]{QueryFile}
207 \index[dir]{Directive!QueryFile}
208 This directive is mandatory and specifies a directory and file in which
209 the Director can find the canned \acs{SQL} statements for the \bcommandname{query}
210 command of the Console. Standard shell expansion of the \bbracket{Path} is
211 done when the configuration file is read so that values such as \textbf{\$HOME}
212 will be properly expanded. This directive is required.
213
214 \bwebdoc{Director:Director:HeartbeatInterval}
215 \item [Heartbeat Interval = \bbracket{time-interval}]
216 \index[dir]{Heartbeat Interval}
217 \index[dir]{Directive!Heartbeat}
218 This directive is optional and if specified will cause the Director to
219 set a keepalive interval (heartbeat) in seconds on each of the sockets
220 it opens for the Client resource. This value will override any
221 specified at the Director level. It is implemented only on systems
222 (Linux, \ldots{}) that provide the \btool{setsockopt} \texttt{TCP\_KEEPIDLE} function.
223 The default value is \bdefaultvalue{300s}.
224
225 \label{blb:DirMaxConJobs}
226
227 \bwebdoc{Director:Director:MaximumConcurrentJobs}
228 \item [Maximum Concurrent Jobs = \bbracket{number}]
229 \index[dir]{Maximum Concurrent Jobs}
230 \index[dir]{Directive!Maximum Concurrent Jobs}
231 \index[general]{Simultaneous Jobs}
232 \index[general]{Concurrent Jobs}
233 where \bbracket{number} is the maximum number of total Director Jobs that should run concurrently. The default is set to \bdefaultvalue{20}, but you may set it to a larger number.
234 Every valid connection to any daemon (Director, File daemon, or Storage daemon) results in a Job. This includes connections from \bconsole{}. Thus the number of concurrent Jobs must, in general, be greater than the maximum number of Jobs that you wish to actually run.
235
236 In general, increasing the number of Concurrent Jobs increases the total throughtput of \bacula{}, because the simultaneous Jobs can all feed data to the Storage daemon and to the Catalog at the same time. However, keep in mind, that the Volume format becomes more complicated with multiple simultaneous jobs, consequently, restores may take longer if \bacula{} must sort through interleaved volume blocks from multiple simultaneous jobs. Though not normally necessary, this can be avoided by having each simultaneous job write to a different volume or by using data spooling, which will first spool the data to disk simultaneously, then write one spool file at a time to the volume thus avoiding excessive interleaving of the different job blocks.
237
238 \bwebdoc{Director:Director:FdConnectTimeout}
239 \item [FD Connect Timeout = \bbracket{time}]
240 \index[dir]{FD Connect Timeout}
241 \index[dir]{Directive!FD Connect Timeout}
242 where \bbracket{time} is the time that the Director should continue
243 attempting to contact the File daemon to start a job, and after which
244 the Director will cancel the job. The default is \bdefaultvalue{3 minutes}.
245
246 \bwebdoc{Director:Director:SdConnectTimeout}
247 \item [SD Connect Timeout = \bbracket{time}]
248 \index[dir]{SD Connect Timeout}
249 \index[dir]{Directive!SD Connect Timeout}
250 where \bbracket{time} is the time that the Director should continue
251 attempting to contact the Storage daemon to start a job, and after which
252 the Director will cancel the job. The default is \bdefaultvalue{30 minutes}.
253
254 \bwebdoc{Director:Director:DirAddresses}
255 \item [DirAddresses = \bbracket{IP-address-specification}]
256 \index[dir]{DirAddresses}
257 \index[dir]{Address}
258 \index[general]{Address}
259 \index[dir]{Directive!DirAddresses}
260 Specify the ports and addresses on which the Director daemon will listen
261 for \bacula{} Console connections. Probably the simplest way to explain
262 this is to show an example:
263
264 % TODO: IPv6 example needs updating. Also, we should use example.net and
265 % corresponding IP addresses... (ARL)
266 \begin{bVerbatim}
267 DirAddresses = {
268 ip = { addr = 1.2.3.4; port = 1205;}
269 ipv4 = {
270 addr = 1.2.3.4; port = http;
271 }
272 ipv6 = {
273 addr = 1.2.3.4;
274 port = 1205;
275 }
276 ip = {
277 addr = 1.2.3.4
278 port = 1205
279 }
280 ip = { addr = 1.2.3.4 }
281 ip = { addr = 201:220:222::2 }
282 ip = {
283 addr = bluedot.thun.net
284 }
285 }
286 \end{bVerbatim}
287
288 where ip, ip4, ip6, addr, and port are all keywords. Note, that the address
289 can be specified as either a dotted quadruple, or IPv6 colon notation, or as
290 a symbolic name (only in the ip specification). Also, port can be specified
291 as a number or as the mnemonic value from the \bfilename{/etc/services} file. If a port
292 is not specified, the default will be used. If an ip section is specified,
293 the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then
294 only IPv4 resolutions will be permitted, and likewise with ip6.
295
296 Please note that if you use the DirAddresses directive, you must
297 not use either a DirPort or a DirAddress directive in the same
298 resource.
299
300 \bwebdoc{Director:Director:DirPort}
301 \item [DirPort = \bbracket{port-number}]
302 \index[dir]{DirPort}
303 \index[dir]{Directive!DirPort}
304 Specify the port (a positive integer) on which the Director daemon will
305 listen for \bacula{} Console connections. This same port number must be
306 specified in the Director resource of the Console configuration file. The
307 default is \bdefaultvalue{9101}, so normally this directive need not be specified. This
308 directive should not be used if you specify the DirAddresses (plural)
309 directive.
310
311 \bwebdoc{Director:Director:DirAddress}
312 \item [DirAddress = \bbracket{IP-Address}]
313 \index[dir]{DirAddress}
314 \index[dir]{Directive!DirAddress}
315 This directive is optional, but if it is specified, it will cause the
316 Director server (for the Console program) to bind to the specified \bbracket{IP-Address},
317 which is either a domain name or an \acs{IP} address specified as a
318 dotted quadruple in string or quoted string format. If this directive is
319 not specified, the Director will bind to any available address (the
320 default). Note, unlike the DirAddresses specification noted above, this
321 directive only permits a single address to be specified. This directive
322 should not be used if you specify a DirAddresses (plural) directive.
323
324 \bwebdoc{Director:Director:DirSourceAddress}
325 \item [DirSourceAddress = \bbracket{IP-Address}]
326 \index[fd]{DirSourceAddress}
327 \index[fd]{Directive!DirSourceAddress}
328 This record is optional, and if it is specified, it will cause the Director
329 server (when initiating connections to a storage or file daemon) to source
330 its connections from the specified address. Only a single \acs{IP} address may be
331 specified. If this record is not specified, the Director server will source
332 its outgoing connections according to the system routing table (the default).
333
334 \bwebdoc{Director:Director:EventsRetention}
335 \item[Events Retention = \bbracket{time}]
336 \index[dir]{EventsRetention}
337 \index[dir]{Directive!EventsRetention}
338
339 The \bdirectivename{Events Retention} directive defines the length of time that
340 \bacula{} will keep events records in the Catalog database.
341 When this time period expires, and if the user runs the \bcommandname{prune events} command,
342 \bacula{} will prune (remove) Events records that are older than the specified period.
343
344 See the \bilink{Configuration chapter}{blb:Time} of this manual for additional
345 details of time specifications.
346
347 The default is \bdefaultvalue{1 month}.
348
349 \phantomsection
350 \bwebdoc{Director:Director:StatisticsRetention}
351 \item[Statistics Retention = \bbracket{time}]
352 \index[dir]{StatisticsRetention}
353 \label{blb:PruneStatistics}
354 \index[dir]{Directive!StatisticsRetention}
355
356 The \bdirectivename{Statistics Retention} directive defines the length of time that
357 \bacula{} will keep statistics job records in the Catalog database after the
358 Job End time. (In \btable{JobHistory} table) When this time period expires,
359 and if the user runs the \bcommandname{prune stats} command, \bacula{} will prune (remove)
360 Job records that are older than the specified period.
361
362 Theses statistics records aren't used for restore purpose, but mainly for
363 capacity planning, billings, etc. See \bilink{Statistics chapter}{blb:UseBaculaCatalogToExtractInformationChapter} for
364 additional information.
365
366 See the \bilink{Configuration chapter}{blb:Time} of this manual for additional
367 details of time specifications.
368
369 The default is \bdefaultvalue{5 years}.
370 \bwebdoc{Director:Director:AutoPrune}
371 \item[AutoPrune = \byesorno{}]
372
373 Normally, pruning of Files from the Catalog is specified on a Client by
374 Client basis in the \bresourcename{Client} resource with the \bdirectivename{AutoPrune}
375 directive. It is also possible to overwrite the Client settings in the \bresourcename{Pool} resource used by jobs,
376 with the \bdirectivename{AutoPrune}, \bdirectivename{PruneFiles} and \bdirectivename{PruneJobs}
377 directives.
378 \smallskip
379
380 If this directive is specified (not normally) and the value is \bvalue{no}, it
381 will override the value specified in all the \bresourcename{Client} and the \bresourcename{Pool} resources.
382 The default is \bdefaultvalue{yes}.
383 \smallskip
384
385 If you set \bvalueddirective{AutoPrune}{no}, pruning will not be done automatically, and
386 your Catalog will grow in size each time you run a Job. Pruning affects only
387 information in the catalog and not data stored in the backup archives (on
388 Volumes). The \bcommandname{prune} \bconsolename{} command can be used to prune catalog
389 records respecting the Client and/or the Pool \bdirectivename{FileRetention},
390 \bdirectivename{JobRetention} and \bdirectivename{VolumeRetention} directives.
391
392
393 \bwebdoc{Director:Director:VerId}
394 \item[VerId = \bbracket{string}]
395 \index[dir]{Directive!VerId}
396 where \bbracket{string} is an identifier which can be used for support purpose.
397 This string is displayed using the \bcommandname{version} command.
398
399 \bwebdoc{Director:Director:MaximumConsoleConnections}
400 \item[MaximumConsoleConnections = \bbracket{number}]
401 \index[dir]{MaximumConsoleConnections}
402 \index[dir]{Directive!MaximumConsoleConnections}
403 \index[dir]{Console}
404 where \bbracket{number} is the maximum number of Console Connections that
405 could run concurrently. The default is set to \bdefaultvalue{20}, but you may set it to a
406 larger number.
407
408 \bwebdoc{Director:Director:MaximumReloadRequests}
409 \item[MaximumReloadRequests = \bbracket{number}]
410 \index[dir]{MaximumReloadRequests}
411 \index[dir]{Directive!MaximumReloadRequests}
412 \index[dir]{Console}
413
414 Where \bbracket{number} is the maximum number of \bcommandname{reload} command that
415 can be queued while jobs are running. The default is set to \bdefaultvalue{32} and is usually
416 sufficient.
417
418 \bwebdoc{Director:Director:CommCompression}
419 \item[CommCompression = \byesorno{}]
420 \index[dir]{CommCompression}
421 \index[dir]{Directive!CommCompression}
422 \index[dir]{Compression}
423
424 If the two \bacula{} components (DIR, FD, SD, bconsole) have the comm line
425 compression enabled, the line compression will be enabled. The default value
426 is yes.
427
428 In many cases, the volume of data transmitted across the communications line
429 can be reduced by a factor of three when this directive is
430 \bdefaultvalue{enabled}. In the case that the compression is not effective,
431 \bacula{} turns it off on a record by record basis. \smallskip
432
433 If you are backing up data that is already compressed the comm line compression
434 will not be effective, and you are likely to end up with an average compression
435 ratio that is very small. In this case, \bacula{} reports \bvalue{None} in the
436 Job report.
437
438
439 % Generated by the Makefile with the extract.pl tool from the tls chapter
440 \input{DirectorDirectorTls}
441
442 \bwebdoc{Director:Director:End}
443
444 % \bwebdoc{Director:SharedStorage}
445 %\item[SharedStorage = \byesorno{}]
446 % \index[dir]{SharedStorage}
447 % \index[dir]{Directive!SharedStorage}
448 %
449 % The \texttt{Shared Storage} directive is a Bacula Enterprise feature that
450 % allows you to share volumes between different Storage resources. This
451 % directive should be used \textbf{only} if all \texttt{Media Type} are
452 % correctly set across all Devices.
453 %
454 % The \texttt{Shared Storage} directive should be used when using the SAN
455 % Shared Storage plugin or when accessing from the Director Storage resources
456 % directly to Devices of an Autochanger.
457 %
458 % When sharing volumes between different Storage resources, you will
459 % need also to use the \texttt{reset-storageid} script before using the
460 % \texttt{update slots} command. This script can be scheduled once a day in
461 % an Admin job.
462 %
463 %\begin{bVerbatim}
464 % $ /opt/bacula/scripts/reset-storageid MediaType StorageName
465 % $ bconsole
466 % * update slots storage=StorageName drive=0
467 %\end{bVerbatim}
468 %
469 % Please contact Bacula Systems support to get help on this advanced
470 % configuration.
471
472 \end{bdescription}
473
474 The following is an example of a valid Director resource definition:
475
476 \begin{bVerbatim}
477 Director {
478 Name = HeadMan
479 WorkingDirectory = "$HOME/bacula/bin/working"
480 Password = UA_password
481 PidDirectory = "$HOME/bacula/bin/working"
482 QueryFile = "$HOME/bacula/bin/query.sql"
483 Messages = Standard
484 }
485 \end{bVerbatim}
486
487 \bwebdoc{blb:JobResource}
488 %$
489
490 \section{The Job Resource}
491 \index[general]{Resource!Job}
492 \index[general]{Job Resource}
493
494 The Job resource defines a Job (Backup, Restore, \ldots{}) that \bacula{} must
495 perform. Each Job resource definition contains the name of a Client and
496 a FileSet to backup, the Schedule for the Job, where the data
497 are to be stored, and what media Pool can be used. In effect, each Job
498 resource must specify What, Where, How, and When or FileSet, Storage,
499 Backup/Restore/Level, and Schedule respectively. Note, the FileSet must
500 be specified for a restore job for historical reasons, but it is no longer used.
501
502 Only a single type (\bjobtype{Backup}, \bjobtype{Restore}, \ldots{}) can be specified for any
503 job. If you want to backup multiple FileSets on the same Client or multiple
504 Clients, you must define a Job for each one.
505
506 Note, you define only a single Job to do the Full, Differential, and
507 Incremental backups since the different backup levels are tied together by
508 a unique Job name. Normally, you will have only one Job per Client, but
509 if a client has a really huge number of files (more than several million),
510 you might want to split it into to Jobs each with a different FileSet
511 covering only part of the total files.
512
513 Multiple Storage daemons are not currently supported for Jobs, so if
514 you do want to use multiple storage daemons, you will need to create
515 a different Job and ensure that for each Job that the combination of
516 Client and FileSet are unique. The Client and FileSet are what \bacula{}
517 uses to restore a client, so if there are multiple Jobs with the same
518 Client and FileSet or multiple Storage daemons that are used, the
519 restore will not work. This problem can be resolved by defining multiple
520 FileSet definitions (the names must be different, but the contents of
521 the FileSets may be the same).
522
523
524 \begin{bdescription}
525
526 \item [Job]
527 \index[dir]{Job}
528 \index[dir]{Directive!Job}
529 Start of the Job resource. At least one Job resource is required.
530
531 \bwebdoc{Director:Job:Name}
532 \item [Name = \bbracket{name}]
533 \index[dir]{Name}
534 \index[dir]{Directive!Name}
535 The Job name. This name can be specified on the \bcommandname{run} command in the
536 console program to start a job. If the name contains spaces, it must be
537 specified between quotes. It is generally a good idea to give your job the
538 same name as the Client that it will backup. This permits easy
539 identification of jobs.
540
541 When the job actually runs, the unique Job Name will consist of the name you
542 specify here followed by the date and time the job was scheduled for
543 execution. This directive is required.
544
545 \bwebdoc{Director:Job:Enabled}
546 \item [Enabled = \byesorno{}]
547 \index[dir]{Enable}
548 \index[dir]{Directive!Enable}
549 This directive allows you to enable or disable a \bresourcename{Job} resource. When the
550 resource of the Job is disabled, the Job will no longer be scheduled and
551 it will not be available in the list of Jobs to be run. To be able
552 to use the Job you must \bcommandname{enable} it.
553
554 \bwebdoc{Director:Job:Tag}
555 \item [Tag = \bbracket{string, string2, string3}]
556 \index[dir]{Tag}
557 \index[dir]{Directive!Tag}
558 The \bdirectivename{Tag} directive specifies a list of tags to create when creating a new Job record.
559 This directive is optional.
560
561 \bwebdoc{Director:Job:Type}
562 \item [Type = \bbracket{job-type}]
563 \index[dir]{Type}
564 \index[dir]{Directive!Type}
565 The \bdirectivename{Type} directive specifies the Job type, which may be one of the
566 following: \bkeyword{Backup}, \bkeyword{Restore}, \bkeyword{Verify}, or \bkeyword{Admin}. This
567 directive is required. Within a particular Job Type, there are also Levels
568 as discussed in the next item.
569
570 \begin{bdescription}
571
572 \item [Backup]
573 \index[dir]{Backup}
574 Run a backup Job. Normally you will have at least one Backup job for each
575 client you want to save. Normally, unless you turn off cataloging, most all
576 the important statistics and data concerning files backed up will be placed
577 in the catalog.
578
579 \item [Restore]
580 \index[dir]{Restore}
581 Run a restore Job. Normally, you will specify only one Restore job
582 which acts as a sort of prototype that you will modify using the console
583 program in order to perform restores. Although certain basic
584 information from a Restore job is saved in the catalog, it is very
585 minimal compared to the information stored for a Backup job -- for
586 example, no File database entries are generated since no Files are
587 saved.
588
589 \bjobtype{Restore} jobs cannot be
590 automatically started by the scheduler as is the case for Backup, Verify
591 and Admin jobs. To restore files, you must use the \bcommandname{restore} command
592 in the console.
593
594
595 \item [Verify]
596 \index[dir]{Verify}
597 Run a \bjobtype{Verify} Job. In general, \bjobtype{Verify} jobs permit you to compare the
598 contents of the catalog to the file system, or to what was backed up. In
599 addition, to verifying that a tape that was written can be read, you can
600 also use \bjobtype{Verify} as a sort of tripwire intrusion detection.
601
602 \item [Admin]
603 \index[dir]{Admin}
604
605 Run an \bjobtype{Admin} Job. Only Director's runscripts will be executed.
606 The Client is not involved in an Admin job, so features such as \bdirectivename{Client Run Before Job}
607 are not available. Although an Admin job is recorded in the catalog, very little data is saved.
608 An Admin job can be used to periodically run catalog pruning, if you do not want to do it at the
609 end of each Backup Job.
610
611 \item [Migration]
612 \index[dir]{Migration}
613 Run a \bjobtype{Migration} Job (similar to a backup job) that reads data that was
614 previously backed up to a Volume and writes it to another Volume. (See
615 \vref{blb:MigrationChapter})
616
617 \item [Copy]
618 \index[dir]{Copy}
619 Run a \bjobtype{Copy} Job that essentially creates two identical copies of the same
620 backup. The \bjobtype{Copy} process is essentially identical to the Migration feature
621 with the exception that the Job that is copied is left unchanged. (See
622 \vref{blb:MigrationChapter})
623
624 \end{bdescription}
625
626 \label{blb:Level}
627 \bwebdoc{Director:Job:Level}
628 \item [Level = \bbracket{job-level}]
629 \index[dir]{Level}
630 \index[dir]{Directive!Level}
631 The Level directive specifies the default Job level to be run. Each
632 different Job Type (Backup, Restore, \ldots{}) has a different set of Levels
633 that can be specified. The Level is normally overridden by a different
634 value that is specified in the \bresourcename{Schedule} resource. This directive
635 is not required, but must be specified either by a \bdirectivename{Level} directive
636 or as an override specified in the \bresourcename{Schedule} resource.
637
638 For a \bjobtype{Backup} Job, the Level may be one of the following:
639
640 \begin{bdescription}
641
642 \item [Full]
643 \index[dir]{Full}
644 When the \bdirectivename{Level} is set to \bvalue{Full} all files in the FileSet whether or not
645 they have changed will be backed up.
646
647 \item [Incremental]
648 \index[dir]{Incremental}
649 When the Level is set to Incremental all files specified in the FileSet
650 that have changed since the last successful backup of the the same Job
651 using the same FileSet and Client, will be backed up. If the Director
652 cannot find a previous valid Full backup then the job will be upgraded
653 into a Full backup. When the Director looks for a valid backup record
654 in the catalog database, it looks for a previous Job with:
655
656 \begin{bitemize}
657 \item The same Job name.
658 \item The same Client name.
659 \item The same FileSet (any change to the definition of the FileSet such as
660 adding or deleting a file in the Include or Exclude sections constitutes a
661 different FileSet.
662 \item The Job was a Full, Differential, or Incremental backup.
663 \item The Job terminated normally (i.e. did not fail or was not canceled).
664 \item The Job started no longer ago than \bdirectivename{Max Full Interval}.
665 \end{bitemize}
666
667 If all the above conditions do not hold, the Director will upgrade the
668 Incremental to a Full save. Otherwise, the Incremental backup will be
669 performed as requested.
670
671 The File daemon (Client) decides which files to backup for an
672 Incremental backup by comparing start time of the prior Job (Full,
673 Differential, or Incremental) against the time each file was last
674 ``modified'' (\texttt{st\_mtime}) and the time its attributes were last
675 ``changed''(\texttt{st\_ctime}). If the file was modified or its attributes
676 changed on or after this start time, it will then be backed up.
677
678 Some virus scanning software may change \texttt{st\_ctime} while
679 doing the scan. For example, if the virus scanning program attempts to
680 reset the access time (\texttt{st\_atime}), which \bacula{} does not use, it will
681 cause \texttt{st\_ctime} to change and hence \bacula{} will backup the file during
682 an Incremental or Differential backup. In the case of Sophos virus
683 scanning, you can prevent it from resetting the access time (\texttt{st\_atime})
684 and hence changing \texttt{st\_ctime} by using the {\bf\verb:--:no-reset-atime}
685 option. For other software, please see their manual.
686
687 When \bacula{} does an Incremental backup, all modified files that are
688 still on the system are backed up. However, any file that has been
689 deleted since the last Full backup remains in the \bacula{} catalog,
690 which means that if between a Full save and the time you do a
691 restore, some files are deleted, those deleted files will also be
692 restored. The deleted files will no longer appear in the catalog
693 after doing another Full save.
694
695 In addition, if you move a directory rather than copy it, the files in
696 it do not have their modification time (\texttt{st\_mtime}) or their attribute
697 change time (\texttt{st\_ctime}) changed. As a consequence, those files will
698 probably not be backed up by an Incremental or Differential backup which
699 depend solely on these time stamps. If you move a directory, and wish
700 it to be properly backed up, it is generally preferable to copy it, then
701 delete the original.
702
703 However, to manage deleted files or directories changes in the
704 catalog during an Incremental backup you can use \bhighlight{accurate}
705 mode. This is quite memory consuming process. See
706 \bilink{Accurate mode}{accuratemode} for more details.
707
708 \item [Differential]
709 \index[dir]{Differential}
710 When the Level is set to Differential
711 all files specified in the FileSet that have changed since the last
712 successful Full backup of the same Job will be backed up.
713 If the Director cannot find a
714 valid previous Full backup for the same Job, FileSet, and Client,
715 backup, then the Differential job will be upgraded into a Full backup.
716 When the Director looks for a valid Full backup record in the catalog
717 database, it looks for a previous Job with:
718
719 \begin{bitemize}
720 \item The same Job name.
721 \item The same Client name.
722 \item The same FileSet (any change to the definition of the FileSet such as
723 adding or deleting a file in the Include or Exclude sections constitutes a
724 different FileSet.
725 \item The Job was a FULL backup.
726 \item The Job terminated normally (i.e. did not fail or was not canceled).
727 \item The Job started no longer ago than \bdirectivename{Max Full Interval}.
728 \end{bitemize}
729
730 If all the above conditions do not hold, the Director will upgrade the
731 Differential to a Full save. Otherwise, the Differential backup will be
732 performed as requested.
733
734 The File daemon (Client) decides which files to backup for a
735 differential backup by comparing the start time of the prior Full backup
736 Job against the time each file was last ``modified'' (\texttt{st\_mtime}) and the
737 time its attributes were last ``changed'' (\texttt{st\_ctime}). If the file was
738 modified or its attributes were changed on or after this start time, it
739 will then be backed up. The start time used is displayed after the \textbf{Since}
740 on the Job report. In rare cases, using the start time of the
741 prior backup may cause some files to be backed up twice, but it ensures
742 that no change is missed. As with the Incremental option, you should
743 ensure that the clocks on your server and client are synchronized or as
744 close as possible to avoid the possibility of a file being skipped.
745 Note, on versions 1.33 or greater \bacula{} automatically makes the
746 necessary adjustments to the time between the server and the client so
747 that the times \bacula{} uses are synchronized.
748
749 When \bacula{} does a Differential backup, all modified files that are
750 still on the system are backed up. However, any file that has been
751 deleted since the last Full backup remains in the \bacula{} catalog, which
752 means that if between a Full save and the time you do a restore, some
753 files are deleted, those deleted files will also be restored. The
754 deleted files will no longer appear in the catalog after doing another
755 Full save. However, to remove deleted files from the catalog during a
756 Differential backup is quite a time consuming process and not currently
757 implemented in \bacula{}. It is, however, a planned future feature.
758
759 As noted above, if you move a directory rather than copy it, the
760 files in it do not have their modification time (\texttt{st\_mtime}) or
761 their attribute change time (\texttt{st\_ctime}) changed. As a
762 consequence, those files will probably not be backed up by an
763 Incremental or Differential backup which depend solely on these
764 time stamps. If you move a directory, and wish it to be
765 properly backed up, it is generally preferable to copy it, then
766 delete the original. Alternatively, you can move the directory, then
767 use the \btool{touch} program to update the timestamps.
768
769 %% TODO: merge this with incremental
770 However, to manage deleted files or directories changes in the
771 catalog during an Differential backup you can use \bhighlight{accurate}
772 mode. This is quite memory consuming process. See
773 \bilink{Accurate mode}{accuratemode} for more details.
774
775 Every once and a while, someone asks why we need Differential
776 backups as long as Incremental backups pickup all changed files.
777 There are possibly many answers to this question, but the one
778 that is the most important for me is that a Differential backup
779 effectively merges
780 all the Incremental and Differential backups since the last Full backup
781 into a single Differential backup. This has two effects:
782 \begin{benumerate}
783 \item It gives some redundancy since the old backups could be used if the merged backup
784 cannot be read.
785 \item More importantly, it reduces the number of Volumes that are needed to do a restore effectively eliminating the need to read
786 all the volumes on which the preceding Incremental and Differential
787 backups since the last Full are done.
788 \end{benumerate}
789
790 \item [VirtualFull]
791 \index[dir]{VirtualFull}
792 When the backup Level is set to \bvalue{VirtualFull}, \bacula{} will consolidate the
793 previous Full backup plus the most recent Differential backup and any
794 subsequent Incremental backups into a new Full backup. This new Full backup
795 will then be considered as the most recent Full for any future Incremental
796 or Differential backups. The VirtualFull backup is accomplished without
797 contacting the client by reading the previous backup data and writing it to
798 a volume in a different pool.
799
800 \bacula{}'s virtual backup feature is often called Synthetic Backup or
801 Consolidation in other backup products.
802
803 \end{bdescription}
804
805 For a \bjobtype{Restore} Job, no level needs to be specified.
806
807 For a \bjobtype{Verify} Job, the Level may be one of the following:
808
809 \begin{bdescription}
810
811 \item [InitCatalog]
812 \index[dir]{InitCatalog}
813 does a scan of the specified \bdirectivename{FileSet} and stores the file
814 attributes in the Catalog database. Since no file data is saved, you
815 might ask why you would want to do this. It turns out to be a very
816 simple and easy way to have a \textbf{Tripwire} like feature using
817 \bacula{}. In other words, it allows you to save the state of a set of
818 files defined by the \bresourcename{FileSet} and later check to see if those files
819 have been modified or deleted and if any new files have been added.
820 This can be used to detect system intrusion. Typically you would
821 specify a \bresourcename{FileSet} that contains the set of system files that
822 should not change (e.g. /sbin, /boot, /lib, /bin, \ldots{}). Normally, you
823 run the \bkeyword{InitCatalog} level verify one time when your system is
824 first setup, and then once again after each modification (upgrade) to
825 your system. Thereafter, when your want to check the state of your
826 system files, you use a \bjobtype{Verify} \bvalueddirective{level}{Catalog}. This
827 compares the results of your \bkeyword{InitCatalog} with the current state of
828 the files.
829
830 \item [Catalog]
831 \index[dir]{Catalog}
832 Compares the current state of the files against the state previously
833 saved during an \bkeyword{InitCatalog}. Any discrepancies are reported. The
834 items reported are determined by the \bjobtype{Verify} options specified on
835 the \bdirectivename{Include} directive in the specified \bresourcename{FileSet}
836 (see the \bresourcename{FileSet} resource below for more details). Typically this command will
837 be run once a day (or night) to check for any changes to your system
838 files.
839
840 Please note! If you run two Verify Catalog jobs on the same client at
841 the same time, the results will certainly be incorrect. This is because
842 Verify Catalog modifies the Catalog database while running in order to
843 track new files.
844
845 \item [Data]
846 \index[dir]{Data}
847
848 Read back the data stored on volumes and check data attributes such as size and
849 the checksum of all the files.
850
851 To run the Verify job, it is possible to use the ``jobid'' parameter of the
852 ``run'' command.
853
854 Please note, the current Verify Data implementation requires specifying the
855 correct Storage resource in the Verify job. The Storage resource can be
856 changed with the bconsole command line and with the menu.
857
858 It is also possible to use the \texttt{accurate} option to check
859 catalog records at the same time. When using a Verify job with
860 \texttt{level=Data} and \texttt{accurate=yes} can replace the
861 \texttt{level=VolumeToCatalog} option.
862
863 To run a Verify Job with the \texttt{accurate} option, it is possible to set
864 the option in the Job definition or set use the \texttt{accurate=yes} on the
865 command line.
866
867 \begin{verbatim}
868 * run job=VerifyData level=Data jobid=10 accurate=yes
869 \end{verbatim}
870
871
872 \item [VolumeToCatalog]
873 \index[dir]{VolumeToCatalog}
874 This level causes \bacula{} to read the file attribute data written to the
875 Volume from the last backup Job for the job specified on the \bdirectivename{VerifyJob}
876 directive. The file attribute data are compared to the
877 values saved in the Catalogind database and any differences are reported.
878 This is similar to the \bkeyword{DiskToCatalog} level except that instead of
879 comparing the disk file attributes to the catalog database, the
880 attribute data written to the Volume is read and compared to the catalog
881 database. Although the attribute data including the signatures (\acs{MD}5 or
882 \acs{SHA}1) are compared, the actual file data is not compared (it is not in
883 the catalog).
884
885 Please note! If you run two Verify VolumeToCatalog jobs on the same
886 client at the same time, the results will certainly be incorrect. This
887 is because the Verify VolumeToCatalog modifies the Catalog database
888 while running.
889
890 \item [DiskToCatalog]
891 \index[dir]{DiskToCatalog}
892 This level causes \bacula{} to read the files as they currently are on
893 disk, and to compare the current file attributes with the attributes
894 saved in the catalog from the last backup for the job specified on the
895 \bdirectivename{VerifyJob} directive. This level differs from the \bkeyword{VolumeToCatalog}
896 level described above by the fact that it doesn't compare against a
897 previous Verify job but against a previous backup. When you run this
898 level, you must supply the verify options on your Include statements.
899 Those options determine what attribute fields are compared.
900
901 This command can be very useful if you have disk problems because it
902 will compare the current state of your disk against the last successful
903 backup, which may be several jobs.
904
905 Note, the current implementation (1.32c) does not identify files that
906 have been deleted.
907 \end{bdescription}
908
909 \bwebdoc{Director:Job:Accurate}
910 \item [Accurate = \byesorno{}]
911 \index[dir]{Accurate}
912 In accurate mode, the File daemon knowns exactly which files were present
913 after the last backup. So it is able to handle deleted or renamed files.
914
915 When restoring a FileSet for a specified date (including ``most
916 recent''), \bacula{} is able to restore exactly the files and
917 directories that existed at the time of the last backup prior to
918 that date including ensuring that deleted files are actually deleted,
919 and renamed directories are restored properly.
920
921 In this mode, the File daemon must keep data concerning all files in
922 memory. So If you do not have sufficient memory, the backup may
923 either be terribly slow or fail.
924
925 %% $$ memory = \sum_{i=1}^{n}(strlen(path_i + file_i) + sizeof(CurFile))$$
926
927 For 500.000 files (a typical desktop linux system), it will require
928 approximately 64 Megabytes of RAM on your File daemon to hold the
929 required information.
930
931 \bwebdoc{Director:Job:VerifyJob}
932 \item [Verify Job = \bbracket{Job-Resource-Name}]
933 \index[dir]{Verify Job}
934 \index[dir]{Directive!Verify Job}
935 If you run a verify job without this directive, the last job run will be
936 compared with the catalog, which means that you must immediately follow
937 a backup by a \bcommandname{verify} command. If you specify a \bjobtype{Verify} Job \bacula{}
938 will find the last job with that name that ran. This permits you to run
939 all your backups, then run \bjobtype{Verify} jobs on those that you wish to be
940 verified (most often a \bkeyword{VolumeToCatalog}) so that the tape just
941 written is re-read.
942
943 \bwebdoc{Director:Job:JobDefs}
944 \item [JobDefs = \bbracket{JobDefs-Resource-Name}]
945 \index[dir]{JobDefs}
946 \index[dir]{Directive!JobDefs}
947 If a \bbracket{JobDefs-Resource-Name} is specified, all the values contained in the
948 named \bresourcename{JobDefs} resource will be used as the defaults for the current Job.
949 Any value that you explicitly define in the current Job resource, will
950 override any defaults specified in the \bresourcename{JobDefs} resource. The use of
951 this directive permits writing much more compact \bresourcename{Job} resources where the
952 bulk of the directives are defined in one or more JobDefs. This is
953 particularly useful if you have many similar Jobs but with minor
954 variations such as different Clients. A simple example of the use of
955 JobDefs is provided in the default \bfilename{bacula-dir.conf} file.
956
957 \bwebdoc{Director:Job:Bootstrap}
958 \item [Bootstrap = \bbracket{bootstrap-file}]
959 \index[dir]{Bootstrap}
960 \index[dir]{Directive!Bootstrap}
961 The \bdirectivename{Bootstrap} directive specifies a bootstrap file that, if provided,
962 will be used during \bjobtype{Restore} Jobs and is ignored in other Job
963 types. The \bbracket{bootstrap-file} contains the list of tapes to be used
964 in a \bjobtype{Restore} Job as well as which files are to be restored.
965 Specification of this directive is optional, and if specified, it is
966 used only for a restore job. In addition, when running a \bjobtype{Restore} job
967 from the console, this value can be changed.
968
969 If you use the \bcommandname{restore} command in the \bconsolename{} program, to start a
970 \bjobtype{Restore} job, the \bbracket{bootstrap-file} will be created automatically from
971 the files you select to be restored.
972
973 For additional details of the \bdirectivename{bootstrap} directive, please see
974 \bilink{Restoring Files with the Bootstrap File}{blb:BootstrapChapter} chapter
975 of this manual.
976 \label{blb:writebootstrap}
977
978 \bwebdoc{Director:Job:WriteBootstrap}
979 \item [Write Bootstrap = \bbracket{bootstrap-file-specification}]
980 \index[dir]{Write Bootstrap}
981 \index[dir]{Directive!Write Bootstrap}
982 The \bresourcename{writebootstrap} directive specifies a file name where \bacula{}
983 will write a \textbf{bootstrap} file for each Backup job run. This
984 directive applies only to \bjobtype{Backup} Jobs. If the Backup job is a Full
985 save, \bacula{} will erase any current contents of the specified file
986 before writing the bootstrap records. If the Job is an Incremental
987 or Differential
988 save, \bacula{} will append the current bootstrap record to the end of the
989 file.
990
991 Using this feature, permits you to constantly have a bootstrap file that
992 can recover the current state of your system. Normally, the file
993 specified should be a mounted drive on another machine, so that if your
994 hard disk is lost, you will immediately have a bootstrap record
995 available. Alternatively, you should copy the bootstrap file to another
996 machine after it is updated. Note, it is a good idea to write a separate
997 bootstrap file for each Job backed up including the job that backs up
998 your catalog database.
999
1000 If the \bbracket{bootstrap-file-specification} begins with a vertical bar
1001 (\vb{}), \bacula{} will use the specification as the name of a program to which
1002 it will pipe the bootstrap record. It could for example be a shell
1003 script that emails you the bootstrap record.
1004
1005 On versions 1.39.22 or greater, before opening the file or executing the
1006 specified command, \bacula{} performs
1007 \bilink{character substitution}{blb:character substitution} like in RunScript
1008 directive. To automatically manage your bootstrap files, you can use
1009 this in your \bresourcename{JobDefs} resources:
1010 \begin{bVerbatim}
1011 JobDefs {
1012 Write Bootstrap = "%c_%n.bsr"
1013 ...
1014 }
1015 \end{bVerbatim}
1016
1017 For more details on using this file, please see the chapter entitled
1018 \bilink{The Bootstrap File}{blb:BootstrapChapter} of this manual.
1019
1020 \bwebdoc{Director:Job:Client}
1021 \item [Client = \bbracket{client-resource-name}]
1022 \index[dir]{Client}
1023 \index[dir]{Directive!Client}
1024 The Client directive specifies the Client (File daemon) that will be used in
1025 the current Job. Only a single Client may be specified in any one Job. The
1026 Client runs on the machine to be backed up, and sends the requested files to
1027 the Storage daemon for backup, or receives them when restoring. For
1028 additional details, see the
1029 \bilink{Client Resource section}{blb:ClientResource} of this chapter.
1030 This directive is required.
1031
1032 \bwebdoc{Director:Job:Fileset}
1033 \item [FileSet = \bbracket{FileSet-resource-name}]
1034 \index[dir]{FileSet}
1035 \index[dir]{Directive!FileSet}
1036 The FileSet directive specifies the FileSet that will be used in the
1037 current Job. The FileSet specifies which directories (or files) are to
1038 be backed up, and what options to use (e.g. compression, \ldots{}). Only a
1039 single FileSet resource may be specified in any one Job. For additional
1040 details, see the \bilink{FileSet Resource section}{blb:FileSetResource} of
1041 this chapter. This directive is required.
1042
1043 \bwebdoc{Director:Job:Base}
1044 \item [Base = \bbracket{job-resource-name, \ldots{}}]
1045 \index[dir]{Base}
1046 \index[dir]{Directive!Base}
1047 The Base directive permits to specify the list of jobs that will be used during
1048 Full backup as base. This directive is optional. See the
1049 \bilink{Base Job chapter}{blb:basejobs} for more information.
1050
1051 \bwebdoc{Director:Job:Messages}
1052 \item [Messages = \bbracket{messages-resource-name}]
1053 \index[dir]{Messages}
1054 \index[dir]{Directive!Messages}
1055 The Messages directive defines what Messages resource should be used for
1056 this job, and thus how and where the various messages are to be
1057 delivered. For example, you can direct some messages to a log file, and
1058 others can be sent by email. For additional details, see the
1059 \bilink{Messages Resource}{blb:MessagesChapter} Chapter of this manual. This
1060 directive is required.
1061
1062 \bwebdoc{Director:Job:SnapshotRetention}
1063 \item [Snapshot Retention = \bbracket{time-period-specification}]
1064 \index[dir]{Snapshot Retention}
1065 \index[dir]{Directive!Snapshot Retention}
1066
1067 The Snapshot Retention directive defines the length of time that \bacula{} will
1068 keep Snapshots in the Catalog database and on the Client after the Snapshot
1069 creation. When this time period expires, and if using the \bcommandname{snapshot prune}
1070 command, \bacula{} will prune (remove) Snapshot records that are older than
1071 the specified Snapshot Retention period and will contact the FileDaemon to delete
1072 Snapshots from the system.
1073
1074 The Snapshot retention period is specified as seconds, minutes, hours, days,
1075 weeks, months, quarters, or years. See the
1076 \bilink{ Configuration chapter}{blb:Time} of this manual for
1077 additional details of time specification.
1078
1079 The default is \bdefaultvalue{0 seconds}, Snapshots are deleted at the end of the
1080 backup. The Job \bdirectivename{SnapshotRetention} directive overwrites the Client
1081 \bdirectivename{SnapshotRetention} directive.
1082
1083 \bwebdoc{Director:Job:Pool}
1084 \item [Pool = \bbracket{pool-resource-name}]
1085 \index[dir]{Pool}
1086 \index[dir]{Directive!Pool}
1087 The Pool directive defines the pool of Volumes where your data can be
1088 backed up. Many \bacula{} installations will use only the \bvalue{Default}
1089 pool. However, if you want to specify a different set of Volumes for
1090 different Clients or different Jobs, you will probably want to use
1091 Pools. For additional details, see the
1092 \bilink{Pool Resource section}{blb:PoolResource} of this chapter. This directive is required.
1093
1094 \bwebdoc{Director:Job:FullBackupPool}
1095 \item [Full Backup Pool = \bbracket{pool-resource-name}]
1096 \index[dir]{Full Backup Pool}
1097 \index[dir]{Directive!Full Backup Pool}
1098 The \bdirectivename{Full Backup Pool} specifies a Pool to be used for Full backups.
1099 It will override any Pool specification during a Full backup. This
1100 directive is optional.
1101
1102 \bwebdoc{Director:Job:DifferentialBackupPool}
1103 \item [Differential Backup Pool = \bbracket{pool-resource-name}]
1104 \index[dir]{Differential Backup Pool}
1105 \index[dir]{Directive!Differential Backup Pool}
1106 The \bdirectivename{Differential Backup Pool} specifies a Pool to be used for
1107 Differential backups. It will override any Pool specification during a
1108 Differential backup. This directive is optional.
1109
1110 \bwebdoc{Director:Job:IncrementalBackupPool}
1111 \item [Incremental Backup Pool = \bbracket{pool-resource-name}]
1112 \index[dir]{Incremental Backup Pool}
1113 \index[dir]{Directive!Incremental Backup Pool}
1114 The \bdirectivename{Incremental Backup Pool} specifies a Pool to be used for
1115 Incremental backups. It will override any Pool specification during an
1116 Incremental backup. This directive is optional.
1117
1118 \bwebdoc{Director:Job:VirtualFullBackupPool}
1119 \item [VirtualFull Backup Pool = \bbracket{pool-resource-name}]
1120 \index[dir]{VirtualFull Backup Pool}
1121 \index[dir]{Directive!VirtualFull Backup Pool}
1122 The \bdirectivename{VirtualFull Backup Pool} specifies a Pool to be used for
1123 VirtualFull backups. It will override any Pool specification during an
1124 VirtualFull backup. This directive is optional.
1125
1126 \bwebdoc{Director:Job:BackupsToKeep}
1127 \item [BackupsToKeep = \bbracket{number}]
1128 \index[dir]{Backups to Keep}
1129 \index[dir]{Directive!Backups To Keep}
1130
1131 When this directive is present during a Virtual Full (it is ignored for other
1132 Job types), it will look for a Full backup that has more subsequent backups
1133 than the value specified. In the example below, the Job will simply terminate
1134 unless there is a Full back followed by at least 31 backups of
1135 either level Differential or Incremental.
1136
1137 \begin{bVerbatim}
1138 Job {
1139 Name = "VFull"
1140 Type = Backup
1141 Level = VirtualFull
1142 Client = "my-fd"
1143 File Set = "FullSet"
1144 Accurate = Yes
1145 Backups To Keep = 30
1146 }
1147 \end{bVerbatim}
1148
1149 Assuming that the last Full backup is followed by 32 Incremental
1150 backups, a Virtual Full will be run that consolidates the Full with the first
1151 two Incrementals that were run after the Full. The result is that you will end
1152 up with a Full followed by 30 Incremental backups.
1153
1154 \bwebdoc{Director:Job:DeleteConsolidatedJobs}
1155 \item [DeleteConsolidatedJobs = \bbracket{yes/no}]
1156 \index[dir]{Delete Consolidated Jobs}
1157 \index[dir]{Directive!Delete Consolidated Jobs}
1158
1159 If set to \bvalue{yes}, it will cause any old Job that is consolidated during a
1160 Virtual Full to be deleted. In the example above we saw that a Full plus one
1161 other job (either an Incremental or Differential) were consolidated into a new
1162 Full backup. The original Full plus the other Job consolidated will be
1163 deleted. The default value is \bdefaultvalue{no}.
1164
1165
1166 \bwebdoc{Director:Job:Schedule}
1167 \item [Schedule = \bbracket{schedule-name}]
1168 \index[dir]{Schedule}
1169 \index[dir]{Directive!Schedule}
1170 The Schedule directive defines what schedule is to be used for the Job.
1171 The schedule in turn determines when the Job will be automatically
1172 started and what Job level (i.e. Full, Incremental, \ldots{}) is to be run.
1173 This directive is optional, and if left out, the Job can only be started
1174 manually using the Console program. Although you may specify only a
1175 single Schedule resource for any one job, the Schedule resource may
1176 contain multiple \bdirectivename{Run} directives, which allow you to run the Job at
1177 many different times, and each \bdirectivename{Run} directive permits overriding
1178 the default Job Level Pool, Storage, and Messages resources. This gives
1179 considerable flexibility in what can be done with a single Job. For
1180 additional details, see the
1181 \bilink{Schedule Resource chapter}{blb:ScheduleResource} of this manual.
1182
1183
1184 \bwebdoc{Director:Job:Storage}
1185 \item [Storage = \bbracket{storage-resource-name}]
1186 \index[dir]{Storage}
1187 \index[dir]{Directive!Storage}
1188 The Storage directive defines the name of the storage services where you
1189 want to backup the FileSet data. For additional details, see the
1190 \bilink{Storage Resource Chapter}{blb:StorageResource} of this manual.
1191 The Storage resource may also be specified in the Job's Pool resource,
1192 in which case the value in the Pool resource overrides any value
1193 in the Job. This Storage resource definition is not required by either
1194 the Job resource or in the Pool, but it must be specified in
1195 one or the other, if not an error will result.
1196 Storage can be either specified by an single item or it can be specified as
1197 a comma separated list of storages to use according to StorageGroupPolicy.
1198 If some number of first storage daemons on the list are unavailable due to network problems,
1199 broken or unreachable for some other reason, Bacula will take first available one from the list
1200 (which is sorted according to the policy used) which is network reachable and healthy.
1201
1202 \bwebdoc{Director:Job:StorageGroupPolicy}
1203 \item [StorageGroupPolicy = \bbracket{Storage Group Policy Name}]
1204 \index[dir]{StorageGroupPolicy}
1205 \index[dir]{Directive!StorageGroupPolicy}
1206 Storage Group Policy determines how Storage resources (from the 'Storage' directive) are
1207 being choosen from the Storage list. If no StoragePolicy is specified Bacula always
1208 tries to use first available Storage from the provided list.
1209 Currently supported policies are:
1210 \begin{itemize}
1211 \item [ListedOrder] - This is the default policy, which uses first available storage from the list provided
1212 \item [LeastUsed] - This policy scans all storage daemons from the list and chooses the one with the least
1213 number of jobs being currently run
1214 \item [FreeSpace] - This policy queries each Storage Daemon in the list for
1215 its FreeSpace (as a sum of devices specified in the SD config) and sorts
1216 the list according to the FreeSpace returned, so that first item in the
1217 list is the SD with the biggest amount of FreeSpace while the last one in
1218 the list is the one with the least amount of FreeSpace available.
1219 \item [LastBackedUpTo] - This policy ensures that job is backed up to the
1220 storage where the same job (of the same level, i.e. Full or Incremental)
1221 has been backed up the longest time ago. The goal is to split the jobs to
1222 improve redundancy.
1223 \item[LastBackupedToStore] - This policy ensures that job is backed up on
1224 the storage where the same job (with same level i.e. Full or Incremental)
1225 has been backed up to the longest time ago. The goal is to spread the jobs
1226 to improve redundancy.
1227 \item[FreeSpaceLeastUsed] - This policy ensures that a job is backed up to
1228 the storage with the most free space and least running jobs. Within the
1229 candidates storages, the least used one will be selected. Candidate
1230 storages are determined by the \texttt{StorageGroupPolicyThreshold} Job
1231 directive. If MaxFreeSpace is the largest amount of free space for all
1232 storages in the group, a storage will be a candidate if its free space is
1233 above $$MaxFreeSpace - StorageGroupPolicyThreshold$$.
1234 \end{itemize}
1235
1236 \bwebdoc{Director:Job:StorageGroupPolicyThreshold}
1237 \item [StorageGroupPolicyThreshold = \bbracket{Threshold size}] Used in
1238 conjunction with the FreeSpaceLeastUsed StorageGroupePolicy to specify the
1239 range of free space Candidate storages.
1240
1241 \bwebdoc{Director:Job:MaxStartDelay}
1242 \item [Max Start Delay = \bbracket{time}]
1243 \index[dir]{Max Start Delay}
1244 \index[dir]{Directive!Max Start Delay}
1245 The time specifies the maximum delay between the scheduled time and the
1246 actual start time for the Job. For example, a job can be scheduled to
1247 run at 1:00am, but because other jobs are running, it may wait to run.
1248 If the delay is set to 3600 (one hour) and the job has not begun to run
1249 by 2:00am, the job will be canceled. This can be useful, for example,
1250 to prevent jobs from running during day time hours. The default is \bdefaultvalue{0}
1251 which indicates no limit.
1252
1253 \bwebdoc{Director:Job:MaxRunTime}
1254 \item [Max Run Time = \bbracket{time}]
1255 \index[dir]{Max Run Time}
1256 \index[dir]{Directive!Max Run Time}
1257 The time specifies the maximum allowed time that a job may run, counted
1258 from when the job starts, (\textbf{not} necessarily the same as when the
1259 job was scheduled).
1260
1261 By default, the the watchdog thread will kill any Job that has run more
1262 than 200 days. The maximum watchdog timeout is independent of MaxRunTime
1263 and cannot be changed.
1264
1265
1266 \bwebdoc{Director:Job:IncrementalWaitRunTime}
1267 \item [Incremental|Differential Max Wait Time = \bbracket{time}]
1268 \index[dir]{Incremental Wait Run Time}
1269 \index[dir]{Differential Wait Run Time}
1270 \index[dir]{Directive!Differential Max Wait Time}
1271 Theses directives have been deprecated in favor of
1272 \bdirectivename{Incremental|Differential Max Run Time} since bacula 2.3.18.
1273
1274 \bwebdoc{Director:Job:IncrementalMaxRunTime}
1275 \item [Incremental Max Run Time = \bbracket{time}]
1276 \index[dir]{Incremental Max Run Time}
1277 \index[dir]{Directive!Incremental Max Run Time}
1278 The time specifies the maximum allowed time that an Incremental backup job may
1279 run, counted from when the job starts, (\textbf{not} necessarily the same as when
1280 the job was scheduled).
1281
1282 \bwebdoc{Director:Job:DifferentialMaxRunTime}
1283 \item [Differential Max Run Time = \bbracket{time}]
1284 \index[dir]{Differential Max Run Time}
1285 \index[dir]{Directive!Differential Max Run Time}
1286 The time specifies the maximum allowed time that a Differential backup job may
1287 run, counted from when the job starts, (\textbf{not} necessarily the same as when
1288 the job was scheduled).
1289
1290 \bwebdoc{Director:Job:MaxRunSchedTime}
1291 \item [Max Run Sched Time = \bbracket{time}]
1292 \index[dir]{Max Run Sched Time}
1293 \index[dir]{Directive!Max Run Sched Time}
1294
1295 The time specifies the maximum allowed time that a job may run, counted from
1296 when the job was scheduled. This can be useful to prevent jobs from running
1297 during working hours. We can see it like \texttt{Max Start Delay + Max Run
1298 Time}.
1299
1300
1301 \bwebdoc{Director:Job:MaxWaitTime}
1302 \item [Max Wait Time = \bbracket{time}]
1303 \index[dir]{Max Wait Time}
1304 \index[dir]{Directive!Max Wait Time}
1305 The time specifies the maximum allowed time that a job may block waiting
1306 for a resource (such as waiting for a tape to be mounted, or waiting for
1307 the storage or file daemons to perform their duties), counted from the
1308 when the job starts, (\textbf{not} necessarily the same as when the job was
1309 scheduled). This directive works as expected since bacula 2.3.18.
1310
1311 \bimageH{different_time}{Job time control directives}{blb:fig:differenttime}
1312
1313 \bwebdoc{Director:Job:MaximumSpawnedJobs}
1314 \item [Maximum Spawned Jobs = \bbracket{nb}]
1315 \index[dir]{Maximum Spawned Jobs}
1316 \index[dir]{Directive!Maximum Spawned Jobs}
1317
1318 The Job resource now permits specifying a number of
1319 \bdirectivename{Maximum Spawn Jobs}. The default is \bdefaultvalue{600}. This directive can be useful if you have
1320 big hardware and you do a lot of Migration/Copy jobs which start
1321 at the same time.
1322
1323
1324 \bwebdoc{Director:Job:MaximumBandwidth}
1325 \item [Maximum Bandwidth = \bbracket{speed}]
1326 \index[dir]{Maximum Bandwidth}
1327 \index[dir]{Directive!Maximum Bandwidth}
1328
1329 The speed parameter specifies the maximum allowed bandwidth in \bhighlight{bytes} that a
1330 job may use. You may specify the following speed parameter modifiers:
1331 \bvalue{kb/s} (1,000 bytes per second), \bvalue{k/s} (1,024 bytes per second),
1332 \bvalue{mb/s} (1,000,000 bytes per second), or \bvalue{m/s} (1,048,576 bytes per second).
1333
1334 The use of TLS, TLS PSK, CommLine compression and Deduplication can interfer
1335 with the value set with the Directive.
1336
1337 \bwebdoc{Director:Job:MaxFullInterval}
1338 \item [Max Full Interval = \bbracket{time}]
1339 \index[dir]{Max Full Interval}
1340 \index[dir]{Directive!Max Full Interval}
1341 The time specifies the maximum allowed age (counting from start time) of
1342 the most recent successful Full backup that is required in order to run
1343 Incremental or Differential backup jobs. If the most recent Full backup
1344 is older than this interval, Incremental and Differential backups will be
1345 upgraded to Full backups automatically. If this directive is not present,
1346 or specified as 0, then the age of the previous Full backup is not
1347 considered.
1348
1349 \bwebdoc{Director:Job:MaxVirtualFullInterval}
1350 \item [Max VirtualFull Interval = \bbracket{time}]
1351 \index[dir]{Max VirtualFull Interval}
1352 \index[dir]{Directive!Max VirtualFull Interval}
1353
1354 The time specifies the maximum allowed age (counting from start time) of
1355 the most recent successful Full backup that is required in order to run
1356 Incremental, Differential or Full backup jobs. If the most recent Full backup
1357 is older than this interval, Incremental, Differential and Full backups will be
1358 converted to a VirtualFull backup automatically. If this directive is not present,
1359 or specified as 0, then the age of the previous Full backup is not
1360 considered.
1361
1362 \smallskip{}
1363
1364 Please note that a VirtualFull job is not a real backup job. A VirtualFull
1365 will merge exiting jobs to create a new virtual Full job in the catalog and will copy
1366 the exiting data to new volumes.
1367
1368 The Client is not used in a VirtualFull job, so when using this directive,
1369 the Job that was supposed to run and save recently modified data on the
1370 Client will not run. Only the next regular Job defined in the Schedule will
1371 backup the data. It will not be possible to restore the data that was modified
1372 on the Client between the last Incremental/Differential and the VirtualFull.
1373
1374
1375 \label{blb:PreferMountedVolumes}
1376
1377 \bwebdoc{Director:Job:PreferMountedVolumes}
1378 \item [Prefer Mounted Volumes = \byesorno{}]
1379 \index[dir]{Prefer Mounted Volumes}
1380 \index[dir]{Directive!Prefer Mounted Volumes}
1381 If the Prefer Mounted Volumes directive is set to \bvalue{yes} (default
1382 \bdefaultvalue{yes}), the Storage daemon is requested to select either an Autochanger or
1383 a drive with a valid Volume already mounted in preference to a drive
1384 that is not ready. This means that all jobs will attempt to append
1385 to the same Volume (providing the Volume is appropriate -- right Pool,
1386 \ldots{} for that job), unless you are using multiple pools.
1387 If no drive with a suitable Volume is available, it
1388 will select the first available drive. Note, any Volume that has
1389 been requested to be mounted, will be considered valid as a mounted
1390 volume by another job. This if multiple jobs start at the same time
1391 and they all prefer mounted volumes, the first job will request the
1392 mount, and the other jobs will use the same volume.
1393
1394 If the directive is set to \bvalue{no}, the Storage daemon will prefer
1395 finding an unused drive, otherwise, each job started will append to the
1396 same Volume (assuming the Pool is the same for all jobs). Setting
1397 Prefer Mounted Volumes to no can be useful for those sites
1398 with multiple drive autochangers that prefer to maximize backup
1399 throughput at the expense of using additional drives and Volumes.
1400 This means that the job will prefer to use an unused drive rather
1401 than use a drive that is already in use.
1402
1403 Despite the above, we recommend against setting this directive to
1404 \bvalue{no} since
1405 it tends to add a lot of swapping of Volumes between the different
1406 drives and can easily lead to deadlock situations in the Storage
1407 daemon. We will accept bug reports against it, but we cannot guarantee
1408 that we will be able to fix the problem in a reasonable time.
1409
1410 A better alternative for using multiple drives is to use multiple
1411 pools so that \bacula{} will be forced to mount Volumes from those Pools
1412 on different drives.
1413
1414 \bwebdoc{Director:Job:PruneJobs}
1415 \item [Prune Jobs = \byesorno{}]
1416 \index[dir]{Prune Jobs}
1417 \index[dir]{Directive!Prune Jobs}
1418 Normally, pruning of Jobs from the Catalog is specified on a Client by
1419 Client basis in the Client resource with the \bdirectivename{AutoPrune} directive.
1420 If this directive is specified (not normally) and the value is \bvalue{yes},
1421 it will override the value specified in the Client resource. The
1422 default is \bdefaultvalue{no}.
1423
1424
1425 \bwebdoc{Director:Job:PruneFiles}
1426 \item [Prune Files = \byesorno{}]
1427 \index[dir]{Prune Files}
1428 \index[dir]{Directive!Prune Files}
1429 Normally, pruning of Files from the Catalog is specified on a Client by
1430 Client basis in the Client resource with the \bdirectivename{AutoPrune} directive.
1431 If this directive is specified (not normally) and the value is \bvalue{yes},
1432 it will override the value specified in the Client resource. The
1433 default is \bdefaultvalue{no}.
1434
1435 \bwebdoc{Director:Job:PruneVolumes}
1436 \item [Prune Volumes = \byesorno{}]
1437 \index[dir]{Prune Volumes}
1438 \index[dir]{Directive!Prune Volumes}
1439 Normally, pruning of Volumes from the Catalog is specified on a Pool by
1440 Pool basis in the Pool resource with the \bdirectivename{AutoPrune} directive.
1441 Note, this is different from File and Job pruning which is done on a
1442 Client by Client basis. If this directive is specified (not normally)
1443 and the value is \bvalue{yes}, it will override the value specified in the
1444 Pool resource. The default is \bdefaultvalue{no}.
1445
1446 \bwebdoc{Director:Job:Runscript}
1447 \item [RunScript \{\bbracket{body-of-runscript}\}]
1448 \index[dir]{RunScript}
1449 \index[dir]{Directive!Run Script}
1450
1451 The \bdirectivename{RunScript} directive behaves like a resource in that it
1452 requires opening and closing braces around a number of directives
1453 that make up the body of the runscript.
1454
1455 The specified \bdirectivename{Command} (see below for details) is run as an external
1456 program prior or after the current Job. This is optional. By default, the
1457 program is executed on the Client side like in \texttt{ClientRunXXXJob}.
1458
1459 \bdirectivename{Console} options are special commands that are sent to the director instead
1460 of the \acs{OS}. At this time, console command ouputs are redirected to log with
1461 the jobid \bvalue{0}.
1462
1463 You can use following console command : \bcommandname{delete}, \bcommandname{disable},
1464 \bcommandname{enable}, \bcommandname{estimate}, \bcommandname{list}, \bcommandname{llist},
1465 \bcommandname{memory}, \bcommandname{prune}, \bcommandname{purge}, \bcommandname{reload},
1466 \bcommandname{status}, \bcommandname{setdebug}, \bcommandname{show}, \bcommandname{time},
1467 \bcommandname{trace}, \bcommandname{update}, \bcommandname{version}, \bcommandname{.client},
1468 \bcommandname{.jobs}, \bcommandname{.pool}, \bcommandname{.storage}. See console chapter for
1469 more information. You need to specify needed information on command line, nothing
1470 will be prompted. Example :
1471
1472 \begin{bVerbatim}
1473 Console = "prune files client=%c"
1474 Console = "update stats age=3"
1475 \end{bVerbatim}
1476
1477 You can specify more than one Command/Console option per RunScript.
1478
1479 You can use following options may be specified in the body
1480 of the runscript:
1481
1482 \LTXtable{\linewidth}{t-main-runscript}
1483
1484 Any output sent by the command to standard output will be included in the
1485 \bacula{} job report. The command string must be a valid program name or name
1486 of a shell script.
1487
1488 In addition, the command string is parsed then fed to the OS,
1489 which means that the path will be searched to execute your specified
1490 command, but there is no shell interpretation, as a consequence, if you
1491 invoke complicated commands or want any shell features such as redirection
1492 or piping, you must call a shell script and do it inside that script.
1493
1494 Before submitting the specified command to the operating system, \bacula{}
1495 performs character substitution of the following characters:
1496 \label{blb:character substitution}
1497
1498 \begin{bVerbatim}
1499 %% = %
1500 %b = Job Bytes
1501 %c = Client's name
1502 %C = If the job is a Cloned job (Only on director side)
1503 %d = Daemon's name (Such as host-dir or host-fd)
1504 %D = Director's name (Also valid on file daemon)
1505 %e = Job Exit Status
1506 %E = Non-fatal Job Errors
1507 %f = Job FileSet (Only on director side)
1508 %F = Job Files
1509 %h = Client address
1510 %i = JobId
1511 %I = Migration/Copy JobId (Only in Copy/Migrate Jobs)
1512 %j = Unique Job id
1513 %l = Job Level
1514 %n = Job name
1515 %o = Job Priority
1516 %p = Pool name (Only on director side)
1517 %P = Current PID process
1518 %R = Read Bytes
1519 %s = Since time
1520 %S = Previous Job name (Only on file daemon side)
1521 %t = Job type (Backup, ...)
1522 %v = Volume name (Only on director side)
1523 %w = Storage name (Only on director side)
1524 %x = Spooling enabled? ("yes" or "no")
1525 \end{bVerbatim}
1526
1527 Some character substitutions are not available in all situations. The Job Exit
1528 Status code \%e edits the following values:
1529
1530 \index[dir]{Exit Status}
1531 \begin{bitemize}
1532 \item OK
1533 \item Error
1534 \item Fatal Error
1535 \item Canceled
1536 \item Differences
1537 \item Unknown term code
1538 \end{bitemize}
1539
1540 Thus if you edit it on a command line, you will need to enclose
1541 it within some sort of quotes.
1542
1543 \bwebdoc{Director:Job:End}
1544
1545 You can use these following shortcuts:
1546 \LTXtable{\linewidth}{t-main-runscript-shortcuts}
1547 Examples:
1548 \begin{bVerbatim}
1549 RunScript {
1550 RunsWhen = Before
1551 FailJobOnError = No
1552 Command = "/etc/init.d/apache stop"
1553 }
1554
1555 RunScript {
1556 RunsWhen = After
1557 RunsOnFailure = yes
1558 Command = "/etc/init.d/apache start"
1559 }
1560 \end{bVerbatim}
1561
1562 %\paragraph
1563 \textbf{Notes about ClientRunBeforeJob}
1564
1565 For compatibility reasons, with this shortcut, the command is executed
1566 directly when the client recieve it. And if the command is in error, other
1567 remote runscripts will be discarded. To be sure that all commands will be
1568 sent and executed, you have to use RunScript syntax.
1569
1570 %\paragraph
1571 \textbf{Special Shell Considerations}
1572
1573 A ``Command ='' can be one of:
1574 \begin{bitemize}
1575 \item The full path to an executable program
1576 \item The name of an executable program that can be found in the \$PATH
1577 \item A \emph{complex} shell command in the form of: "sh -c \textbackslash"your commands go here\textbackslash""
1578 \end{bitemize}
1579 %\paragraph
1580 \textbf{Special Windows Considerations}
1581
1582 You can run scripts just after snapshots initializations with
1583 \bkeyword{AfterVSS} keyword.
1584
1585 In addition, for a Windows client, please take
1586 note that you must ensure a correct path to your script. The script or
1587 program can be a \bfilename{.com}, \bfilename{.exe} or a \bfilename{.bat} file.
1588 If you just put the program name in then \bacula{} will search using
1589 the same rules that \btool{cmd.exe} uses
1590 (current directory, \bacula{} bin directory, and \texttt{PATH}). It will even try the
1591 different extensions in the same order as \btool{cmd.exe}.
1592 The command can be anything that \btool{cmd.exe} or \btool{command.com} will recognize
1593 as an executable file.
1594
1595 However, if you have slashes in the program name then \bacula{} figures you
1596 are fully specifying the name, so you must also explicitly add the three
1597 character extension.
1598
1599 The command is run in a Win32 environment, so Unix like commands will not
1600 work unless you have installed and properly configured Cygwin in addition
1601 to and separately from \bacula{}.
1602
1603 The System \texttt{\%Path\%} will be searched for the command. (under the
1604 environment variable dialog you have have both System Environment and
1605 User Environment, we believe that only the System environment will be
1606 available to \btool{bacula-fd}, if it is running as a service.)
1607
1608 System environment variables can be referenced with \texttt{\%var\%} and
1609 used as either part of the command name or arguments.
1610
1611 So if you have a script in the \bacula{} \bdirectoryname{\textbackslash{}bin} directory then the following lines
1612 should work fine:
1613
1614 \begin{bVerbatim}
1615 Client Run Before Job = systemstate
1616 or
1617 Client Run Before Job = systemstate.bat
1618 or
1619 Client Run Before Job = "systemstate"
1620 or
1621 Client Run Before Job = "systemstate.bat"
1622 or
1623 ClientRunBeforeJob = "\"C:/Program Files/Bacula/systemstate.bat\""
1624 \end{bVerbatim}
1625
1626 The outer set of quotes is removed when the configuration file is parsed.
1627 You need to escape the inner quotes so that they are there when the code
1628 that parses the command line for execution runs so it can tell what the
1629 program name is.
1630
1631
1632 \begin{bVerbatim}
1633 ClientRunBeforeJob = "\"C:/Program Files/Software
1634 Vendor/Executable\" /arg1 /arg2 \"foo bar\""
1635 \end{bVerbatim}
1636
1637 The special characters
1638 \begin{bVerbatim}
1639 &<>()@^|
1640 \end{bVerbatim}
1641 will need to be quoted,
1642 if they are part of a filename or argument.
1643
1644 If someone is logged in, a blank ``command'' window running the commands
1645 will be present during the execution of the command.
1646
1647 Some Suggestions from Phil Stracchino for running on Win32 machines with
1648 the native Win32 File daemon:
1649
1650 \begin{benumerate}
1651 \item You might want the ClientRunBeforeJob directive to specify a \bfilename{.bat}
1652 file which runs the actual client-side commands, rather than trying
1653 to run (for example) \btool{regedit /e} directly.
1654 \item The batch file should explicitly ``\texttt{exit 0}'' on successful completion.
1655 \item The path to the batch file should be specified in Unix form:
1656 \begin{bVerbatim}
1657 ClientRunBeforeJob = "c:/bacula/bin/systemstate.bat"
1658 \end{bVerbatim}
1659 rather than DOS/Windows form:
1660 \begin{bVerbatim}
1661 ClientRunBeforeJob = "c:\bacula\bin\systemstate.bat" # INCORRECT
1662 \end{bVerbatim}
1663 \end{benumerate}
1664
1665 For Win32, please note that there are certain limitations:
1666 \begin{bVerbatim}
1667 ClientRunBeforeJob = "C:/Program Files/Bacula/bin/pre-exec.bat"
1668 \end{bVerbatim}
1669
1670 Lines like the above do not work because there are limitations of
1671 \btool{cmd.exe} that is used to execute the command.
1672 \bacula{} prefixes the string you supply with \btool{cmd.exe /c }. To test that
1673 your command works you should type \btool{cmd /c "C:/Program Files/test.exe"} at a
1674 cmd prompt and see what happens. Once the command is correct insert a
1675 backslash (\textbackslash{}) before each double quote ("), and
1676 then put quotes around the whole thing when putting it in
1677 the director's configuration file. You either need to have only one set of quotes
1678 or else use the short name and don't put quotes around the command path.
1679
1680 Below is the output from cmd's help as it relates to the command line
1681 passed to the \texttt{/c} option.
1682
1683
1684 If \texttt{/C} or \texttt{/K} is specified, then the remainder of the command line after
1685 the switch is processed as a command line, where the following logic is
1686 used to process quote (") characters:
1687
1688 \begin{benumerate}
1689 \item If all of the following conditions are met, then quote characters
1690 on the command line are preserved:
1691 \begin{bitemize}
1692 \item no \texttt{/S} switch.
1693 \item exactly two quote characters.
1694 \item no special characters between the two quote characters,
1695 where special is one of:
1696 \begin{bVerbatim}
1697 &<>()@^|
1698 \end{bVerbatim}
1699 \item there are one or more whitespace characters between the
1700 the two quote characters.
1701 \item the string between the two quote characters is the name
1702 of an executable file.
1703 \end{bitemize}
1704
1705 \item Otherwise, old behavior is to see if the first character is
1706 a quote character and if so, strip the leading character and
1707 remove the last quote character on the command line, preserving
1708 any text after the last quote character.
1709 \end{benumerate}
1710
1711
1712 The following example of the use of the Client Run Before Job directive was
1713 submitted by a user:
1714
1715
1716 You could write a shell script to back up a DB2 database to a FIFO. The shell
1717 script is:
1718
1719 \begin{bVerbatim}
1720 #!/bin/sh
1721 # ===== backupdb.sh
1722 DIR=/u01/mercuryd
1723
1724 mkfifo $DIR/dbpipe
1725 db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING &
1726 sleep 1
1727 \end{bVerbatim}
1728
1729 The following line in the Job resource in the \bfilename{bacula-dir.conf} file:
1730 \begin{bVerbatim}
1731 Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t' '%l'\""
1732 \end{bVerbatim}
1733
1734 When the job is run, you will get messages from the output of the script
1735 stating that the backup has started. Even though the command being run is
1736 backgrounded with \&, the job will block until the \btool{db2 BACKUP DATABASE}
1737 command, thus the backup stalls.
1738
1739 To remedy this situation, the ``db2 BACKUP DATABASE'' line should be changed to
1740 the following:
1741
1742 \begin{bVerbatim}
1743 db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log 2>&1 < /dev/null &
1744 \end{bVerbatim}
1745
1746 It is important to redirect the input and outputs of a backgrounded command to
1747 \bdirectoryname{/dev/null} to prevent the script from blocking.
1748
1749 \bwebdoc{Director:Job:RunBeforeJob}
1750 \item [Run Before Job = \bbracket{command}]
1751 \index[dir]{Run Before Job}
1752 \index[dir]{Directive!Run Before Job}
1753 \index[dir]{Directive!Run Before Job}
1754 The specified \bbracket{command} is run as an external program prior to running the
1755 current Job. This directive is not required, but if it is defined, and if the
1756 exit code of the program run is non-zero, the current \bacula{} job will be
1757 canceled.
1758
1759 \begin{bVerbatim}
1760 Run Before Job = "echo test"
1761 \end{bVerbatim}
1762 it's equivalent to :
1763 \begin{bVerbatim}
1764 RunScript {
1765 Command = "echo test"
1766 RunsOnClient = No
1767 RunsWhen = Before
1768 }
1769 \end{bVerbatim}
1770
1771 Lutz Kittler has pointed out that using the RunBeforeJob directive can be a
1772 simple way to modify your schedules during a holiday. For example, suppose
1773 that you normally do Full backups on Fridays, but Thursday and Friday are
1774 holidays. To avoid having to change tapes between Thursday and Friday when
1775 no one is in the office, you can create a RunBeforeJob that returns a
1776 non-zero status on Thursday and zero on all other days. That way, the
1777 Thursday job will not run, and on Friday the tape you inserted on Wednesday
1778 before leaving will be used.
1779
1780 \bwebdoc{Director:Job:RunAfterJob}
1781 \item [Run After Job = \bbracket{Command}]
1782 \index[dir]{Run After Job}
1783 \index[dir]{Directive!Run After Job}
1784 The specified \bbracket{Command} is run as an external program if the current
1785 job terminates normally (without error or without being canceled). This
1786 directive is not required. If the exit code of the program run is
1787 non-zero, \bacula{} will print a warning message. Before submitting the
1788 specified command to the operating system, \bacula{} performs character
1789 substitution as described above for the \bdirectivename{RunScript} directive.
1790
1791 An example of the use of this directive is given in the
1792 \bxlink{Tips}{blb:JobNotification}{problems}{chapter} of the \bproblemman{}.
1793
1794 See the \textbf{Run After Failed Job} if you
1795 want to run a script after the job has terminated with any
1796 non-normal status.
1797
1798 \bwebdoc{Director:Job:RunAfterJob}
1799 \item [Run After Failed Job = \bbracket{Command}]
1800 \index[dir]{Run After Job}
1801 \index[dir]{Directive!Run After Job}
1802 The specified \bbracket{Command} is run as an external program after the current
1803 job terminates with any error status. This directive is not required. The
1804 command string must be a valid program name or name of a shell script. If
1805 the exit code of the program run is non-zero, \bacula{} will print a
1806 warning message. Before submitting the specified command to the
1807 operating system, \bacula{} performs character substitution as described above
1808 for the \bdirectivename{RunScript} directive. Note, if you wish that your script
1809 will run regardless of the exit status of the Job, you can use this :
1810 \begin{bVerbatim}
1811 RunScript {
1812 Command = "echo test"
1813 RunsWhen = After
1814 RunsOnFailure = yes
1815 RunsOnClient = no
1816 RunsOnSuccess = yes # default, you can drop this line
1817 }
1818 \end{bVerbatim}
1819
1820 An example of the use of this directive is given in the
1821 \bxlink{Tips}{blb:JobNotification}{problems}{chapter} of the \bproblemman{}.
1822
1823
1824 \bwebdoc{Director:Job:ClientRunBeforeJob}
1825 \item [Client Run Before Job = \bbracket{Command}]
1826 \index[dir]{Client Run Before Job}
1827 \index[dir]{Directive!Client Run Before Job}
1828
1829 This directive is the same as \bdirectivename{Run Before Job} except that the program is
1830 run on the client machine. The same restrictions apply to Unix systems as
1831 noted above for the \bdirectivename{RunScript}. \bdirectivename{ClientRunBeforeJob} can be used
1832 with \bjobtype{Backup} and \bjobtype{Restore} jobs.
1833
1834 \bwebdoc{Director:Job:ClientRunAfterJob}
1835 \item [Client Run After Job = \bbracket{Command}]
1836 \index[dir]{Client Run After Job}
1837 \index[dir]{Directive!Client Run After Job}
1838 The specified \bbracket{Command} is run on the client machine as soon
1839 as data spooling is complete in order to allow restarting applications
1840 on the client as soon as possible. \bdirectivename{ClientRunBeforeJob} can be used
1841 with Backup and Restore jobs.
1842
1843 Note, please see the notes above in \bdirectivename{RunScript}
1844 concerning Windows clients.
1845
1846 \bwebdoc{Director:Job:RerunFailedLevels}
1847 \item [Rerun Failed Levels = \byesorno{}]
1848 \index[dir]{Rerun Failed Levels}
1849 \index[dir]{Directive!Rerun Failed Levels}
1850 If this directive is set to \bvalue{yes} (default \bdefaultvalue{no}), and \bacula{} detects that
1851 a previous job at a higher level (i.e. Full or Differential) has failed,
1852 the current job level will be upgraded to the higher level. This is
1853 particularly useful for Laptops where they may often be unreachable, and if
1854 a prior Full save has failed, you wish the very next backup to be a Full
1855 save rather than whatever level it is started as.
1856
1857 There are several points that must be taken into account when using this
1858 directive: first, a failed job is defined as one that has not terminated
1859 normally, which includes any running job of the same name (you need to
1860 ensure that two jobs of the same name do not run simultaneously);
1861 secondly, the \bdirectivename{Ignore FileSet Changes} directive is not considered
1862 when checking for failed levels, which means that any FileSet change will
1863 trigger a rerun.
1864
1865 \bwebdoc{Director:Job:SpoolData}
1866 \item [Spool Data = \byesorno{}]
1867 \index[dir]{Spool Data}
1868 \index[dir]{Directive!Spool Data}
1869
1870 If this directive is set to \bvalue{yes} (default \bdefaultvalue{no}), the Storage daemon will
1871 be requested to spool the data for this Job to disk rather than write it
1872 directly to the Volume (normally a tape).
1873
1874 Thus the data is written in large blocks to the Volume rather than small
1875 blocks. This directive is particularly useful when running multiple
1876 simultaneous backups to tape. Once all the data arrives or the spool
1877 files' maximum sizes are reached, the data will be despooled and written
1878 to tape.
1879
1880 Spooling data prevents interleaving date from several job and reduces or
1881 eliminates tape drive stop and start commonly known as ``shoe-shine''.
1882
1883 We don't recommend using this option if you are writing to a disk file
1884 using this option will probably just slow down the backup jobs.
1885
1886 NOTE: When this directive is set to yes, Spool Attributes is also
1887 automatically set to yes.
1888
1889 \bwebdoc{Director:Job:SpoolAttributes}
1890 \item [Spool Attributes = \byesorno{}]
1891 \index[dir]{Spool Attributes}
1892 \index[dir]{Directive!Spool Attributes}
1893 \index[dir]{slow}
1894 \index[general]{slow}
1895 \index[dir]{Backups!slow}
1896 \index[general]{Backups!slow}
1897
1898 The default is set to \bdefaultvalue{yes}, the Storage daemon will buffer the File
1899 attributes and Storage coordinates to a temporary file in the Working
1900 Directory, then when writing the Job data to the tape is completed, the
1901 attributes and storage coordinates will be sent to the Director.
1902 If set to \bvalue{no} the File attributes are sent by the Storage daemon to the
1903 Director as they are stored on tape.
1904
1905 NOTE: When Spool Data is set to yes, Spool Attributes is also
1906 automatically set to yes.
1907
1908 \bwebdoc{Director:Job:SpoolSize}
1909 \item [SpoolSize={\it bytes}]
1910 \index[dir]{SpoolSize}
1911 \index[dir]{Directive!SpoolSize}
1912 where the bytes specify the maximum spool size for this job.
1913 The default is take from Device Maximum Spool Size limit.
1914 This directive is available only in \bacula{} version 2.3.5 or
1915 later.
1916
1917
1918 \bwebdoc{Director:Job:Where}
1919 \item [Where = \bbracket{directory}]
1920 \index[dir]{Where}
1921 \index[dir]{Directive!Where}
1922 This directive applies only to a Restore job and specifies a prefix to
1923 the directory name of all files being restored. This permits files to
1924 be restored in a different location from which they were saved. If \bdirectivename{Where}
1925 is not specified or is set to slash (\bdirectoryname{/}), the files will
1926 be restored to their original location. By default, we have set \bdirectivename{Where}
1927 in the example configuration files to be \bdirectoryname{/tmp/bacula-restores}.
1928 This is to prevent accidental overwriting of your files.
1929
1930 \label{blb:confaddprefix}
1931 \bwebdoc{Director:Job:AddPrefix}
1932 \item [Add Prefix = \bbracket{directory}]
1933 \index[dir]{AddPrefix}
1934 \index[dir]{Directive!AddPrefix}
1935 This directive applies only to a Restore job and specifies a prefix to the
1936 directory name of all files being restored. This will use
1937 \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8 or later.
1938
1939 \bwebdoc{Director:Job:AddSuffix}
1940 \item [Add Suffix = \bbracket{extention}]
1941 \index[dir]{AddSuffix}
1942 \index[dir]{Directive!AddSuffix}
1943 This directive applies only to a Restore job and specifies a suffix to all
1944 files being restored. This will use \bilink{File Relocation}{blb:filerelocation}
1945 feature implemented in \bacula{} 2.1.8 or later.
1946
1947 Using \texttt{Add Suffix=.old}, \bfilename{/etc/passwd} will be restored to
1948 \bfilename{/etc/passwsd.old}
1949
1950 \bwebdoc{Director:Job:StripPrefix}
1951 \item [Strip Prefix = \bbracket{directory}]
1952 \index[dir]{StripPrefix}
1953 \index[dir]{Directive!StripPrefix}
1954 This directive applies only to a Restore job and specifies a prefix to remove
1955 from the directory name of all files being restored. This will use the
1956 \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8
1957 or later.
1958
1959 Using \texttt{Strip Prefix=/etc}, \bfilename{/etc/passwd} will be restored to
1960 \bfilename{/passwd}
1961
1962 Under Windows, if you want to restore \bfilename{c:/files} to \bfilename{d:/files},
1963 you can use :
1964
1965 \begin{bVerbatim}
1966 Strip Prefix = c:
1967 Add Prefix = d:
1968 \end{bVerbatim}
1969
1970 \bwebdoc{Director:Job:RegexWhere}
1971 \item [RegexWhere = \bbracket{expressions}]
1972 \index[dir]{RegexWhere}
1973 \index[dir]{Directive!RegexWhere}
1974 This directive applies only to a Restore job and specifies a regex filename
1975 manipulation of all files being restored. This will use
1976 \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8 or later.
1977
1978 For more informations about how use this option, see
1979 \bilink{this}{useregexwhere}.
1980
1981 \bwebdoc{Director:Job:Replace}
1982 \item [Replace = \bbracket{replace-option}]
1983 \index[dir]{Replace}
1984 \index[dir]{Directive!Replace}
1985 This directive applies only to a Restore job and specifies what happens
1986 when \bacula{} wants to restore a file or directory that already exists.
1987 You have the following options for \bbracket{replace-option}:
1988
1989 \bwebdoc{Director:Job:RestoreClient}
1990 \item [RestoreClient = \bbracket{client-resource-name}]
1991 \index[dir]{RestoreClient}
1992 \index[dir]{Directive!RestoreClient}
1993
1994 The RestoreClient directive specifies the default Client (File Daemon) that
1995 will be used with the restore job. If this directive is not set then a
1996 default restore client will be set to a backup client as usual. It is
1997 possible to define a dedicated restore job and run an automatic (scheduled)
1998 restore tests of your backups which will be redirected to the restore test
1999 Client.
2000
2001 \begin{bdescription}
2002
2003 \item [always]
2004 \index[dir]{always}
2005 when the file to be restored already exists, it is deleted and then
2006 replaced by the copy that was backed up. This is the default value.
2007
2008 \item [ifnewer]
2009 \index[dir]{ifnewer}
2010 if the backed up file (on tape) is newer than the existing file, the
2011 existing file is deleted and replaced by the back up.
2012
2013 \item [ifolder]
2014 \index[dir]{ifolder}
2015 if the backed up file (on tape) is older than the existing file, the
2016 existing file is deleted and replaced by the back up.
2017
2018 \item [never]
2019 \index[dir]{never}
2020 if the backed up file already exists, \bacula{} skips restoring this file.
2021 \end{bdescription}
2022
2023 \bwebdoc{Director:Job:PrefixLinks}
2024 \item [Prefix Links=\byesorno{}]
2025 \index[dir]{Prefix Links}
2026 \index[dir]{Directive!Prefix Links}
2027 If a \bdirectoryname{Where} path prefix is specified for a recovery job, apply it
2028 to absolute links as well. The default is \bdefaultvalue{no}. When set to \bvalue{yes}
2029 then while restoring files to an alternate directory, any absolute
2030 soft links will also be modified to point to the new alternate
2031 directory. Normally this is what is desired -- i.e. everything is self
2032 consistent. However, if you wish to later move the files to their
2033 original locations, all files linked with absolute names will be broken.
2034
2035 \bwebdoc{Director:Job:MaximumConcurrentJobs}
2036 \item [Maximum Concurrent Jobs = \bbracket{number}]
2037 \index[dir]{Maximum Concurrent Jobs}
2038 \index[dir]{Directive!Maximum Concurrent Jobs}
2039 where \bbracket{number} is the maximum number of Jobs from the current
2040 Job resource that can run concurrently. Note, this directive limits
2041 only Jobs with the same name as the resource in which it appears. Any
2042 other restrictions on the maximum concurrent jobs such as in the
2043 Director, Client, or Storage resources will also apply in addition to
2044 the limit specified here. The default is set to \bdefaultvalue{1}, but you may set it
2045 to a larger number. We strongly recommend that you read the WARNING
2046 documented under \bilink{ Maximum Concurrent Jobs}{blb:DirMaxConJobs} in the
2047 Director's resource.
2048
2049 \bwebdoc{Director:Job:RescheduleOnError}
2050 \item [Reschedule On Error = \byesorno{}]
2051 \index[dir]{Reschedule On Error}
2052 \index[dir]{Directive!Reschedule On Error}
2053 If this directive is enabled, and the job terminates in error, the job
2054 will be rescheduled as determined by the \bdirectivename{Reschedule Interval} and
2055 \bdirectivename{Reschedule Times} directives. If you cancel the job, it will not
2056 be rescheduled. The default is \bdefaultvalue{no} (i.e. the job will not be
2057 rescheduled).
2058
2059 This specification can be useful for portables, laptops, or other
2060 machines that are not always connected to the network or switched on.
2061
2062 \bwebdoc{Director:Job:RescheduleIncompleteJobs}
2063 \item [Reschedule Incomplete Jobs = \byesorno{}]
2064 \index[dir]{Reschedule Incomplete Jobs}
2065 \index[dir]{Directive!Reschedule Incomplete Jobs}
2066
2067 If this directive is enabled, and the job terminates in incomplete status,
2068 the job will be rescheduled as determined by the \bdirectivename{Reschedule Interval}
2069 and \bdirectivename{Reschedule Times} directives. If you cancel the job, it will not
2070 be rescheduled. The default is \bdefaultvalue{yes} (i.e. Incomplete jobs will be
2071 rescheduled).
2072
2073 \bwebdoc{Director:Job:RescheduleInterval}
2074 \item [Reschedule Interval = \bbracket{time-specification}]
2075 \index[dir]{Reschedule Interval}
2076 \index[dir]{Directive!Reschedule Interval}
2077 If you have specified \bvalueddirective{Reschedule On Error}{yes} and the job
2078 terminates in error, it will be rescheduled after the interval of time
2079 specified by \bbracket{time-specification}. See
2080 \bilink{the time specification formats}{blb:Time} in the Configure chapter for details of
2081 time specifications. If no interval is specified, the job will not be
2082 rescheduled on error. The default Reschedule Interval
2083 is \bdefaultvalue{30 minutes} (\bdefaultvalue{1800 seconds}).
2084
2085 \bwebdoc{Director:Job:RescheduleTimes}
2086 \item [Reschedule Times = \bbracket{count}]
2087 \index[dir]{Reschedule Times}
2088 \index[dir]{Directive!Reschedule Times}
2089 This directive specifies the maximum number of times to reschedule the
2090 job. If it is set to \bdefaultvalue{zero} (\bdefaultvalue{0}, the default) the job will be rescheduled an
2091 indefinite number of times.
2092
2093 \bwebdoc{Director:Job:AllowIncompleteJobs}
2094 \item [Allow Incomplete Jobs = \byesorno{}]
2095 \index[dir]{Allow Incomplete Jobs}
2096 \index[dir]{Directive!Allow Incomplete Jobs}
2097
2098 If this directive is disabled, and the job terminates in incomplete status,
2099 the data of the job will be discarded and the job will be marked in error. Bacula
2100 will treat this job like a regular job in error.
2101 The default is \bdefaultvalue{yes}.
2102
2103 \bwebdoc{Director:Job:AllowDuplicateJobs}
2104 \item [Allow Duplicate Jobs = \byesorno{}]
2105 \index[general]{Allow Duplicate Jobs}
2106 A duplicate job in the sense we use it here means a second or subsequent job
2107 with the same name starts. This happens most frequently when the first job
2108 runs longer than expected because no tapes are available. The default is \bdefaultvalue{yes}.
2109
2110 \bimageH[0.8\linewidth]{duplicate-real}{Allow Duplicate Jobs usage}{blb:fig:allowduplicatejobs}
2111
2112
2113 If this directive is enabled duplicate jobs will be run. If
2114 the directive is set to \bvalue{no} then only one job of a given name
2115 may run at one time, and the action that \bacula{} takes to ensure only
2116 one job runs is determined by the other directives (see below).
2117
2118 If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and two jobs
2119 are present and none of the three directives given below permit
2120 cancelling a job, then the current job (the second one started)
2121 will be cancelled.
2122
2123
2124
2125
2126 \bwebdoc{Director:Job:AllowHigherDuplicates}
2127 \item [Allow Higher Duplicates = \byesorno{}]
2128 \index[general]{Allow Higher Duplicates}
2129 This directive was implemented in version 5.0.0, but does not work
2130 as expected. If used, it should always be set to no. In later versions
2131 of \bacula{} the directive is disabled (disregarded).
2132
2133
2134 \bwebdoc{Director:Job:CancelLowerLevelDuplicates}
2135 \item [Cancel Lower Level Duplicates = \byesorno{}]
2136 \index[general]{Cancel Lower Level Duplicates}
2137 If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and this
2138 directive is set to \bvalue{yes}, \bacula{} will choose between duplicated
2139 jobs the one with the highest level. For example, it will cancel a
2140 previous Incremental to run a Full backup. It works only for Backup
2141 jobs. The default is \bdefaultvalue{no}. If the levels of the duplicated
2142 jobs are the same, nothing is done and the other
2143 Cancel XXX Duplicate directives will be examined.
2144
2145 \bwebdoc{Director:Job:CancelQueuedDuplicates}
2146 \item [Cancel Queued Duplicates = \byesorno{}]
2147 \index[general]{Cancel Queued Duplicates}
2148 If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and
2149 if this directive is set to \bvalue{yes} any job that is
2150 already queued to run but not yet running will be canceled.
2151 The default is \bdefaultvalue{no}.
2152
2153 \bwebdoc{Director:Job:CancelRunningDuplicates}
2154 \item[Cancel Running Duplicates = \byesorno{}]
2155 \index[general]{Cancel Running Duplicates}
2156 If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and
2157 if this directive is set to \bvalue{yes} any job that is already running
2158 will be canceled. The default is \bdefaultvalue{no}.
2159
2160
2161 %%\item[DuplicateJobProximity = \bbracket{time-specification}]
2162 %%\index[general]{Duplicate Job Proximity}
2163 %% This directive permits to determine if two jobs are really duplicated.
2164 %% If the first one is running for long time, this is probably not a good
2165 %% idea to cancel it.
2166
2167 \bwebdoc{Director:Job:Run}
2168 \item [Run = \bbracket{job-name}]
2169 \index[dir]{Run}
2170 \index[dir]{Directive!Run}
2171 \index[dir]{Clone a Job}
2172 The \bdirectivename{Run} directive (not to be confused with the Run option in a
2173 Schedule) allows you to start other jobs or to clone jobs. By using the
2174 cloning keywords (see below), you can backup
2175 the same data (or almost the same data) to two or more drives
2176 at the same time. The \bbracket{job-name} is normally the same name
2177 as the current Job resource (thus creating a clone). However, it
2178 may be any Job name, so one job may start other related jobs.
2179
2180 The part after the equal sign must be enclosed in double quotes,
2181 and can contain any string or set of options (overrides) that you
2182 can specify when entering the \bcommandname{run} command from the console. For
2183 example \textbf{storage=\acs{DDS}-4 \ldots{}}. In addition, there are two special
2184 keywords that permit you to clone the current job. They are \textbf{level=\%l}
2185 and \textbf{since=\%s}. The \%l in the level keyword permits
2186 entering the actual level of the current job and the \%s in the since
2187 keyword permits putting the same time for comparison as used on the
2188 current job. Note, in the case of the since keyword, the \%s must be
2189 enclosed in double quotes, and thus they must be preceded by a backslash
2190 since they are already inside quotes. For example:
2191
2192 \begin{bVerbatim}
2193 run = "Nightly-backup level=%l since=\"%s\" storage=DDS-4"
2194 \end{bVerbatim}
2195
2196 A cloned job will not start additional clones, so it is not
2197 possible to recurse.
2198
2199 Please note that all cloned jobs, as specified in the Run directives are
2200 submitted for running before the original job is run (while it is being
2201 initialized). This means that any clone job will actually start before
2202 the original job, and may even block the original job from starting
2203 until the original job finishes unless you allow multiple simultaneous
2204 jobs. Even if you set a lower priority on the clone job, if no other
2205 jobs are running, it will start before the original job.
2206
2207 If you are trying to prioritize jobs by using the clone feature (Run
2208 directive), you will find it much easier to do using a RunScript
2209 resource, or a RunBeforeJob directive.
2210
2211
2212 \bwebdoc{Director:Job:Priority}
2213 \item [Priority = \bbracket{number}]
2214 \index[dir]{Priority}
2215 \index[dir]{Directive!Priority}
2216 \label{blb:Priority}
2217 This directive permits you to control the order in which your jobs will
2218 be run by specifying a positive non-zero number. The higher the number,
2219 the lower the job priority. Assuming you are not running concurrent jobs,
2220 all queued jobs of priority 1 will run before queued jobs of priority 2
2221 and so on, regardless of the original scheduling order.
2222
2223 The priority only affects waiting jobs that are queued to run, not jobs
2224 that are already running. If one or more jobs of priority 2 are already
2225 running, and a new job is scheduled with priority 1, the currently
2226 running priority 2 jobs must complete before the priority 1 job is
2227 run, unless \bdirectivename{Allow Mixed Priority} is set.
2228
2229 The default priority is \bdefaultvalue{10}.
2230
2231 If you want to run concurrent jobs you should
2232 keep these points in mind:
2233
2234 \begin{bitemize}
2235 \item See \bxlink{Running Concurrent Jobs}{blb:ConcurrentJobs}{problems}{section} on how to setup
2236 concurrent jobs in the \bproblemman{}.
2237
2238 \item \bacula{} concurrently runs jobs of only one priority at a time. It
2239 will not simultaneously run a priority 1 and a priority 2 job.
2240
2241 \item If \bacula{} is running a priority 2 job and a new priority 1 job is
2242 scheduled, it will wait until the running priority 2 job terminates even
2243 if the \bdirectivename{Maximum Concurrent Jobs} settings would otherwise allow two jobs
2244 to run simultaneously.
2245
2246 \item Suppose that bacula is running a priority 2 job and a new priority 1
2247 job is scheduled and queued waiting for the running priority 2 job to
2248 terminate. If you then start a second priority 2 job, the waiting
2249 priority 1 job will prevent the new priority 2 job from running
2250 concurrently with the running priority 2 job. That is: as long as there
2251 is a higher priority job waiting to run, no new lower priority jobs will
2252 start even if the Maximum Concurrent Jobs settings would normally allow
2253 them to run. This ensures that higher priority jobs will be run as soon
2254 as possible.
2255 \end{bitemize}
2256
2257 If you have several jobs of different priority, it may not best to start
2258 them at exactly the same time, because \bacula{} must examine them one at a
2259 time. If by \bacula{} starts a lower priority job first, then it will run
2260 before your high priority jobs. If you experience this problem, you may
2261 avoid it by starting any higher priority jobs a few seconds before lower
2262 priority ones. This insures that \bacula{} will examine the jobs in the
2263 correct order, and that your priority scheme will be respected.
2264 \label{blb:AllowMixedPriority}
2265
2266 \bwebdoc{Director:Job:AllowMixedPriority}
2267 \item [Allow Mixed Priority = \byesorno{}]
2268 \index[dir]{Allow Mixed Priority}
2269 This directive is only implemented in version 2.5 and later. When
2270 set to \bvalue{yes} (default \bdefaultvalue{no}), this job may run even if lower
2271 priority jobs are already running. This means a high priority job
2272 will not have to wait for other jobs to finish before starting.
2273 The scheduler will only mix priorities when all running jobs have
2274 this set to true.
2275
2276 Note that only higher priority jobs will start early. Suppose the
2277 director will allow two concurrent jobs, and that two jobs with
2278 priority 10 are running, with two more in the queue. If a job with
2279 priority 5 is added to the queue, it will be run as soon as one of
2280 the running jobs finishes. However, new priority 10 jobs will not
2281 be run until the priority 5 job has finished.
2282 %%\label{blb:WritePartAfterJob}
2283 %%
2284 %%\bwebdoc{Director:Job:WritePartAfterJob}
2285 %%\item [Write Part After Job = \byesorno{}]
2286 %%\index[dir]{Write Part After Job}
2287 %%\index[dir]{Directive!Write Part After Job}
2288 %% This directive is only implemented in version 1.37 and later.
2289 %% If this directive is set to \bvalue{yes} (default \bdefaultvalue{no}), a new part file
2290 %% will be created after the job is finished.
2291 %%
2292 %% It should be set to \bvalue{yes} when writing to devices that require mount
2293 %% (for example DVD), so you are sure that the current part, containing
2294 %% this job's data, is written to the device, and that no data is left in
2295 %% the temporary file on the hard disk. However, on some media, like DVD+R
2296 %% and DVD-R, a lot of space (about 10Mb) is lost every time a part is
2297 %% written. So, if you run several jobs each after another, you could set
2298 %% this directive to \bvalue{no} for all jobs, except the last one, to avoid
2299 %% wasting too much space, but to ensure that the data is written to the
2300 %% medium when all jobs are finished.
2301 %%
2302 %% This directive is ignored with tape and FIFO devices.
2303
2304 \end{bdescription}
2305
2306 The following is an example of a valid Job resource definition:
2307
2308 \begin{bVerbatim}
2309 Job {
2310 Name = "Minou"
2311 Type = Backup
2312 Level = Incremental # default
2313 Client = Minou
2314 FileSet="Minou Full Set"
2315 Storage = DLTDrive
2316 Pool = Default
2317 Schedule = "MinouWeeklyCycle"
2318 Messages = Standard
2319 }
2320 \end{bVerbatim}
2321
2322 \label{blb:JobDefsResource}
2323 \section{The JobDefs Resource}
2324 \index[general]{JobDefs Resource}
2325 \index[general]{Resource!JobDefs}
2326
2327 The JobDefs resource permits all the same directives that can appear in a Job
2328 resource. However, a JobDefs resource does not create a Job, rather it can be
2329 referenced within a Job to provide defaults for that Job. This permits you to
2330 concisely define several nearly identical Jobs, each one referencing a JobDefs
2331 resource which contains the defaults. Only the changes from the defaults need to
2332 be mentioned in each Job.
2333
2334 \label{blb:ScheduleResource}
2335 \section{The Schedule Resource}
2336 \index[general]{Resource!Schedule}
2337 \index[general]{Schedule Resource}
2338
2339 The Schedule resource provides a means of automatically scheduling a Job as
2340 well as the ability to override the default Level, Pool, Storage and Messages
2341 resources. If a Schedule resource is not referenced in a Job, the Job can only
2342 be run manually. In general, you specify an action to be taken and when.
2343
2344 \begin{bdescription}
2345
2346 \item [Schedule]
2347 \index[dir]{Schedule}
2348 \index[dir]{Directive!Schedule}
2349 Start of the Schedule directives. No \bresourcename{Schedule} resource is
2350 required, but you will need at least one if you want Jobs to be
2351 automatically started.
2352
2353 \bwebdoc{Director:Schedule:Name}
2354 \item [Name = \bbracket{name}]
2355 \index[dir]{Name}
2356 \index[dir]{Directive!Name}
2357 The name of the schedule being defined. The Name directive is required.
2358
2359 \bwebdoc{Director:Schedule:Enabled}
2360 \item [Enabled = \byesorno{}]
2361 \index[dir]{Enabled}
2362 \index[dir]{Directive!Enabled}
2363 This directive allows you to enable or disable the \bresourcename{Schedule} resource.
2364
2365 \bwebdoc{Director:Schedule:Run}
2366 \item [Run = \bbracket{Job-overrides} \bbracket{Date-time-specification}]
2367 \index[dir]{Run}
2368 \index[dir]{Directive!Run}
2369 The Run directive defines when a Job is to be run, and what overrides if
2370 any to apply. You may specify multiple \bdirectivename{Run} directives within a
2371 \bresourcename{Schedule} resource. If you do, they will all be applied (i.e.
2372 multiple schedules). If you have two \bdirectivename{Run} directives that start at
2373 the same time, two Jobs will start at the same time (well, within one
2374 second of each other).
2375
2376 The \textbf{Job-overrides} permit overriding the Level, the Storage, the
2377 Messages, and the Pool specifications provided in the Job resource. In
2378 addition, the \bdirectivename{FullPool}, the \bdirectivename{IncrementalPool},
2379 and the \bdirectivename{DifferentialPool} specifications permit overriding
2380 the Pool specification according to what backup Job Level is in effect.
2381
2382 By the use of overrides, you may customize a particular Job. For
2383 example, you may specify a Messages override for your Incremental
2384 backups that outputs messages to a log file, but for your weekly or
2385 monthly Full backups, you may send the output by email by using a
2386 different Messages override.
2387
2388 \textbf{Job-overrides} are specified as: \textbf{keyword=value} where the
2389 keyword is \bkeyword{Level}, \bkeyword{Storage}, \bkeyword{Messages}, \bkeyword{Pool},
2390 \bkeyword{FullPool}, \bkeyword{DifferentialPool},
2391 or \bkeyword{IncrementalPool}, and the \bvalue{value} is as defined on the respective
2392 directive formats for the Job resource. You may specify multiple \textbf{Job-overrides}
2393 on one \bdirectivename{Run} directive by separating them with one or
2394 more spaces or by separating them with a trailing comma. For example:
2395
2396 \bwebdoc{Director:Schedule:End}
2397 \begin{bdescription}
2398
2399 \item [Level=Full]
2400 \index[dir]{Level}
2401 \index[dir]{Directive!Level}
2402 is all files in the FileSet whether or not they have changed.
2403
2404 \item [Level=Incremental]
2405 \index[dir]{Level}
2406 \index[dir]{Directive!Level}
2407 is all files that have changed since the last backup.
2408
2409 \item [Pool=Weekly]
2410 \index[dir]{Pool}
2411 \index[dir]{Directive!Pool}
2412 specifies to use the Pool named \textbf{Weekly}.
2413
2414 \item [Storage=DLT\_Drive]
2415 \index[dir]{Storage}
2416 \index[dir]{Directive!Storage}
2417 specifies to use \textbf{DLT\_Drive} for the storage device.
2418
2419 \item [Messages=Verbose]
2420 \index[dir]{Messages}
2421 \index[dir]{Directive!Messages}
2422 specifies to use the \textbf{Verbose} message resource for the Job.
2423
2424 \item [FullPool=Full]
2425 \index[dir]{FullPool}
2426 \index[dir]{Directive!FullPool}
2427 specifies to use the Pool named \textbf{Full} if the job is a full backup, or
2428 is upgraded from another type to a Full backup.
2429
2430 \item [DifferentialPool=Differential]
2431 \index[dir]{DifferentialPool}
2432 \index[dir]{Directive!DifferentialPool}
2433 specifies to use the Pool named \textbf{Differential} if the job is a
2434 differential backup.
2435
2436 \item [IncrementalPool=Incremental]
2437 \index[dir]{IncrementalPool}
2438 \index[dir]{Directive!IncrementalPool}
2439 specifies to use the Pool named \textbf{Incremental} if the job is an
2440 incremental backup.
2441
2442 \item [Next Pool = \bbracket{pool-specification}]
2443 The \textbf{Next Pool} directive specifies the pool to which Jobs will be
2444 migrated. This directive is used to define the Pool into which
2445 the data will be migrated.
2446
2447 %% \item [WritePartAfterJob=\byesorno{}]
2448 %% \index[dir]{WritePartAfterJob}
2449 %% \index[dir]{Directive!WritePartAfterJob}
2450 %% tells \bacula{} to request the Storage daemon to write the current part
2451 %% file to the device when the job is finished (see
2452 %% \bilink{Write Part After Job directive in the Job resource}{blb:WritePartAfterJob}). Please note,
2453 %% this directive is implemented only in version 1.37 and later. The
2454 %% default is \bdefaultvalue{yes}. We strongly recommend that you keep this set to yes
2455 %% otherwise, when the last job has finished one part will remain in the
2456 %% spool file and restore may or may not work.
2457
2458 \item [Priority = \bbracket{number}]
2459 \index[dir]{Priority}
2460 \index[dir]{Directive!Priority}
2461 This directive permits you to control the order in which your jobs will
2462 be run by specifying a positive non-zero number. The higher the number,
2463 the lower the job priority. Assuming you are not running concurrent jobs,
2464 all queued jobs of priority 1 will run before queued jobs of priority 2
2465 and so on, regardless of the original scheduling order.
2466
2467 The priority only affects waiting jobs that are queued to run, not jobs
2468 that are already running. If one or more jobs of priority 2 are already
2469 running, and a new job is scheduled with priority 1, the currently
2470 running priority 2 jobs must complete before the priority 1 job is
2471 run, unless \bdirectivename{Allow Mixed Priority} is set.
2472
2473 The default priority is \bdefaultvalue{10}.
2474
2475 See \vref{blb:Priority} for more information.
2476
2477 \end{bdescription}
2478 \label{Date-time-specification}
2479 \bbracket{Date-time-specification} determines when the Job is to be run. The
2480 specification is a repetition, and as a default \bacula{} is set to run a job at
2481 the beginning of the hour of every hour of every day of every week of every
2482 month of every year. This is not normally what you want, so you must specify
2483 or limit when you want the job to run. Any specification given is assumed to
2484 be repetitive in nature and will serve to override or limit the default
2485 repetition. This is done by specifying masks or times for the hour, day of the
2486 month, day of the week, week of the month, week of the year, and month when
2487 you want the job to run. By specifying one or more of the above, you can
2488 define a schedule to repeat at almost any frequency you want.
2489
2490 Basically, you must supply a \textbf{month}, \textbf{day}, \textbf{hour}, and \textbf{minute}
2491 the Job is to be run. Of these four items to be specified, \textbf{day}
2492 is special in that you may either specify a day of the month such as \bvalue{1}, \bvalue{2},
2493 \ldots{} \bvalue{31}, or you may specify a day of the week such as \bkeyword{Monday}, \bkeyword{Tuesday}, \ldots{}
2494 \bkeyword{Sunday}. Finally, you may also specify a week qualifier to restrict the
2495 schedule to the \bkeyword{first}, \bkeyword{second}, \bkeyword{third}, \bkeyword{fourth}, \bkeyword{fifth} or \bkeyword{sixth} week of the month.
2496
2497 For example, if you specify only a day of the week, such as \bkeyword{Tuesday} the
2498 Job will be run every hour of every Tuesday of every Month. That is the \bkeyword{month}
2499 and \bkeyword{hour} remain set to the defaults of every month and all
2500 hours.
2501
2502 Note, by default with no other specification, your job will run at the
2503 beginning of every hour. If you wish your job to run more than once in any
2504 given hour, you will need to specify multiple \bdirectivename{Run} specifications each
2505 with a different minute.
2506
2507 The date/time to run the Job can be specified in the following way in
2508 pseudo-\acs{BNF}:
2509
2510 \begin{bVerbatim}
2511 <void-keyword> = on
2512 <at-keyword> = at
2513 <week-keyword> = 1st | 2nd | 3rd | 4th | 5th | 6th | first |
2514 second | third | fourth | fifth
2515 <wday-keyword> = sun | mon | tue | wed | thu | fri | sat |
2516 sunday | monday | tuesday | wednesday |
2517 thursday | friday | saturday
2518 <week-of-year-keyword> = w00 | w01 | ... w52 | w53
2519 <month-keyword> = jan | feb | mar | apr | may | jun | jul |
2520 aug | sep | oct | nov | dec | january |
2521 february | ... | december
2522 <daily-keyword> = daily
2523 <weekly-keyword> = weekly
2524 <monthly-keyword> = monthly
2525 <hourly-keyword> = hourly
2526 <digit> = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0
2527 <number> = <digit> | <digit><number>
2528 <12hour> = 0 | 1 | 2 | ... 12
2529 <hour> = 0 | 1 | 2 | ... 23
2530 <minute> = 0 | 1 | 2 | ... 59
2531 <day> = 1 | 2 | ... 31 | lastday
2532 <time> = <hour>:<minute> |
2533 <12hour>:<minute>am |
2534 <12hour>:<minute>pm
2535 <time-spec> = <at-keyword> <time> |
2536 <hourly-keyword>
2537 <date-keyword> = <void-keyword> <weekly-keyword>
2538 <day-range> = <day>-<day>
2539 <month-range> = <month-keyword>-<month-keyword>
2540 <wday-range> = <wday-keyword>-<wday-keyword>
2541 <range> = <day-range> | <month-range> |
2542 <wday-range>
2543 <date> = <date-keyword> | <day> | <range>
2544 <date-spec> = <date> | <date-spec>
2545 <day-spec> = <day> | <wday-keyword> |
2546 <day> | <wday-range> |
2547 <week-keyword> <wday-keyword> |
2548 <week-keyword> <wday-range> |
2549 <daily-keyword>
2550 <month-spec> = <month-keyword> | <month-range> |
2551 <monthly-keyword>
2552 <date-time-spec> = <month-spec> <day-spec> <time-spec>
2553 \end{bVerbatim}
2554
2555 \end{bdescription}
2556
2557 Note, the Week of Year specification wnn follows the \acs{ISO} standard definition
2558 of the week of the year, where Week 1 is the week in which the first Thursday
2559 of the year occurs, or alternatively, the week which contains the 4th of
2560 January. Weeks are numbered w01 to w53. w00 for \bacula{} is the week that
2561 precedes the first \acs{ISO} week (i.e. has the first few days of the year if any
2562 occur before Thursday). w00 is not defined by the \acs{ISO} specification. A week
2563 starts with Monday and ends with Sunday.
2564
2565 According to the \ac{NIST}, 12am and 12pm are ambiguous and can be defined
2566 to anything. However, 12:01am is the same as 00:01 and 12:01pm is the same
2567 as 12:01, so \bacula{} defines 12am as 00:00 (midnight) and 12pm as 12:00 (noon).
2568 You can avoid this abiguity (confusion) by using 24 hour time specifications (i.e. no
2569 am/pm). This is the definition in \bacula{} version 2.0.3 and later.
2570
2571 An example schedule resource that is named \bvalue{WeeklyCycle} and runs a job
2572 with level full each Sunday at 2:05am and an incremental job Monday through
2573 Saturday at 2:05am is:
2574
2575 \begin{bVerbatim}
2576 Schedule {
2577 Name = "WeeklyCycle"
2578 Run = Level=Full sun at 2:05
2579 Run = Level=Incremental mon-sat at 2:05
2580 }
2581 \end{bVerbatim}
2582
2583
2584 An example of a possible monthly cycle is as follows:
2585
2586 \begin{bVerbatim}
2587 Schedule {
2588 Name = "MonthlyCycle"
2589 Run = Level=Full Pool=Monthly 1st sun at 2:05
2590 Run = Level=Differential 2nd-5th sun at 2:05
2591 Run = Level=Incremental Pool=Daily mon-sat at 2:05
2592 }
2593 \end{bVerbatim}
2594
2595 The first of every month:
2596
2597 \begin{bVerbatim}
2598 Schedule {
2599 Name = "First"
2600 Run = Level=Full on 1 at 2:05
2601 Run = Level=Incremental on 2-31 at 2:05
2602 }
2603 \end{bVerbatim}
2604
2605 The last day of February (28th or 29th), on May 31st and September 30rd at
2606 20:00. In \bcommandname{show schedule} output, \texttt{LastDay is printed as ``31''}
2607 \begin{bVerbatim}
2608 Schedule {
2609 Name = "Last"
2610 Run = Level=Full on lastday Feb, May, Sep at 20:00
2611 }
2612 \end{bVerbatim}
2613
2614
2615 Every 10 minutes:
2616
2617 \begin{bVerbatim}
2618 Schedule {
2619 Name = "TenMinutes"
2620 Run = Level=Full hourly at 0:05
2621 Run = Level=Full hourly at 0:15
2622 Run = Level=Full hourly at 0:25
2623 Run = Level=Full hourly at 0:35
2624 Run = Level=Full hourly at 0:45
2625 Run = Level=Full hourly at 0:55
2626 }
2627 \end{bVerbatim}
2628
2629 \section{Technical Notes on Schedules}
2630 \index[general]{Schedules!Technical Notes on}
2631 \index[general]{Technical Notes on Schedules}
2632
2633 Internally \bacula{} keeps a schedule as a bit mask. There are six masks and a
2634 minute field to each schedule. The masks are hour, day of the month (mday),
2635 month, day of the week (wday), week of the month (wom), and week of the year
2636 (woy). The schedule is initialized to have the bits of each of these masks
2637 set, which means that at the beginning of every hour, the job will run. When
2638 you specify a month for the first time, the mask will be cleared and the bit
2639 corresponding to your selected month will be selected. If you specify a second
2640 month, the bit corresponding to it will also be added to the mask. Thus when
2641 \bacula{} checks the masks to see if the bits are set corresponding to the
2642 current time, your job will run only in the two months you have set. Likewise,
2643 if you set a time (hour), the hour mask will be cleared, and the hour you
2644 specify will be set in the bit mask and the minutes will be stored in the
2645 minute field.
2646
2647 For any schedule you have defined, you can see how these bits are set by doing
2648 a \bcommandname{show schedules} command in the Console program. Please note that the
2649 bit mask is zero based, and Sunday is the first day of the week (bit zero).
2650
2651 \input{fileset}
2652 \input{bsplugins}
2653
2654 \label{blb:ClientResource}
2655 \section{The Client Resource}
2656 \index[general]{Resource!Client}
2657 \index[general]{Client Resource}
2658
2659 The Client resource defines the attributes of the Clients that are served by
2660 this Director; that is the machines that are to be backed up. You will need
2661 one Client resource definition for each machine to be backed up.
2662
2663 \begin{bdescription}
2664
2665 \item [Client (or FileDaemon)]
2666 \index[dir]{Client (or FileDaemon)}
2667 \index[dir]{Directive!Client (or FileDaemon)}
2668 Start of the Client directives.
2669
2670 \bwebdoc{Director:Client:Name}
2671 \item [Name = \bbracket{name}]
2672 \index[dir]{Name}
2673 \index[dir]{Directive!Name}
2674 The client name which will be used in the Job resource directive or in the
2675 console \bcommandname{run} command. This directive is required.
2676
2677 \bwebdoc{Director:Client:Enabled}
2678 \item [Enabled = \byesorno{}]
2679 \index[dir]{Enable}
2680 \index[dir]{Directive!Enable}
2681 This directive allows you to enable or disable the \bresourcename{Client} resource.
2682 If the resource is disabled, the Client will not be used.
2683
2684 \bwebdoc{Director:Client:Address}
2685 \item [Address = \bbracket{address}]
2686 \index[dir]{Address}
2687 \index[dir]{Directive!FD Address}
2688 \index[dir]{File Daemon Address}
2689 \index[dir]{Client Address}
2690 Where the \bbracket{address} is a host name, a fully qualified domain name, or a
2691 network address in dotted quad notation for a \bacula{} File server daemon.
2692 This directive is required.
2693
2694 \bwebdoc{Director:Client:FdPort}
2695 \item [FD Port = \bbracket{port-number}]
2696 \index[dir]{FD Port}
2697 \index[dir]{Directive!FD Port}
2698 Where the \bbracket{port-number} is a port number at which the \bacula{} File server daemon can
2699 be contacted. The default is \bdefaultvalue{9102}.
2700
2701 \bwebdoc{Director:Client:AllowFDConnections}
2702 \item [AllowFDConnections = \byesorno{}]
2703 \index[dir]{AllowFDConnections}
2704 \index[dir]{Directive!AllowFDConnection}
2705
2706 When \bdirectivename{AllowFDConnections} is set to \bvalue{true}, the
2707 Director will accept incoming connections from the Client and will keep the
2708 socket open for a future use. The Director will no longer use the
2709 \bdirectivename{Address} to contact the File Daemon. This configuration is
2710 useful if the Director cannot contact the FileDaemon directly. See
2711 \vref{blb:ConnectToDirector} for more information. The default value is
2712 \bdefaultvalue{no}.
2713
2714 \bwebdoc{Director:Client:Catalog}
2715 \item [Catalog = \bbracket{Catalog-resource-name}]
2716 \index[dir]{Catalog}
2717 \index[dir]{Directive!Catalog}
2718 This specifies the name of the catalog resource to be used for this Client.
2719 This directive is required.
2720
2721 \bwebdoc{Director:Client:Password}
2722 \item [Password = \bbracket{password}]
2723 \index[dir]{Password}
2724 \index[dir]{Directive!Password}
2725 This is the password to be used when establishing a connection with the File
2726 services, so the Client configuration file on the machine to be backed up
2727 must have the same password defined for this Director. This directive is
2728 required. If you have either \btool{/dev/random} or \btool{bc} on your machine,
2729 \bacula{} will generate a random password during the configuration process,
2730 otherwise it will be left blank.
2731
2732 The password is plain text. It is not generated through any special
2733 process, but it is preferable for security reasons to make the text
2734 random.
2735
2736 \bwebdoc{Director:Client:SnapshotRetention}
2737 \item [Snapshot Retention = \bbracket{time-period-specification}]
2738 \index[dir]{Snapshot Retention}
2739 \index[dir]{Directive!Snapshot Retention}
2740
2741 The Snapshot Retention directive defines the length of time that \bacula{} will
2742 keep Snapshots in the Catalog database and on the Client after the Snapshot
2743 creation. When this time period expires, and if using the \bcommandname{snapshot prune}
2744 command, \bacula{} will prune (remove) Snapshot records that are older than
2745 the specified Snapshot Retention period and will contact the FileDaemon to delete
2746 Snapshots from the system.
2747
2748 The Snapshot retention period is specified as seconds, minutes, hours, days,
2749 weeks, months, quarters, or years. See the
2750 \bilink{ Configuration chapter}{blb:Time} of this manual for
2751 additional details of time specification.
2752
2753 The default is \bdefaultvalue{0 seconds}, Snapshots are deleted at the end of the
2754 backup. The Job \bdirectivename{SnapshotRetention} directive overwrites the Client
2755 \bdirectivename{SnapshotRetention} directive.
2756
2757 \label{blb:FileRetention}
2758 \bwebdoc{Director:Client:FileRetention}
2759 \item [File Retention = \bbracket{time-period-specification}]
2760 \index[dir]{File Retention}
2761 \index[dir]{Directive!File Retention}
2762 The File Retention directive defines the length of time that \bacula{} will
2763 keep File records in the Catalog database after the End time of the
2764 Job corresponding to the File records.
2765 When this time period expires, and if
2766 \bdirectivename{AutoPrune} is set to \bvalue{yes} \bacula{} will prune (remove) File
2767 records that are older than the specified File Retention period. Note,
2768 this affects only records in the catalog database. It does not affect
2769 your archive backups.
2770
2771 File records may actually be retained for a shorter period than you
2772 specify on this directive if you specify either a shorter \textbf{Job Retention}
2773 or a shorter \textbf{Volume Retention} period. The shortest
2774 retention period of the three takes precedence. The time may be
2775 expressed in seconds, minutes, hours, days, weeks, months, quarters, or
2776 years. See the \bilink{Configuration chapter}{blb:Time} of this manual for
2777 additional details of time specification.
2778
2779 The default is \bdefaultvalue{60 days}.
2780
2781 \label{blb:JobRetention}
2782 \bwebdoc{Director:Client:JobRetention}
2783 \item [Job Retention = \bbracket{time-period-specification}]
2784 \index[dir]{Job Retention}
2785 \index[dir]{Directive!Job Retention}
2786 The Job Retention directive defines the length of time that \bacula{} will keep
2787 Job records in the Catalog database after the Job End time. When
2788 this time period expires, and if \bdirectivename{AutoPrune} is set to \bvalue{yes}
2789 \bacula{} will prune (remove) Job records that are older than the specified
2790 File Retention period. As with the other retention periods, this
2791 affects only records in the catalog and not data in your archive backup.
2792
2793 If a Job record is selected for pruning, all associated File and JobMedia
2794 records will also be pruned regardless of the File Retention period set.
2795 As a consequence, you normally will set the File retention period to be
2796 less than the Job retention period. The Job retention period can actually
2797 be less than the value you specify here if you set the
2798 \bdirectivename{Volume Retention} directive in the Pool resource to a smaller duration. This is
2799 because the Job retention period and the Volume retention period are
2800 independently applied, so the smaller of the two takes precedence.
2801
2802 The Job retention period is specified as seconds, minutes, hours, days,
2803 weeks, months, quarters, or years. See the
2804 \bilink{ Configuration chapter}{blb:Time} of this manual for
2805 additional details of time specification.
2806
2807 The default is \bdefaultvalue{180 days}.
2808 \label{blb:AutoPrune}
2809
2810 \bwebdoc{Director:Client:AutoPrune}
2811 \item [AutoPrune = \byesorno{}]
2812 \index[dir]{AutoPrune}
2813 \index[dir]{Directive!AutoPrune}
2814 If AutoPrune is set to \bdefaultvalue{yes} (default), \bacula{} (version 1.20 or greater)
2815 will automatically apply the File retention period and the Job retention
2816 period for the Client at the end of the Job. If you set \bvalueddirective{AutoPrune}{no},
2817 pruning will not be done, and your Catalog will grow in size each time you
2818 run a Job. Pruning affects only information in the catalog and not data
2819 stored in the backup archives (on Volumes).
2820
2821 \bwebdoc{Director:Client:MaximumConcurrentJobs}
2822 \item [Maximum Concurrent Jobs = \bbracket{number}]
2823 \index[dir]{Maximum Concurrent Jobs}
2824 \index[dir]{Directive!Maximum Concurrent Jobs}
2825 where \bbracket{number} is the maximum number of Jobs with the current Client
2826 that can run concurrently. Note, this directive limits only Jobs for Clients
2827 with the same name as the resource in which it appears. Any other
2828 restrictions on the maximum concurrent jobs such as in the Director, Job, or
2829 Storage resources will also apply in addition to any limit specified here.
2830 The default is set to \bdefaultvalue{1}, but you may set it to a larger number. If set to a
2831 large value, please be careful to not have this value higher than the
2832 \bdirectivename{Maximum Concurrent Jobs} configured in the \bresourcename{Client} resource in the
2833 Client/File daemon configuration file. Otherwise, backup jobs can fail due
2834 to the Director connection to FD be refused because \acl{MCJ} was exceeded on FD side.
2835
2836 \bwebdoc{Director:Client:MaximumBandwidthPerJob}
2837 \item [Maximum Bandwidth Per Job = \bbracket{speed}]
2838 \index[dir]{Maximum Bandwidth Per Job}
2839 \index[dir]{Directive!Maximum Bandwidth Per Job}
2840
2841 The speed parameter specifies the maximum allowed bandwidth in bytes that a
2842 job may use when started for this Client.
2843 You may specify the following speed parameter modifiers:
2844 kb/s (1,000 bytes per second), k/s (1,024 bytes per second),
2845 mb/s (1,000,000 bytes per second), or m/s (1,048,576 bytes per second).
2846
2847 The use of TLS, TLS PSK, CommLine compression and Deduplication can interfer
2848 with the value set with the Directive.
2849
2850 % \item [FD Storage Address = \bbracket{address}]
2851 % \index[dir]{FDStorageAddress}
2852 % \index[dir]{Directive!FD Storage Address}
2853 % \index[dir]{Storage daemon Address}
2854 %
2855 % Where the address is a host name, a \textbf{fully qualified domain name}, or an
2856 % \textbf{IP address}. Please note that the \bbracket{address} as specified here
2857 % will be transmitted to the File daemon instead of the Storage
2858 % \texttt{Address} who will then use it to contact the Storage daemon. This
2859 % directive can be used in NAT environment where the configuration of the
2860 % Client resolver is not possible. Note that using this directive will not allow
2861 % to use multiple Storage Daemon for Backup/Restore jobs.
2862 %
2863
2864 \bwebdoc{Director:Client:Priority}
2865 \item [Priority = \bbracket{number}]
2866 \index[dir]{Priority}
2867 \index[dir]{Directive!Priority}
2868 The number specifies the priority of this client relative to other clients
2869 that the Director is processing simultaneously. The priority can range from
2870 1 to 1000. The clients are ordered such that the smaller number priorities
2871 are performed first (not currently implemented).
2872
2873 \bwebdoc{Director:Client:SDCallsClient}
2874 \item [SD Calls Client = \byesorno{}]
2875 \index[dir]{SD Calls Client}
2876 \index[dir]{Directive!SD Calls Client}
2877
2878 If the \bdirectivename{SD Calls Client} directive is set to true in a \bresourcename{Client} resource any
2879 Backup, Restore, Verify Job where the client is involved, the client will wait
2880 for the Storage daemon to contact it. By default this directive is set to
2881 \bdefaultvalue{false}, and the Client will call the Storage daemon as it always has. This
2882 directive can be useful if your Storage daemon is behind a firewall that
2883 permits outgoing connections but not incoming connections.
2884
2885
2886 \bwebdoc{Director:Client:FdStorageAddress}
2887 \item [FD Storage Address = \bbracket{address}]
2888 \index[dir]{FDStorageAddress}
2889 \index[dir]{Directive!FD Storage Address}
2890 \index[dir]{Storage daemon Address}
2891 Where the \bbracket{address} is a host name, a \acl{FQDN},
2892 or an \textbf{\acs{IP} address}. The \bbracket{address} specified here will be
2893 transmitted to the File daemon instead of the \acs{IP} address that the
2894 Director uses to contact the Storage daemon. This FDStorageAddress
2895 will then be used by the File daemon to contact the Storage daemon.
2896 This directive particularly useful if the File daemon is in a
2897 different network domain than the Director or Storage daemon.
2898 It is also useful in \acs{NAT} or firewal environments.
2899
2900 \input{DirectorClientTls}
2901
2902 \end{bdescription}
2903
2904 The following is an example of a valid Client resource definition:
2905
2906 \begin{bVerbatim}
2907 Client {
2908 Name = Minimatou
2909 Address = minimatou
2910 Catalog = MySQL
2911 Password = very_good
2912 }
2913 \end{bVerbatim}
2914
2915 \label{blb:StorageResource}
2916 \section{The Storage Resources}
2917 \index[general]{Resource!Storage}
2918 \index[general]{Storage Resource}
2919
2920 The Storage resource defines which Storage daemons are available for use by
2921 the Director.
2922
2923 \begin{bdescription}
2924
2925 \item [Storage]
2926 \index[dir]{Storage}
2927 \index[dir]{Directive!Storage}
2928 Start of the Storage resources. At least one storage resource must be
2929 specified.
2930
2931 \bwebdoc{Director:Storage:Name}
2932 \item [Name = \bbracket{name}]
2933 \index[dir]{Name}
2934 \index[dir]{Directive!Name}
2935 The name of the storage resource. This name appears on the Storage directive
2936 specified in the Job resource and is required.
2937
2938 \bwebdoc{Director:Storage:Enabled}
2939 \item [Enabled = \byesorno{}]
2940 \index[dir]{Enable}
2941 \index[dir]{Directive!Enable}
2942 This directive allows you to enable or disable a \bresourcename{Storage} resource. When the
2943 resource is disabled, the storage device will not be used. To reuse it
2944 you must re-enable the \bresourcename{Storage} resource.
2945
2946 \bwebdoc{Director:Storage:Address}
2947 \item [Address = \bbracket{address}]
2948 \index[dir]{Address}
2949 \index[dir]{Directive!SD Address}
2950 \index[dir]{Storage daemon Address}
2951 Where the address is a host name, a \acl{FQDN},
2952 or an \textbf{\acs{IP} address}. Please note that the \bbracket{address} as
2953 specified here will be transmitted to the File daemon who will then use
2954 it to contact the Storage daemon. Hence, it is \textbf{not}, a good idea
2955 to use \bvalue{localhost} as the name but rather a fully qualified machine
2956 name or an \acs{IP} address. This directive is required.
2957
2958 \bwebdoc{Director:Storage:FdStorageAddress}
2959 \item [FD Storage Address = \bbracket{address}]
2960 \index[dir]{FDStorageAddress}
2961 \index[dir]{Directive!FD Storage Address}
2962 \index[dir]{Storage daemon Address}
2963 Where the \bbracket{address} is a host name, a \acl{FQDN},
2964 or an \textbf{\acs{IP} address}. The \bbracket{address} specified here will be
2965 transmitted to the File daemon instead of the \acs{IP} address that the
2966 Director uses to contact the Storage daemon. This FDStorageAddress
2967 will then be used by the File daemon to contact the Storage daemon.
2968 This directive particularly useful if the File daemon is in a
2969 different network domain than the Director or Storage daemon.
2970 It is also useful in \acs{NAT} or firewal environments.
2971
2972 \bimageH{BackupOverWan1}{Backup over WAN using FD Storage Address}{figdirdconf:backupwan}
2973
2974 \bwebdoc{Director:Storage:SdPort}
2975 \item [SD Port = \bbracket{port}]
2976 \index[dir]{SD Port}
2977 \index[dir]{Directive!SD Port}
2978 Where port is the port to use to contact the storage daemon for information
2979 and to start jobs. This same port number must appear in the Storage resource
2980 of the Storage daemon's configuration file. The default is \bdefaultvalue{9103}.
2981
2982 \bwebdoc{Director:Storage:Password}
2983 \item [Password = \bbracket{password}]
2984 \index[dir]{Password}
2985 \index[dir]{Directive!Password}
2986 This is the password to be used when establishing a connection with the
2987 Storage services. This same password also must appear in the Director
2988 resource of the Storage daemon's configuration file. This directive is
2989 required. If you have either \btool{/dev/random} or \btool{bc} on your machine,
2990 \bacula{} will generate a random password during the configuration process,
2991 otherwise it will be left blank.
2992
2993 The password is plain text. It is not generated through any special
2994 process, but it is preferable for security reasons to use random text.
2995
2996 \bwebdoc{Director:Storage:Device}
2997 \item [Device = \bbracket{device-name}]
2998 \index[dir]{Device}
2999 \index[dir]{Directive!Device}
3000 This directive specifies the Storage daemon's name of the device
3001 resource to be used for the storage. If you are using an Autochanger,
3002 the name specified here should be the name of the Storage daemon's
3003 Autochanger resource rather than the name of an individual device. This
3004 name is not the physical device name, but the logical device name as
3005 defined on the \bdirectivename{Name} directive contained in the
3006 \bresourcename{Device} or the \bresourcename{Autochanger}
3007 resource definition of the \textbf{Storage daemon} configuration file.
3008 You can specify any name you would like (even the
3009 device name if you prefer) up to a maximum of 127 characters in length.
3010 The physical device name associated with this device is specified in the
3011 \textbf{Storage daemon} configuration file (as \bdirectivename{Archive Device}).
3012 Please take care not to define two different Storage resource directives
3013 in the Director that point to the same Device in the Storage daemon.
3014 Doing so may cause the Storage daemon to block (or hang) attempting to
3015 open the same device that is already open. This directive is required.
3016 \label{blb:MediaType}
3017
3018 \bwebdoc{Director:Storage:MediaType}
3019 \item [Media Type = \bbracket{MediaType}]
3020 \index[dir]{Media Type}
3021 \index[dir]{Directive!Media Type}
3022 This directive specifies the Media Type to be used to store the data.
3023 This is an arbitrary string of characters up to 127 maximum that you
3024 define. It can be anything you want. However, it is best to make it
3025 descriptive of the storage media (e.g. ``File'', ``DAT'', ``HP DLT8000'', ``8mm'',
3026 \ldots{}). In addition, it is essential that you make the \bdirectivename{Media Type}
3027 specification unique for each storage media type. If you have two \acs{DDS}-4
3028 drives that have incompatible formats, or if you have a \acs{DDS}-4 drive and
3029 a \acs{DDS}-4 autochanger, you almost certainly should specify different
3030 \textbf{Media Types}. During a restore, assuming a \textbf{\acs{DDS}-4} Media Type is
3031 associated with the Job, \bacula{} can decide to use any Storage daemon
3032 that supports Media Type \textbf{\acs{DDS}-4} and on any drive that supports it.
3033
3034 If you are writing to disk Volumes, you must make doubly sure that each
3035 Device resource defined in the Storage daemon (and hence in the
3036 Director's conf file) has a unique media type. Otherwise for \bacula{}
3037 versions 1.38 and older, your restores may not work because \bacula{}
3038 will assume that you can mount any Media Type with the same name on
3039 any Device associated with that Media Type. This is possible with
3040 tape drives, but with disk drives, unless you are very clever you
3041 cannot mount a Volume in any directory -- this can be done by creating
3042 an appropriate soft link.
3043
3044 Currently \bacula{} permits only a single Media Type per Storage
3045 and Device definition. Consequently, if
3046 you have a drive that supports more than one Media Type, you can
3047 give a unique string to Volumes with different intrinsic Media
3048 Type (Media Type = \acs{DDS}-3-4 for \acs{DDS}-3 and \acs{DDS}-4 types), but then
3049 those volumes will only be mounted on drives indicated with the
3050 dual type (DDS-3-4).
3051
3052 If you want to tie \bacula{} to using a single Storage daemon or drive, you
3053 must specify a unique Media Type for that drive. This is an important
3054 point that should be carefully understood. Note, this applies equally
3055 to Disk Volumes. If you define more than one disk Device resource in
3056 your Storage daemon's conf file, the Volumes on those two devices are in
3057 fact incompatible because one can not be mounted on the other device
3058 since they are found in different directories. For this reason, you
3059 probably should use two different Media Types for your two disk Devices
3060 (even though you might think of them as both being File types). You can
3061 find more on this subject in the
3062 \bilink{Basic Volume Management}{blb:DiskChapter} chapter of this manual.
3063
3064 The \textbf{MediaType} specified in the Director's Storage resource,
3065 \textbf{must} correspond to the \textbf{Media Type} specified in the \bresourcename{Device}
3066 resource of the \textbf{Storage daemon} configuration file. This directive
3067 is required, and it is used by the Director and the Storage daemon to
3068 ensure that a Volume automatically selected from the Pool corresponds to
3069 the physical device. If a Storage daemon handles multiple devices (e.g.
3070 will write to various file Volumes on different partitions), this
3071 directive allows you to specify exactly which device.
3072
3073 As mentioned above, the value specified in the Director's Storage
3074 resource must agree with the value specified in the Device resource in
3075 the \textbf{Storage daemon's} configuration file. It is also an additional
3076 check so that you don't try to write data for a \acs{DLT} onto an 8mm device.
3077 \label{blb:Autochanger1}
3078
3079 \bwebdoc{Director:Storage:Autochanger}
3080 \item [Autochanger = \byesorno{}]
3081 \index[dir]{Autochanger}
3082 \index[dir]{Directive!Autochanger}
3083 If you specify \bvalue{yes} for this command (the default is \bdefaultvalue{no}),
3084 when you use the \bcommandname{label} command or the \bcommandname{add} command to create
3085 a new Volume, \bacula{} will also request the Autochanger Slot
3086 number. This simplifies creating database entries for Volumes in an
3087 autochanger. If you forget to specify the Slot, the autochanger will
3088 not be used. However, you may modify the Slot associated with a Volume
3089 at any time by using the \bcommandname{update volume} or \bcommandname{update slots}
3090 command in the console program. When \bdirectivename{Autochanger} is enabled, the
3091 algorithm used by \bacula{} to search for available volumes will be
3092 modified to consider only Volumes that are known to be in the
3093 autochanger's magazine. If no \textbf{in changer} volume is found, \bacula{}
3094 will attempt recycling, pruning, \ldots{}, and if still no volume is found,
3095 \bacula{} will search for any volume whether or not in the magazine. By
3096 privileging in changer volumes, this procedure minimizes operator
3097 intervention. The default is \bdefaultvalue{no}.
3098
3099 For the autochanger to be used, you must also specify \bvalueddirective{Autochanger}{yes}
3100 in the \bilink{Device Resource}{blb:Autochanger} in the Storage daemon's
3101 configuration file as well as other important Storage daemon
3102 configuration information. Please consult the
3103 \bilink{Using Autochangers}{blb:AutochangersChapter} manual of this chapter for the
3104 details of using autochangers.
3105 You can modify any additional \bresourcename{Storage} resources that correspond
3106 to devices that are part of the \bresourcename{Autochanger} device.
3107 Instead of the previous \bvalueddirective{Autochanger}{yes} directive, the configuration
3108 should be modified to be \bvalueddirective{Autochanger}{xxx} where \bvalue{xxx} is
3109 the name of the Autochanger.
3110
3111 \bwebdoc{Director:Storage:MaximumConcurrentJobs}
3112 \item [Maximum Concurrent Jobs = \bbracket{number}]
3113 \index[dir]{Maximum Concurrent Jobs}
3114 \index[dir]{Directive!Maximum Concurrent Jobs}
3115 where \bbracket{number} is the maximum number of Jobs with the current
3116 Storage resource that can run concurrently. Note, this directive limits
3117 only Jobs for Jobs using this Storage daemon. Any other restrictions on
3118 the maximum concurrent jobs such as in the Director, Job, or Client
3119 resources will also apply in addition to any limit specified here. The
3120 default is set to \bdefaultvalue{1}, but you may set it to a larger number. However, if
3121 you set the Storage daemon's number of concurrent jobs greater than one,
3122 we recommend that you read the waring documented under
3123 \bilink{Maximum Concurrent Jobs}{blb:DirMaxConJobs} in the Director's resource or simply
3124 turn data spooling on as documented in the
3125 \bilink{Data Spooling}{blb:SpoolingChapter} chapter of this manual.
3126
3127 \bwebdoc{Director:Storage:MaximumConcurrentReadJobs}
3128 \item [Maximum Concurrent Read Jobs = \bbracket{number}]
3129 \index[dir]{MaximumConcurrentReadJobs}
3130 \index[dir]{Directive!MaximumConcurrentReadJobs}
3131
3132 The main purpose is to limit the number of concurrent Copy, Migration, and
3133 VirtualFull jobs so that they don't monopolize all the Storage drives causing
3134 a deadlock situation where all the drives are allocated for reading but none
3135 remain for writing. This deadlock situation can occur when running multiple
3136 simultaneous Copy, Migration, and VirtualFull jobs.
3137 \smallskip
3138
3139 The default value is set to \bdefaultvalue{0} (zero), which means there is no
3140 limit on the number of read jobs. Note, limiting the read jobs does not
3141 apply to Restore jobs, which are normally started by hand. A reasonable
3142 value for this directive is one half the number of drives that the Storage
3143 resource has rounded down. Doing so, will leave the same number of drives
3144 for writing and will generally avoid over committing drives and a deadlock.
3145
3146
3147 \label{blb:AllowCompression}
3148 \bwebdoc{Director:Storage:AllowCompression}
3149 \item [AllowCompression = \byesorno{}]
3150 \index[dir]{AllowCompression}
3151 \index[dir]{Directive!AllowCompression}
3152
3153 This directive is optional, and if you specify \bvalue{no} (the default is \bdefaultvalue{yes}),
3154 it will cause backups jobs running on this storage resource to run
3155 without client File Daemon compression. This effectively overrides
3156 compression options in FileSets used by jobs which use this storage
3157 resource.
3158
3159 \bwebdoc{Director:Storage:HeartbeatInterval}
3160 \item [Heartbeat Interval = \bbracket{time-interval}]
3161 \index[dir]{Heartbeat Interval}
3162 \index[dir]{Directive!Heartbeat}
3163 This directive is optional and if specified will cause the Director to
3164 set a keepalive interval (heartbeat) in seconds on each of the sockets
3165 it opens for the Storage resource. This value will override any
3166 specified at the Director level. It is implemented only on systems
3167 (Linux, \ldots{}) that provide the \btool{setsockopt} \texttt{TCP\_KEEPIDLE} function.
3168 The default value is \bdefaultvalue{300s}.
3169
3170 \input{DirectorStorageTls}
3171
3172 \bwebdoc{Director:Storage:End}
3173 \end{bdescription}
3174
3175 The following is an example of a valid Storage resource definition:
3176
3177 \begin{bVerbatim}
3178 # Definition of tape storage device
3179 Storage {
3180 Name = DLTDrive
3181 Address = lpmatou
3182 Password = storage_password # password for Storage daemon
3183 Device = "HP DLT 80" # same as Device in Storage daemon
3184 Media Type = DLT8000 # same as MediaType in Storage daemon
3185 }
3186 \end{bVerbatim}
3187
3188 \section{The Autochanger Resources}
3189 \index[general]{Resource!Autochanger}
3190 \index[general]{Autochanger Resource}
3191
3192 Each autochanger that you have defined in an \bresourcename{Autochanger} resource in the
3193 Storage daemon's \bfilename{bacula-sd.conf} file, must have a corresponding \bresourcename{Autochanger}
3194 resource defined in the Director's \bfilename{bacula-dir.conf} file.
3195 The \bresourcename{Autochanger} resource uses the same directives as the \bresourcename{Storage}
3196 resource defined \vref{blb:StorageResource}.
3197
3198 Normally you will already have a \bresourcename{Storage} resource that points to the
3199 Storage daemon's \bresourcename{Autochanger} resource. Thus you need only to change the
3200 name of the \bresourcename{Storage} resource to \bresourcename{Autochanger}.
3201 In addition the \bvalueddirective{Autochanger}{yes} directive is not needed in the Director's
3202 \bresourcename{Autochanger} resource, since the resource name is \bresourcename{Autochanger}, the
3203 Director already knows that it represents an autochanger.
3204 \smallskip
3205
3206 In addition to the above change (\bresourcename{Storage} to \bresourcename{Autochanger}),
3207 you must modify any additional \bresourcename{Storage} resources that correspond
3208 to devices that are part of the \bresourcename{Autochanger} device.
3209 Instead of the previous \bvalueddirective{Autochanger}{yes} directive, the configuration
3210 should be modified to be \bvalueddirective{Autochanger}{xxx} where \bvalue{xxx} is
3211 the name of the Autochanger.
3212 \smallskip
3213
3214 For example, in the \bfilename{bacula-dir.conf} file:
3215
3216 \begin{bVerbatim}
3217 Autochanger { # New resource
3218 Name = Changer-1
3219 Address = cibou.company.com
3220 SDPort = 9103
3221 Password = "xxxxxxxxxx"
3222 Device = LTO-Changer-1
3223 Media Type = LTO-4
3224 Maximum Concurrent Jobs = 50
3225 }
3226
3227 Storage {
3228 Name = Changer-1-Drive0
3229 Address = cibou.company.com
3230 SDPort = 9103
3231 Password = "xxxxxxxxxx"
3232 Device = LTO4_1_Drive0
3233 Media Type = LTO-4
3234 Maximum Concurrent Jobs = 5
3235 Autochanger = Changer-1 # New directive
3236 }
3237
3238 Storage {
3239 Name = Changer-1-Drive1
3240 Address = cibou.company.com
3241 SDPort = 9103
3242 Password = "xxxxxxxxxx"
3243 Device = LTO4_1_Drive1
3244 Media Type = LTO-4
3245 Maximum Concurrent Jobs = 5
3246 Autochanger = Changer-1 # New directive
3247 }
3248
3249 ...
3250 \end{bVerbatim}
3251
3252 Note that Storage resources \bresourcename{Changer-1-Drive0} and \bresourcename{Changer-1-Drive1}
3253 are not required since they make up part of an autochanger, and normally, Jobs
3254 refer only to the Autochanger resource. However, by referring to those Storage
3255 definitions in a Job, you will use only the indicated drive. This is not
3256 normally what you want to do, but it is very useful and often used for
3257 reserving a drive for restores. See the Storage daemon example configuration below and
3258 the use of \bvalueddirective{AutoSelect}{no}.
3259
3260 \label{blb:PoolResource}
3261 \section{The Pool Resource}
3262 \index[general]{Resource!Pool}
3263 \index[general]{Pool Resource}
3264
3265 The Pool resource defines the set of storage Volumes (tapes or files) to be
3266 used by \bacula{} to write the data. By configuring different Pools, you can
3267 determine which set of Volumes (media) receives the backup data. This permits,
3268 for example, to store all full backup data on one set of Volumes and all
3269 incremental backups on another set of Volumes. Alternatively, you could assign
3270 a different set of Volumes to each machine that you backup. This is most
3271 easily done by defining multiple Pools.
3272
3273 Another important aspect of a Pool is that it contains the default attributes
3274 (Maximum Jobs, Retention Period, Recycle flag, \ldots{}) that will be given to a
3275 Volume when it is created. This avoids the need for you to answer a large
3276 number of questions when labeling a new Volume. Each of these attributes can
3277 later be changed on a Volume by Volume basis using the \bcommandname{update} command in
3278 the console program. Note that you must explicitly specify which Pool \bacula{}
3279 is to use with each Job. \bacula{} will not automatically search for the correct
3280 Pool.
3281
3282 Most often in \bacula{} installations all backups for all machines (Clients) go
3283 to a single set of Volumes. In this case, you will probably only use the \textbf{Default}
3284 Pool. If your backup strategy calls for you to mount a different tape
3285 each day, you will probably want to define a separate Pool for each day. For
3286 more information on this subject, please see the
3287 \bilink{Backup Strategies}{blb:StrategiesChapter} chapter of this
3288 manual.
3289
3290
3291 To use a Pool, there are three distinct steps. First the Pool must be defined
3292 in the Director's configuration file. Then the Pool must be written to the
3293 Catalog database. This is done automatically by the Director each time that it
3294 starts, or alternatively can be done using the \bcommandname{create} command in the
3295 console program. Finally, if you change the Pool definition in the Director's
3296 configuration file and restart \bacula{}, the pool will be updated alternatively
3297 you can use the \bcommandname{update pool} console command to refresh the database
3298 image. It is this database image rather than the Director's resource image
3299 that is used for the default Volume attributes. Note, for the pool to be
3300 automatically created or updated, it must be explicitly referenced by a Job
3301 resource.
3302
3303 Next the physical media must be labeled. The labeling can either be done with
3304 the \bcommandname{label} command in the \btool{console} program or using the \btool{btape}
3305 program. The preferred method is to use the \bcommandname{label} command in the \btool{console} program.
3306
3307 Finally, you must add Volume names (and their attributes) to the Pool. For
3308 Volumes to be used by \bacula{} they must be of the same \textbf{Media Type} as the
3309 archive device specified for the job (i.e. if you are going to back up to a
3310 \acs{DLT} device, the Pool must have \acs{DLT} volumes defined since 8mm volumes cannot be
3311 mounted on a \acs{DLT} drive). The \textbf{Media Type} has particular importance if you
3312 are backing up to files. When running a Job, you must explicitly specify which
3313 Pool to use. \bacula{} will then automatically select the next Volume to use from
3314 the Pool, but it will ensure that the \textbf{Media Type} of any Volume selected
3315 from the Pool is identical to that required by the Storage resource you have
3316 specified for the Job.
3317
3318 If you use the \bcommandname{label} command in the console program to label the
3319 Volumes, they will automatically be added to the Pool, so this last step is
3320 not normally required.
3321
3322 It is also possible to add Volumes to the database without explicitly labeling
3323 the physical volume. This is done with the \bcommandname{add} console command.
3324
3325 As previously mentioned, each time \bacula{} starts, it scans all the Pools
3326 associated with each Catalog, and if the database record does not already
3327 exist, it will be created from the Pool Resource definition. \bacula{}
3328 probably should do an \bcommandname{update pool} if you change the Pool definition, but
3329 currently, you must do this manually using the \bcommandname{update pool} command in
3330 the Console program.
3331
3332 The Pool Resource defined in the Director's configuration file
3333 (\bfilename{bacula-dir.conf}) may contain the following directives:
3334
3335 \begin{bdescription}
3336
3337 \item [Pool]
3338 \index[dir]{Pool}
3339 \index[dir]{Directive!Pool}
3340 Start of the Pool resource. There must be at least one Pool resource
3341 defined.
3342
3343
3344 \bwebdoc{Director:Pool:Name}
3345 \item [Name = \bbracket{name}]
3346 \index[dir]{Name}
3347 \index[dir]{Directive!Name}
3348 The name of the pool. For most applications, you will use the default
3349 pool name \bvalue{Default}. This directive is required.
3350 \label{blb:MaxVolumes}
3351
3352 \bwebdoc{Director:Pool:MaximumVolumes}
3353 \item [Maximum Volumes = \bbracket{number}]
3354 \index[dir]{Maximum Volumes}
3355 \index[dir]{Directive!Maximum Volumes}
3356 This directive specifies the maximum number of volumes (tapes or files)
3357 contained in the pool. This directive is optional, if omitted or set to
3358 zero, any number of volumes will be permitted. In general, this
3359 directive is useful for Autochangers where there is a fixed number of
3360 Volumes, or for File storage where you wish to ensure that the backups
3361 made to disk files do not become too numerous or consume too much space.
3362 \smallskip
3363
3364 This directive is only respected in case of volumes automatically created by \bacula{}. If you add volumes to a pool manually with the \bcommandname{label} command, it is possible to have more volumes in a pool than specified by \bdirectivename{Maximum Volumes}.
3365
3366 \bwebdoc{Director:Pool:MaximumPoolBytes}
3367 \item [Maximum Pool Bytes = \bbracket{size}]
3368 \index[dir]{Maximum Pool Bytes}
3369 \index[dir]{Directive!Maximum Pool Bytes}
3370
3371 This directive specifies the total maximum size of volumes (tapes or files)
3372 contained in the pool. This directive is optional, if omitted or set to
3373 zero, any size will be permitted. The current size of the pool can be
3374 displayed with \bcommandname{llist pool} command. All type of volumes with any status
3375 are counted in the pool size. To exclude \bstatus{Pruned} and \bstatus{Recycled} volumes
3376 from the quota, the \bdirectivename{RecyclePool} directive can be used to send back pruned
3377 volumes to the Scratch pool for example.
3378
3379 \bwebdoc{Director:Pool:PoolType}
3380 \item [Pool Type = \bbracket{type}]
3381 \index[dir]{Pool Type}
3382 \index[dir]{Directive!Pool Type}
3383 This directive defines the pool type, which corresponds to the type of
3384 Job being run. It is required and may be one of the following:
3385
3386 \begin{bitemize}
3387 \item [Backup]
3388 \item [*Archive]
3389 \item [*Cloned]
3390 \item [*Migration]
3391 \item [*Copy]
3392 \item [*Save]
3393 \end{bitemize}
3394 Note, only Backup is current implemented.
3395
3396 \bwebdoc{Director:Pool:Storage}
3397 \item [Storage = \bbracket{storage-resource-name}]
3398 \index[dir]{Storage}
3399 \index[dir]{Directive!Storage}
3400 The Storage directive defines the name of the storage services where you
3401 want to backup the FileSet data. For additional details, see the
3402 \bilink{Storage Resource Chapter}{blb:StorageResource} of this manual.
3403 The Storage resource may also be specified in the Job resource,
3404 but the value, if any, in the Pool resource overrides any value
3405 in the Job. This Storage resource definition is not required by either
3406 the Job resource or in the Pool, but it must be specified in
3407 one or the other. If not configuration error will result.
3408
3409 \bwebdoc{Director:Pool:UseVolumeOnce}
3410 \item [Use Volume Once = \byesorno{}]
3411 \index[dir]{Use Volume Once}
3412 \index[dir]{Directive!Use Volume Once}
3413 This directive if set to \bvalue{yes} specifies that each volume is to be
3414 used only once. This is most useful when the Media is a file and you
3415 want a new file for each backup that is done. The default is \bdefaultvalue{no}
3416 (i.e. use volume any number of times). This directive will most likely
3417 be phased out (deprecated), so you are recommended to use
3418 \bvalueddirective{Maximum Volume Jobs}{1} instead.
3419
3420 The value defined by this directive in the \bfilename{bacula-dir.conf} file is the
3421 default value used when a Volume is created. Once the volume is
3422 created, changing the value in the \bfilename{bacula-dir.conf} file will not change
3423 what is stored for the Volume. To change the value for an existing
3424 Volume you must use the \bcommandname{update} command in the Console.
3425
3426 Please see the notes below under \bdirectivename{Maximum Volume Jobs} concerning
3427 using this directive with multiple simultaneous jobs.
3428
3429 \bwebdoc{Director:Pool:MaximumVolumeJobs}
3430 \item [Maximum Volume Jobs = \bbracket{positive-integer}]
3431 \index[dir]{Maximum Volume Jobs}
3432 \index[dir]{Directive!Maximum Volume Jobs}
3433 This directive specifies the maximum number of Jobs that can be written
3434 to the Volume. If you specify zero (\bdefaultvalue{0}) (the default), there is no limit.
3435 Otherwise, when the number of Jobs backed up to the Volume equals \bbracket{positive-integer}
3436 the Volume will be marked \bstatus{Used}. When the Volume
3437 is marked \bstatus{Used} it can no longer be used for appending Jobs, much
3438 like the \bstatus{Full} status. A Volume that is marked \bstatus{Used} or \bstatus{Full}
3439 can be recycled if recycling is enabled, and thus used again. By
3440 setting \bdirectivename{MaximumVolumeJobs} to \bvalue{1}, you get the same effect as
3441 setting \bvalueddirective{UseVolumeOnce}{yes}.
3442
3443 The value defined by this directive in the \bfilename{bacula-dir.conf}
3444 file is the default value used when a Volume is created. Once the volume is
3445 created, changing the value in the \bfilename{bacula-dir.conf} file will not change what
3446 is stored for the Volume. To change the value for an existing Volume you
3447 must use the \bcommandname{update} command in the Console.
3448
3449 If you are running multiple simultaneous jobs, this directive may not
3450 work correctly because when a drive is reserved for a job, this
3451 directive is not taken into account, so multiple jobs may try to
3452 start writing to the Volume. At some point, when the Media record is
3453 updated, multiple simultaneous jobs may fail since the Volume can no
3454 longer be written.
3455
3456 \bwebdoc{Director:Pool:MaximumVolumeFiles}
3457 \item [Maximum Volume Files = \bbracket{positive-integer}]
3458 \index[dir]{Maximum Volume Files}
3459 \index[dir]{Directive!Maximum Volume Files}
3460 This directive specifies the maximum number of files that can be written
3461 to the Volume. If you specify zero (\bdefaultvalue{0}, the default), there is no limit.
3462 Otherwise, when the number of files written to the Volume equals \bbracket{positive-integer}
3463 the Volume will be marked \bstatus{Used}. When the Volume
3464 is marked \bstatus{Used} it can no longer be used for appending Jobs, much
3465 like the \bstatus{Full} status, but it can be recycled if recycling is
3466 enabled and thus used again. This value is checked and the \bstatus{Used}
3467 status is set only at the end of a job that writes to the particular
3468 volume.
3469
3470 The value defined by this directive in the \bfilename{bacula-dir.conf} file is the
3471 default value used when a Volume is created. Once the volume is
3472 created, changing the value in the \bfilename{bacula-dir.conf} file will not change
3473 what is stored for the Volume. To change the value for an existing
3474 Volume you must use the \bcommandname{update} command in the Console.
3475
3476 \bwebdoc{Director:Pool:MaximumVolumeBytes}
3477 \item [Maximum Volume Bytes = \bbracket{size}]
3478 \index[dir]{Maximum Volume Bytes}
3479 \index[dir]{Directive!Maximum Volume Bytes}
3480 This directive specifies the maximum number of bytes that can be written
3481 to the Volume. If you specify zero (\bdefaultvalue{0},the default), there is no limit
3482 except the physical size of the Volume. Otherwise, when the number of
3483 bytes written to the Volume equals \bbracket{size} the Volume will be marked
3484 \bstatus{Full}.
3485 When the Volume is marked \bstatus{Full} it can no longer be
3486 used for appending Jobs, but it can be recycled if recycling is enabled, and thus
3487 the Volume can be re-used after recycling. The size specified is checked just before each
3488 block is written to the Volume and if the Volume size would exceed the
3489 specified Maximum Volume Bytes the \bstatus{Full} status will be set and
3490 the Job will request the next available Volume to continue.
3491
3492 This directive is particularly useful for restricting the size
3493 of disk volumes, and will work correctly even in the case of
3494 multiple simultaneous jobs writing to the volume.
3495
3496 The value defined by this directive in the \bfilename{bacula-dir.conf} file is the
3497 default value used when a Volume is created. Once the volume is
3498 created, changing the value in the \bfilename{bacula-dir.conf} file will not change
3499 what is stored for the Volume. To change the value for an existing
3500 Volume you must use the \bcommandname{update} command in the Console.
3501
3502 \bwebdoc{Director:Pool:VolumeUseDuration}
3503 \item [Volume Use Duration = \bbracket{time-period-specification}]
3504 \index[dir]{Volume Use Duration}
3505 \index[dir]{Directive!Volume Use Duration}
3506 The Volume Use Duration directive defines the time period that the
3507 Volume can be written beginning from the time of first data write to the
3508 Volume. If the time-period specified is zero (\bdefaultvalue{0},the default), the Volume
3509 can be written indefinitely. Otherwise, the next time a job
3510 runs that wants to access this Volume, and the time period from the
3511 first write to the volume (the first Job written) exceeds the
3512 time-period-specification, the Volume will be marked \bstatus{Used}, which
3513 means that no more Jobs can be appended to the Volume, but it may be
3514 recycled if recycling is enabled. Using the command \bcommandname{status dir}
3515 applies algorithms similar to running jobs, so
3516 during such a command, the Volume status may also be changed.
3517 Once the Volume is
3518 recycled, it will be available for use again.
3519
3520 You might use this directive, for example, if you have a Volume used for
3521 Incremental backups, and Volumes used for Weekly Full backups. Once the
3522 Full backup is done, you will want to use a different Incremental
3523 Volume. This can be accomplished by setting the Volume Use Duration for
3524 the Incremental Volume to six days. I.e. it will be used for the 6
3525 days following a Full save, then a different Incremental volume will be
3526 used. Be careful about setting the duration to short periods such as 23
3527 hours, or you might experience problems of \bacula{} waiting for a tape
3528 over the weekend only to complete the backups Monday morning when an
3529 operator mounts a new tape.
3530
3531 The use duration is checked and the \bstatus{Used} status is set only at the
3532 end of a job that writes to the particular volume, which means that even
3533 though the use duration may have expired, the catalog entry will not be
3534 updated until the next job that uses this volume is run. This
3535 directive is not intended to be used to limit volume sizes
3536 and may not work as expected (i.e. will fail jobs) if the use
3537 duration expires while multiple simultaneous jobs are writing
3538 to the volume.
3539
3540 Please note that the value defined by this directive in the \bfilename{bacula-dir.conf}
3541 file is the default value used when a Volume is created. Once the volume is
3542 created, changing the value in the \bfilename{bacula-dir.conf} file will not change what
3543 is stored for the Volume. To change the value for an existing Volume you
3544 must use the
3545 \bxlink{update volume}{blb:UpdateCommand}{console}{command} in the \bconsoleman{}.
3546
3547 \bwebdoc{Director:Pool:CatalogFiles}
3548 \item [Catalog Files = \byesorno{}]
3549 \index[dir]{Catalog Files}
3550 \index[dir]{Directive!Catalog Files}
3551 This directive defines whether or not you want the names of the files
3552 that were saved to be put into the catalog. The default is \bdefaultvalue{yes}.
3553 The advantage of specifying \bvalueddirective{Catalog Files}{No} is that you will
3554 have a significantly smaller Catalog database. The disadvantage is that
3555 you will not be able to produce a Catalog listing of the files backed up
3556 for each Job (this is often called Browsing). Also, without the File
3557 entries in the catalog, you will not be able to use the Console \bcommandname{restore}
3558 command nor any other command that references File entries.
3559 \label{blb:PoolAutoPrune}
3560
3561 \bwebdoc{Director:Pool:AutoPrune}
3562 \item [AutoPrune = \byesorno{}]
3563 \index[dir]{AutoPrune}
3564 \index[dir]{Directive!AutoPrune}
3565 If AutoPrune is set to \bdefaultvalue{yes} (default), \bacula{} (version 1.20 or
3566 greater) will automatically apply the Volume Retention period when new
3567 Volume is needed and no appendable Volumes exist in the Pool. Volume
3568 pruning causes expired Jobs (older than the \bdirectivename{Volume Retention}
3569 period) to be deleted from the Catalog and permits possible recycling of
3570 the Volume.
3571 \label{blb:VolRetention}
3572
3573 \bwebdoc{Director:Pool:VolumeRetention}
3574 \item [Volume Retention = \bbracket{time-period-specification}]
3575 \index[dir]{Volume Retention}
3576 \index[dir]{Directive!Volume Retention}
3577 The \bdirectivename{Volume Retention} directive defines the longest amount of time that
3578 \bacula{} will keep records associated with the Volume in the Catalog
3579 database after the end time of each Job written to the Volume. When
3580 this time period expires, and if \bdirectivename{AutoPrune} is set to \bvalue{yes}
3581 \bacula{} may prune (remove) Job records that are older than the specified
3582 Volume Retention period if it is necessary to free up a Volume. Note,
3583 it is also possible for all the Job and File records to be pruned before
3584 the Volume Retention period if Job and File Retention periods are
3585 configured to a lower value. In that case the Volume can then be
3586 marked Pruned and subsequently recycled prior to expiration of
3587 the Volume Retention period.
3588 \smallskip
3589
3590 Recycling will not occur until it is absolutely necessary to
3591 free up a volume (i.e. no other writable volume exists).
3592 All File records associated with pruned Jobs are also
3593 pruned. The time may be specified as seconds, minutes, hours, days,
3594 weeks, months, quarters, or years. The \bdirectivename{Volume Retention} is
3595 applied independently of the \bdirectivename{Job Retention} and the
3596 \bdirectivename{File Retention} periods defined in the Client resource. This means that all
3597 the retention periods are applied in turn and that the shorter period
3598 is the one that effectively takes precedence. Note, that when the
3599 \bdirectivename{Volume Retention} period has been reached, and it is necessary to obtain
3600 a new volume, \bacula{} will prune both the Job and the File records. And
3601 the inverse is also true that if all the Job and File records that
3602 refer to a Volume were already pruned, then the Volume may be recycled
3603 regardless of its retention period. Pruning may also occur during a
3604 \bcommandname{status dir} command because it uses similar algorithms for finding
3605 the next available Volume.
3606
3607 It is important to know that when the Volume Retention period expires,
3608 or all the Job and File records have been pruned that refer to a Volume,
3609 \bacula{} does not automatically recycle a Volume. It attempts to keep the
3610 Volume data intact as long as possible before over writing the Volume.
3611
3612 By defining multiple Pools with different Volume Retention periods, you
3613 may effectively have a set of tapes that is recycled weekly, another
3614 Pool of tapes that is recycled monthly and so on. However, one must
3615 keep in mind that if your \bdirectivename{Volume Retention} period is too short, it
3616 may prune the last valid Full backup, and hence until the next Full
3617 backup is done, you will not have a complete backup of your system, and
3618 in addition, the next Incremental or Differential backup will be
3619 promoted to a Full backup. As a consequence, the minimum
3620 \bdirectivename{Volume Retention} period should be at twice the interval of your Full backups.
3621 This means that if you do a Full backup once a month, the minimum Volume
3622 retention period should be two months.
3623
3624 The default Volume retention period is \bdefaultvalue{365 days}, and either the default
3625 or the value defined by this directive in the \bfilename{bacula-dir.conf} file is
3626 the default value used when a Volume is created. Once the volume is
3627 created, changing the value in the \bfilename{bacula-dir.conf} file will not change
3628 what is stored for the Volume. To change the value for an existing
3629 Volume you must use the \bcommandname{update} command in the Console.
3630
3631 To disable the \bdirectivename{Volume Retention} feature, it is possible to
3632 set the directive to 0. When disabled, the pruning will be done only on the
3633 Job Retention directives and the "ExpiresIn" information available in the \bcommandname{list volume}
3634 output is not available.
3635
3636 \bwebdoc{Director:Pool:CacheRetention}
3637 \item [Cache Retention = \bbracket{time-period-specification}]
3638 \index[dir]{Directive!Cache Retention}
3639 The \bdirectivename{Cache Retention} directive defines the longest amount of time that
3640 bacula{} will keep Parts associated with the Volume in the Storage
3641 daemon Cache directory after a successful upload to the Cloud.
3642 When this time period expires, and if the \bcommandname{cloud prune} command
3643 is issued, \bacula{} may prune (remove) Parts that are older than the specified
3644 \bdirectivename{Cache Retention} period.
3645
3646 Note, it is also possible for all the Parts to be removed before the Cache
3647 Retention period is reached. In that case the \bcommandname{cloud truncate} command
3648 must be used.
3649
3650 \bwebdoc{Director:Pool:ActionOnPurge}
3651 \item [Action On Purge = \lt{Truncate}]
3652 \index[dir]{actiononpurge}
3653
3654 The directive \bvalueddirective{ActionOnPurge}{Truncate} instructs \bacula{} to
3655 permit the Volume to be truncated after it has been purged.
3656 Note: the ActionOnPurge is a bit misleading since the volume
3657 is not actually truncated when it is purged, but is enabled
3658 to be truncated. The actual truncation is done with the \bcommandname{truncate}
3659 command.
3660
3661 To actually truncate a Volume, you must first set the ActionOnPurge
3662 to Truncate in the Pool, then you must ensure that any existing
3663 Volumes also have this information in them, by doing an
3664 \bcommandname{update Volumes} comand. Finally, after the Volume
3665 has been purged, you may then truncate it.
3666 It is useful to prevent disk based volumes from consuming too much
3667 space. See below for more details of how to ensure Volumes are
3668 truncated after being purged.
3669
3670 First set the Pool to permit truncation.
3671 \begin{bVerbatim}
3672 Pool {
3673 Name = Default
3674 Action On Purge = Truncate
3675 ...
3676 }
3677 \end{bVerbatim}
3678
3679 Then assuming a Volume has been Purged, you can schedule
3680 truncate operation at the end of your CatalogBackup job
3681 like in this example:
3682
3683 \begin{bVerbatim}
3684 Job {
3685 Name = CatalogBackup
3686 ...
3687 RunScript {
3688 RunsWhen=After
3689 RunsOnClient=No
3690 Console = "truncate Volume allpools storage=File"
3691 }
3692 }
3693 \end{bVerbatim}
3694
3695
3696 \label{blb:PoolScratchPool}
3697 \bwebdoc{Director:Pool:ScratchPool}
3698 \item [ScratchPool = \bbracket{pool-resource-name}]
3699 \index[dir]{ScratchPool}
3700 \index[dir]{Directive!ScratchPool}
3701 This directive permits specifing a specific scratch Pool to be used for
3702 the Job. This pool will replace the default scratch pool named
3703 \textsl{Scratch} for volume selection. For more information about
3704 scratch pools see \bilink{Scratch Pool}{blb:TheScratchPool} section of this
3705 manual. This directive is useful when using multiple storage devices
3706 that share the same MediaType or when you want to dedicate volumes to a
3707 particular set of pools.
3708
3709
3710 \label{blb:PoolRecyclePool}
3711 \bwebdoc{Director:Pool:RecyclePool}
3712 \item [RecyclePool = \bbracket{pool-resource-name}]
3713 \index[dir]{RecyclePool}
3714 \index[dir]{Directive!RecyclePool}
3715 This directive defines to which pool
3716 the Volume will be placed (moved) when it is recycled. Without
3717 this directive, a Volume will remain in the same pool when it is
3718 recycled. With this directive, it will be moved automatically to any
3719 existing pool during a recycle. This directive is probably most
3720 useful when defined in the Scratch pool, so that volumes will
3721 be recycled back into the Scratch pool. For more on the see the
3722 \bilink{Scratch Pool}{blb:TheScratchPool} section of this manual.
3723
3724 Although this directive is called RecyclePool, the Volume in
3725 question is actually moved from its current pool to the one
3726 you specify on this directive when \bacula{} prunes the Volume and
3727 discovers that there are no records left in the catalog and hence
3728 marks it as \bstatus{Purged}.
3729
3730 \label{blb:PoolRecycle}
3731 \bwebdoc{Director:Pool:Recycle}
3732 \item [Recycle = \byesorno{}]
3733 \index[dir]{Recycle}
3734 \index[dir]{Directive!Recycle}
3735 This directive specifies whether or not Purged Volumes may be recycled.
3736 If it is set to \bdefaultvalue{yes} (default) and \bacula{} needs a volume but finds
3737 none that are appendable, it will search for and recycle (reuse) Purged
3738 Volumes (i.e. volumes with all the Jobs and Files expired and thus
3739 deleted from the Catalog). If the Volume is recycled, all previous data
3740 written to that Volume will be overwritten. If Recycle is set to \bvalue{no},
3741 the Volume will not be recycled, and hence, the data will remain
3742 valid. If you want to reuse (re-write) the Volume, and the recycle flag
3743 is no (0 in the catalog), you may manually set the recycle flag (\bcommandname{update}
3744 command) for a Volume to be reused.
3745
3746 Please note that the value defined by this directive in the
3747 \bfilename{bacula-dir.conf} file is the default value used when a Volume is created.
3748 Once the volume is created, changing the value in the \bfilename{bacula-dir.conf}
3749 file will not change what is stored for the Volume. To change the value
3750 for an existing Volume you must use the \bcommandname{update} command in the
3751 Console.
3752
3753 When all Job and File records have been pruned or purged from the
3754 catalog for a particular Volume, if that Volume is marked as
3755 \bstatus{Full} or \bstatus{Used}, it will then be marked as \bstatus{Purged}. Only
3756 Volumes marked as \bstatus{Purged} will be considered to be converted to the
3757 \bstatus{Recycled} state if the \bdirectivename{Recycle} directive is set to \bvalue{yes}.
3758
3759 \label{blb:RecycleOldest}
3760
3761 \bwebdoc{Director:Pool:RecycleOldestVolume}
3762 \item [Recycle Oldest Volume = \byesorno{}]
3763 \index[dir]{Recycle Oldest Volume}
3764 \index[dir]{Directive!Recycle Oldest Volume}
3765 This directive instructs the Director to search for the oldest used
3766 Volume in the Pool when another Volume is requested by the Storage
3767 daemon and none are available. The catalog is then \textbf{pruned}
3768 respecting the retention periods of all Files and Jobs written to this
3769 Volume. If all Jobs are pruned (i.e. the volume is Purged), then the
3770 Volume is recycled and will be used as the next Volume to be written.
3771 This directive respects any Job, File, or Volume retention periods that
3772 you may have specified, and as such it is \textbf{much} better to use this
3773 directive than the Purge Oldest Volume.
3774
3775 This directive can be useful if you have a fixed number of Volumes in the
3776 Pool and you want to cycle through them and you have specified the correct
3777 retention periods.
3778
3779 However, if you use this directive and have only one
3780 Volume in the Pool, you will immediately recycle your Volume if you fill
3781 it and \bacula{} needs another one. Thus your backup will be totally invalid.
3782 Please use this directive with care. The default is \bdefaultvalue{no}.
3783 \label{blb:RecycleCurrent}
3784
3785
3786 \bwebdoc{Director:Pool:RecycleCurrentVolume}
3787 \item [Recycle Current Volume = \byesorno{}]
3788 \index[dir]{Recycle Current Volume}
3789 \index[dir]{Directive!Recycle Current Volume}
3790 If \bacula{} needs a new Volume, this directive instructs \bacula{} to Prune
3791 the volume respecting the Job and File retention periods. If all Jobs
3792 are pruned (i.e. the volume is Purged), then the Volume is recycled and
3793 will be used as the next Volume to be written. This directive respects
3794 any Job, File, or Volume retention periods that you may have specified,
3795 and thus it is \textbf{much} better to use it rather than the Purge Oldest
3796 Volume directive.
3797
3798 This directive can be useful if you have a fixed number of Volumes in
3799 the Pool, you want to cycle through them, and you have specified
3800 retention periods that prune Volumes before you have cycled through the
3801 Volume in the Pool.
3802
3803 However, if you use this directive and have only one Volume in the Pool,
3804 you will immediately recycle your Volume if you fill it and \bacula{} needs
3805 another one. Thus your backup will be totally invalid. Please use this
3806 directive with care. The default is \bdefaultvalue{no}.
3807 \label{blb:PurgeOldest}
3808
3809
3810 \bwebdoc{Director:Pool:PurgeOldestVolume}
3811 \item [Purge Oldest Volume = \byesorno{}]
3812 \index[dir]{Purge Oldest Volume}
3813 \index[dir]{Directive!Purge Oldest Volume}
3814 This directive instructs the Director to search for the oldest used
3815 Volume in the Pool when another Volume is requested by the Storage
3816 daemon and none are available. The catalog is then \textbf{purged}
3817 irrespective of retention periods of all Files and Jobs written to this
3818 Volume. The Volume is then recycled and will be used as the next Volume
3819 to be written. This directive overrides any Job, File, or Volume
3820 retention periods that you may have specified.
3821
3822 This directive can be useful if you have a fixed number of Volumes in
3823 the Pool and you want to cycle through them and reusing the oldest one
3824 when all Volumes are full, but you don't want to worry about setting
3825 proper retention periods. However, by using this option you risk losing
3826 valuable data.
3827
3828 Please be aware that \bvalue{Purge Oldest Volume} disregards all retention
3829 periods. If you have only a single Volume defined and you turn this
3830 variable on, that Volume will always be immediately overwritten when it
3831 fills! So at a minimum, ensure that you have a decent number of Volumes
3832 in your Pool before running any jobs. If you want retention periods to
3833 apply do not use this directive. To specify a retention period, use the
3834 \bdirectivename{Volume Retention} directive (see above).
3835
3836 We \textbf{highly} recommend against using this directive, because it is
3837 sure that some day, \bacula{} will recycle a Volume that contains current
3838 data. The default is \bdefaultvalue{no}.
3839
3840 \bwebdoc{Director:Pool:FileRetention}
3841 \item [File Retention = \bbracket{time-period-specification}]
3842 \index[dir]{File Retention}
3843 \index[dir]{Directive!File Retention}
3844 The File Retention directive defines the length of time that \bacula{} will
3845 keep File records in the Catalog database after the End time of the
3846 Job corresponding to the File records.
3847
3848 This directive takes precedence over Client directives of the same name. For
3849 example, you can decide to increase Retention times for Archive or OffSite
3850 Pool.
3851
3852 Note, this affects only records in the catalog database. It does not affect
3853 your archive backups.
3854
3855 For more information see Client documentation about
3856 \bilink{FileRetention}{blb:FileRetention}
3857
3858 \bwebdoc{Director:Pool:JobRetention}
3859 \item [Job Retention = \bbracket{time-period-specification}]
3860 \index[dir]{Job Retention}
3861 \index[dir]{Directive!Job Retention}
3862
3863 The Job Retention directive defines the length of time that \bacula{} will keep
3864 Job records in the Catalog database after the Job End time. As with the
3865 other retention periods, this affects only records in the catalog and not
3866 data in your archive backup.
3867
3868 This directive takes precedence over Client directives of the same name.
3869 For example, you can decide to increase Retention times for Archive or
3870 OffSite Pool.
3871
3872 For more information see Client side documentation
3873 \bilink{JobRetention}{blb:JobRetention}
3874
3875 \bwebdoc{Director:Pool:CleaningPrefix}
3876 \item [Cleaning Prefix = \bbracket{string}]
3877 \index[dir]{Cleaning Prefix}
3878 \index[dir]{Directive!Cleaning Prefix}
3879 This directive defines a prefix string, which if it matches the
3880 beginning of a Volume name during labeling of a Volume, the Volume will
3881 be defined with the VolStatus set to \bstatus{Cleaning} and thus \bacula{} will
3882 never attempt to use this tape. This is primarily for use with
3883 autochangers that accept barcodes where the convention is that barcodes
3884 beginning with \bhighlight{CLN} are treated as cleaning tapes.
3885 \label{blb:Label}
3886
3887 \bwebdoc{Director:Pool:LabelFormat}
3888 \item [Label Format = \bbracket{format}]
3889 \index[dir]{Label Format}
3890 \index[dir]{Directive!Label Format}
3891 This directive specifies the format of the labels contained in this
3892 pool. The format directive is used as a sort of template to create new
3893 Volume names during automatic Volume labeling.
3894
3895 The \bbracket{format} should be specified in double quotes, and consists of
3896 letters, numbers and the special characters hyphen (\textbf{-}), underscore
3897 (\textbf{\_}), colon (\textbf{\string:}), and period (\textbf{.}), which are the legal
3898 characters for a Volume name. The \bbracket{format} should be enclosed in
3899 double quotes (").
3900
3901 In addition, the format may contain a number of variable expansion
3902 characters which will be expanded by a complex algorithm allowing you to
3903 create Volume names of many different formats. In all cases, the
3904 expansion process must resolve to the set of characters noted above that
3905 are legal Volume names. Generally, these variable expansion characters
3906 begin with a dollar sign (\textbf{\$}) or a left bracket (\textbf{[}). If you
3907 specify variable expansion characters, you should always enclose the
3908 format with double quote characters (\textbf{"}). For more details on
3909 variable expansion, please see the \bxlink{Variable Expansion}
3910 {blb:VarsChapter}{misc}{chapter} of the \bmiscman{}.
3911
3912 If no variable expansion characters are found in the string, the Volume
3913 name will be formed from the \bbracket{format} string appended with the
3914 a unique number that increases. If you do not remove volumes from the
3915 pool, this number should be the number of volumes plus one, but this
3916 is not guaranteed. The unique number will be edited as four
3917 digits with leading zeros. For example, with a
3918 \bvalueddirective{Label Format}{"File-"}, the first volumes will be named
3919 \bfilename{File-0001}, \bfilename{File-0002}, \ldots{}
3920
3921 With the exception of Job specific variables, you can test your
3922 \bdirectivename{LabelFormat} by using the \bxlink{var}{blb:var}{console}{command}
3923 in the \bconsoleman{}.
3924
3925 \begin{bVerbatim}
3926 Label Format="${Level}_${Type}_${Client}_${Year}-${Month:p/2/0/r}-${Day:p/2/0/r}"
3927 \end{bVerbatim}
3928
3929 Once defined, the name of the volume cannot be changed. When the volume is
3930 recycled, the volume can be used by an other Job at an other time, and
3931 possibly from an other Pool. In the example above, the volume defined
3932 with such name is probably not supposed to be recycled or reused.
3933
3934 In almost all cases, you should enclose the format specification (part
3935 after the equal sign) in double quotes.
3936
3937 \bwebdoc{Director:Pool:End}
3938 \end{bdescription}
3939
3940 In order for a Pool to be used during a Backup Job, the Pool must have at
3941 least one Volume associated with it. Volumes are created for a Pool using
3942 the \bcommandname{label} or the \bcommandname{add} commands in the \bacula{} \bconsolename{}
3943 program. In addition to adding Volumes to the Pool (i.e. putting the
3944 Volume names in the Catalog database), the physical Volume must be labeled
3945 with a valid \bacula{} software volume label before \bacula{} will accept
3946 the Volume. This will be automatically done if you use the \bcommandname{label}
3947 command. \bacula{} can automatically label Volumes if instructed to do so,
3948 but this feature is not yet fully implemented.
3949
3950 The following is an example of a valid Pool resource definition:
3951
3952 \begin{bVerbatim}
3953
3954 Pool {
3955 Name = Default
3956 Pool Type = Backup
3957 }
3958 \end{bVerbatim}
3959
3960 \label{blb:TheScratchPool}
3961 \subsection{The Scratch Pool}
3962 \index[general]{Scratch Pool}
3963 In general, you can give your Pools any name you wish, but there is one
3964 important restriction: the Pool named \bvalue{Scratch}, if it exists behaves
3965 like a scratch pool of Volumes in that when \bacula{} needs a new Volume for
3966 writing and it cannot find one, it will look in the Scratch pool, and if
3967 it finds an available Volume, it will move it out of the Scratch pool into
3968 the Pool currently being used by the job.
3969
3970
3971 \label{blb:CatalogResource}
3972 \section{The Catalog Resource}
3973 \index[general]{Resource!Catalog}
3974 \index[general]{Catalog Resource}
3975
3976 The Catalog Resource defines what catalog to use for the current job.
3977 Currently, \bacula{} can only handle a single database server (\mysql{},
3978 \postgresql{}) that is defined when configuring \bacula{}. However, there
3979 may be as many Catalogs (databases) defined as you wish. For example, you
3980 may want each Client to have its own Catalog database, or you may want
3981 backup jobs to use one database and verify or restore jobs to use another
3982 database.
3983
3984 Since both \mysql{} and \postgresql{} are networked
3985 databases, they may reside either on the same machine as the Director
3986 or on a different machine on the network. See below for more details.
3987
3988 \begin{bdescription}
3989
3990 \item [Catalog]
3991 \index[dir]{Catalog}
3992 \index[dir]{Directive!Catalog}
3993 Start of the Catalog resource. At least one Catalog resource must be
3994 defined.
3995
3996
3997 \bwebdoc{Director:Catalog:Name}
3998 \item [Name = \bbracket{name}]
3999 \index[dir]{Name}
4000 \index[dir]{Directive!Name}
4001 The name of the Catalog. No necessary relation to the database server
4002 name. This name will be specified in the Client resource directive
4003 indicating that all catalog data for that Client is maintained in this
4004 Catalog. This directive is required.
4005
4006 \bwebdoc{Director:Catalog:Password}
4007 \item [password = \bbracket{password}]
4008 \index[dir]{password}
4009 \index[dir]{Directive!password}
4010 This specifies the password to use when logging into the database. This
4011 directive is required.
4012
4013 \bwebdoc{Director:Catalog:DbName}
4014 \item [DB Name = \bbracket{name}]
4015 \index[dir]{DB Name}
4016 \index[dir]{Directive!DB Name}
4017 This specifies the name of the database. If you use multiple catalogs
4018 (databases), you specify which one here. If you are using an external
4019 database server rather than the internal one, you must specify a name
4020 that is known to the server (i.e. you explicitly created the \bacula{}
4021 tables using this name. This directive is required.
4022
4023 \bwebdoc{Director:Catalog:User}
4024 \item [user = \bbracket{user}]
4025 \index[dir]{user}
4026 \index[dir]{Directive!user}
4027 This specifies what user name to use to log into the database. This
4028 directive is required.
4029
4030 \bwebdoc{Director:Catalog:DbSocket}
4031 \item [DB Socket = \bbracket{socket-name}]
4032 \index[dir]{DB Socket}
4033 \index[dir]{Directive!DB Socket}
4034 This is the name of a socket to use on the local host to connect to the
4035 database. This directive is used only by \mysql{}.
4036 Normally, if neither \bdirectivename{DB Socket} or \bdirectivename{DB Address} are specified, \mysql{}
4037 will use the default socket. If the DB Socket is specified, the
4038 \mysql{} server must reside on the same machine as the Director.
4039
4040 \bwebdoc{Director:Catalog:DBAddress}
4041 \item [DB Address = \bbracket{address}]
4042 \index[dir]{DB Address}
4043 \index[dir]{Directive!DB Address}
4044 This is the host address of the database server. Normally, you would specify
4045 this instead of \bdirectivename{DB Socket} if the database server is on another machine.
4046 In that case, you will also specify \bdirectivename{DB Port}. This directive is used
4047 only by \mysql{} and \postgresql{}.
4048 This directive is optional.
4049
4050 \bwebdoc{Director:Catalog:DbPort}
4051 \item [DB Port = \bbracket{port}]
4052 \index[dir]{DB Port}
4053 \index[dir]{Directive!DBPort}
4054 This defines the port to be used in conjunction with \bdirectivename{DB Address} to
4055 access the database if it is on another machine. This directive is used only
4056 by \mysql{} and \postgresql{}. This
4057 directive is optional.
4058
4059 \bwebdoc{Director:Catalog:End}
4060
4061 %% \item [Multiple Connections = \byesorno{}]
4062
4063 %% \index[dir]{Directive!Multiple Connections}
4064 %% By default, this directive is set to no. In that case, each job that uses the
4065 %% same Catalog will use a single connection to the catalog. It will be shared,
4066 %% and \bacula{} will allow only one Job at a time to communicate. If you set this
4067 %% directive to yes, \bacula{} will permit multiple connections to the database,
4068 %% and the database must be multi-thread capable. For \postgresql{},
4069 %% this is no problem. For \mysql{}, you must be *very* careful to have the
4070 %% multi-thread version of the client library loaded on your system. When this
4071 %% directive is set yes, each Job will have a separate connection to the
4072 %% database, and the database will control the interaction between the different
4073 %% Jobs. This can significantly speed up the database operations if you are
4074 %% running multiple simultaneous jobs. In addition, for \postgresql{},
4075 %% \bacula{} will automatically enable transactions. This can significantly speed
4076 %% up insertion of attributes in the database either for a single Job or
4077 %% multiple simultaneous Jobs.
4078
4079 %% This directive has not been tested. Please test carefully before running it
4080 %% in production and report back your results.
4081
4082 \end{bdescription}
4083
4084 The following is an example of a valid Catalog resource definition:
4085
4086 \begin{bVerbatim}
4087 Catalog
4088 {
4089 Name = MySQL
4090 dbname = bacula;
4091 user = bacula;
4092 password = "" # no password = no security
4093 }
4094 \end{bVerbatim}
4095
4096 or for a Catalog on another machine:
4097
4098 \begin{bVerbatim}
4099 Catalog
4100 {
4101 Name = MySQL
4102 dbname = bacula
4103 user = bacula
4104 password = ""
4105 DB Address = remote.acme.com
4106 DB Port = 1234
4107 }
4108 \end{bVerbatim}
4109
4110 \label{blb:MessagesResource2}
4111 \section{The Messages Resource}
4112 \index[general]{Resource!Messages}
4113 \index[general]{Messages Resource}
4114
4115 For the details of the Messages Resource, please see the
4116 \bilink{Messages Resource Chapter}{blb:MessagesChapter} of this
4117 manual.
4118
4119 \label{blb:ConsoleResource1}
4120 \section{The Console Resource}
4121 \index[general]{Console Resource}
4122 \index[general]{Resource!Console}
4123
4124 As of \bacula{} version 1.33 and higher, there are three different kinds of
4125 consoles, which the administrator or user can use to interact with the
4126 Director. These three kinds of consoles comprise three different security
4127 levels.
4128
4129 \begin{bitemize}
4130 \item The first console type is an \textbf{anonymous} or \textbf{default} console,
4131 which has full privileges. There is no console resource necessary for
4132 this type since the password is specified in the Director's resource and
4133 consequently such consoles do not have a name as defined on a \bvalueddirective{Name}{}
4134 directive. This is the kind of console that was initially
4135 implemented in versions prior to 1.33 and remains valid. Typically you
4136 would use it only for administrators.
4137
4138 \item The second type of console, and new to version 1.33 and higher is a
4139 ``named'' console defined within a Console resource in both the Director's
4140 configuration file and in the Console's configuration file. Both the
4141 names and the passwords in these two entries must match much as is the
4142 case for Client programs.
4143
4144 This second type of console begins with absolutely no privileges except
4145 those explicitly specified in the Director's Console resource. Thus you
4146 can have multiple Consoles with different names and passwords, sort of
4147 like multiple users, each with different privileges. As a default,
4148 these consoles can do absolutely nothing -- no commands whatsoever. You
4149 give them privileges or rather access to commands and resources by
4150 specifying access control lists in the Director's Console resource. The
4151 ACLs are specified by a directive followed by a list of access names.
4152 Examples of this are shown below.
4153
4154 \item The third type of console is similar to the above mentioned one in that
4155 it requires a Console resource definition in both the Director and the
4156 Console. In addition, if the console name, provided on the \bvalueddirective{Name}{}
4157 directive, is the same as a Client name, that console is permitted to
4158 use the \bcommandname{SetIP} command to change the Address directive in the
4159 Director's client resource to the \acs{IP} address of the Console. This
4160 permits portables or other machines using \acs{DHCP} (non-fixed \acs{IP} addresses)
4161 to ``notify'' the Director of their current \acs{IP} address.
4162 \end{bitemize}
4163
4164 The Console resource is optional and need not be specified. The following
4165 directives are permitted within the Director's configuration resource:
4166
4167 \begin{bdescription}
4168
4169 \bwebdoc{Director:Console:Name}
4170 \item [Name = \bbracket{name}]
4171 \index[dir]{Name}
4172 \index[dir]{Directive!Name}
4173 The name of the console. This name must match the name specified in the
4174 Console's configuration resource (much as is the case with Client
4175 definitions).
4176
4177 \bwebdoc{Director:Console:Password}
4178 \item [Password = \bbracket{password}]
4179 \index[dir]{Password}
4180 \index[dir]{Directive!Password}
4181 Specifies the password that must be supplied for a named \bacula{} Console
4182 to be authorized. The same password must appear in the \bresourcename{Console}
4183 resource of the Console configuration file. For added security, the
4184 password is never actually passed across the network but rather a
4185 challenge response hash code created with the password. This directive
4186 is required. If you have either \btool{/dev/random} or \btool{bc} on your
4187 machine, \bacula{} will generate a random password during the configuration
4188 process, otherwise it will be left blank.
4189
4190 The password is plain text. It is not generated through any special
4191 process. However, it is preferable for security reasons to choose
4192 random text.
4193
4194 \bwebdoc{Director:Console:AuthenticationPlugin}
4195 \item [AuthenticationPlugin = \bbracket{plugin-definition}]
4196 \index[dir]{AuthenticationPlugin}
4197 \index[dir]{Directive!AuthenticationPlugin}
4198
4199 Specifies the a plugin to use the authentication API framework which allows to
4200 configure a different set of authentication mechanisms (user credentials
4201 verification) using a dedicated Director plugins. It is called BPAM (Bacula
4202 Pluggable Authentication Modules). The first plugin available is a LDAP connector
4203 that is suitable to connect OpenLDAP or ActiveDirectory.
4204
4205 The new framework support standard \texttt{user/password} and \texttt{MFA}
4206 authentication schemes which are fully driven by external plugins. On the
4207 client side \texttt{bconsole} when noticied will perform user interaction to collect
4208 required credentials. Bacula will still support all previous authentication
4209 schemas including \texttt{CRAM-MD5} and \texttt{TLS}. You can even configure \texttt{TLS
4210 Authentication} together with new BPAM authentication raising required security
4211 level. BPAM authentication is available for named Console resources only.
4212
4213 To use this feature you have to load dedicated Director plugin from directory
4214 pointed by \texttt{Plugin Directory} Director resource configuration. This
4215 plugin should be listed in director status command. Then you should configure
4216 the Console resource to use this plugin for authentication with the
4217 \texttt{Authentication Plugin} directive together with a named Console
4218 configuration in \texttt{bconsole.conf} as described in Console
4219 Configuration chapter of this manual.
4220
4221
4222 \begin{bVerbatim}
4223 Console {
4224 Name = "ldapconsole"
4225 Password = "xxx"
4226
4227 Authentication Plugin = "ldap:<parameters>"
4228 }
4229 \end{bVerbatim}
4230
4231 where \texttt{parameters} are the space separated list of one or more plugin parameters:
4232
4233 \begin{itemize}
4234 \item [url] - LDAP Directory service location, i.e. "url=ldap://10.0.0.1/"
4235 \item [binddn] - DN used to connect to LDAP Directory service to perform required \texttt{query}
4236 \item [bindpass] - DN password used to connect to LDAP Directory service to perform required \texttt{query}
4237 \item [query] - a query performed on LDAP Directory serice to find user for authentication.
4238 The \texttt{query} string is composed as \texttt{<basedn>/<filter>}. Where `\texttt{<basedn>} is a DN search starting
4239 point and \texttt{<filter>} is a standard LDAP search object filter which support dynamic string
4240 substitution: \texttt{\%u} will be replaced by credential's username and \texttt{\%p} by credential's
4241 password, i.e. \texttt{query=dc=bacula,dc=com/(cn=\%u)}.
4242 \item [starttls] - instruct BPAM LDAP Plugin to use \texttt{StartTLS} extension if LDAP Directory service
4243 will support it and follback to no TLS if this extension is not available.
4244 \item [starttlsforce] - does the same what `starttls` but resport error on fallback.
4245 \end{itemize}
4246
4247 The working configuration examples:
4248
4249 \smallskip
4250 bacula-dir.conf - Console resource configuration for BPAM LDAP Plugin with OpenLDAP authentication example.
4251
4252 \begin{bVerbatim}
4253 Console {
4254 Name = "bacula_ldap_console"
4255 Password = "xxx"
4256
4257 # New directive (on a single line)
4258 Authentication Plugin = "ldap:url=ldap://ldapsrv/
4259 binddn=cn=root,dc=bacula,dc=com bindpass=secret
4260 query=dc=bacula,dc=com/(cn=%u) starttls"
4261 ...
4262 }
4263 \end{bVerbatim}
4264
4265
4266 bacula-dir.conf - Console resource configuration for BPAM LDAP Plugin with Active Directory authentication example.
4267
4268 {\small
4269 \begin{bVerbatim}
4270 Console {
4271 Name = "bacula_ad_console"
4272 Password = "xxx"
4273
4274 # New directive (on a single line)
4275 Authentication Plugin = "ldap:url=ldaps://ldapsrv/
4276 binddn=cn=bacula,ou=Users,dc=bacula,dc=com bindpass=secret
4277 query=dc=bacula,dc=com/(&(objectCategory=person)(objectClass=user)(sAMAccountName=%u))"
4278 ...
4279 }
4280 \end{bVerbatim}
4281 }
4282
4283 \input{DirectorConsoleTls}
4284
4285 \bwebdoc{Director:Console:JobAcl}
4286 \item [JobACL = \bbracket{name-list}]
4287 \index[dir]{JobACL}
4288 \index[dir]{Directive!JobACL}
4289 This directive is used to specify a list of Job resource names that can
4290 be accessed by the console. Without this directive, the console cannot
4291 access any of the Director's Job resources. Multiple Job resource names
4292 may be specified by separating them with commas, and/or by specifying
4293 multiple JobACL directives. For example, the directive may be specified
4294 as:
4295
4296 \begin{bVerbatim}
4297 JobACL = kernsave, "Backup client 1", "Backup client 2"
4298 JobACL = "RestoreFiles"
4299 \end{bVerbatim}
4300
4301 With the above specification, the console can access the Director's resources
4302 for the four jobs named on the JobACL directives, but for no others.
4303
4304 \bwebdoc{Director:Console:ClientAcl}
4305 \item [ClientACL = \bbracket{name-list}]
4306 \index[dir]{ClientACL}
4307 \index[dir]{Directive!ClientACL}
4308
4309 This directive is used to specify a list of \bresourcename{Client} resource names that can
4310 be accessed by the console.
4311
4312 \bwebdoc{Director:Console:RestoreClientAcl}
4313 \item [RestoreClientACL = \bbracket{name-list}]
4314 \index[dir]{RestoreClientACL}
4315 \index[dir]{Directive!RestoreClientACL}
4316
4317 This directive is used to specify a list of \bresourcename{Client} resource names that can
4318 be used by the console to restore files. The \bdirectivename{ClientAcl} is not
4319 affected by the \bdirectivename{RestoreClientACL} directive.
4320
4321 \begin{bVerbatim}
4322 ClientAcl = localhost-fd # backup and restore
4323 RestoreClientAcl = test-fd # restore only
4324 BackupClientAcl = production-fd # backup only
4325 \end{bVerbatim}
4326
4327 \bwebdoc{Director:Console:BackupClientAcl}
4328 \item [BackupClientACL = \bbracket{name-list}]
4329 \index[dir]{BackupClientACL}
4330 \index[dir]{Directive!BackupClientACL}
4331
4332 This directive is used to specify a list of \bresourcename{Client} resource names that can
4333 be used by the console to backup files. The \bdirectivename{ClientAcl} is not
4334 affected by the \bdirectivename{RestoreClientACL} directive.
4335
4336 \bwebdoc{Director:Console:DirectoryAcl}
4337 \item [DirectoryACL = \bbracket{name-list}]
4338 \index[dir]{Directive!DirectoryACL}
4339 \index[dir]{DirectoryACL}
4340
4341 This directive is used to specify a list of directories that can be accessed by
4342 a restore session. Without this directive, the console cannot restore any
4343 file. Multiple directories names may be specified by separating them with
4344 commas, and/or by specifying multiple \bdirectivename{DirectoryACL} directives.
4345
4346 \bwebdoc{Director:Console:UserIdAcl}
4347 \item [UserIdACL = \bbracket{name-list}]
4348 \index[dir]{Directive!UserIdACL}
4349
4350 This directive is used to specify a list of \texttt{UID}/\texttt{GID} that can be accessed from a
4351 restore session. Without this directive, the console cannot restore any
4352 file. During the restore session, the Director will compute the restore list
4353 and will exclude files and directories that cannot be accessed. \bacula{} uses the
4354 LStat database field to retrieve \texttt{st\_mode}, \texttt{st\_uid} and
4355 \texttt{st\_gid} information for each file and compare them with the UserIdACL
4356 elements. If a parent directory doesn't have a proper catalog entry, the access
4357 to this directory will be automatically granted.
4358
4359 \texttt{UID}/\texttt{GID} names are resolved with \btool{getpwnam()} function within the Director. The
4360 User \texttt{UID}/\texttt{GID} mapping might be different from one system to an other.
4361
4362 Windows systems are not compatible with the \bdirectivename{UserIdACL} feature. The use of
4363 \bvalueddirective{UserIdACL}{*all*} is required to restore Windows systems from a
4364 restricted Console.
4365
4366 Multiple \texttt{UID}/\texttt{GID} names may be specified by separating them with
4367 commas, and/or by specifying multiple \bdirectivename{UserIdACL} directives.
4368
4369 \bwebdoc{Director:Console:StorageAcl}
4370 \item [StorageACL = \bbracket{name-list}]
4371 \index[dir]{StorageACL}
4372 \index[dir]{Directive!StorageACL}
4373 This directive is used to specify a list of Storage resource names that can
4374 be accessed by the console.
4375
4376 \bwebdoc{Director:Console:ScheduleAcl}
4377 \item [ScheduleACL = \bbracket{name-list}]
4378 \index[dir]{ScheduleACL}
4379 \index[dir]{Directive!ScheduleACL}
4380 This directive is used to specify a list of Schedule resource names that can
4381 be accessed by the console.
4382
4383 \bwebdoc{Director:Console:PoolAcl}
4384 \item [PoolACL = \bbracket{name-list}]
4385 \index[dir]{PoolACL}
4386 \index[dir]{Directive!PoolACL}
4387 This directive is used to specify a list of Pool resource names that can be
4388 accessed by the console.
4389
4390 \bwebdoc{Director:Console:FileSetAcl}
4391 \item [FileSetACL = \bbracket{name-list}]
4392 \index[dir]{FileSetACL}
4393 \index[dir]{Directive!FileSetACL}
4394 This directive is used to specify a list of FileSet resource names that
4395 can be accessed by the console.
4396
4397 \bwebdoc{Director:Console:CatalogAcl}
4398 \item [CatalogACL = \bbracket{name-list}]
4399 \index[dir]{CatalogACL}
4400 \index[dir]{Directive!CatalogACL}
4401 This directive is used to specify a list of Catalog resource names that
4402 can be accessed by the console.
4403
4404 \bwebdoc{Director:Console:CommandAcl}
4405 \item [CommandACL = \bbracket{name-list}]
4406 \index[dir]{CommandACL}
4407 \index[dir]{Directive!CommandACL}
4408 This directive is used to specify a list of console commands that can
4409 be executed by the console.
4410
4411 \bwebdoc{Director:Console:WhereAcl}
4412 \item [WhereACL = \bbracket{string}]
4413 \index[dir]{WhereACL}
4414 \index[dir]{Directive!WhereACL}
4415 This directive permits you to specify where a restricted console
4416 can restore files. If this directive is not specified, only the
4417 default restore location is permitted (normally \bdefaultvalue{/tmp/bacula-restores}).
4418 If \bkeyword{*all*} is specified any path the user enters will be accepted (not very secure), any other
4419 value specified (there may be multiple WhereACL directives) will
4420 restrict the user to use that path. For example, on a Unix system,
4421 if you specify ``/'', the file will be restored to the original
4422 location. This directive is untested.
4423 \bwebdoc{Director:Console:AclEnd}
4424 \end{bdescription}
4425
4426 Aside from Director resource names and console command names, the special
4427 keyword \bkeyword{*all*} can be specified in any of the above access control lists.
4428 When this keyword is present, any resource or command name (which ever is
4429 appropriate) will be accepted. For an example configuration file, please see
4430 the \bilink{Console Configuration}{blb:ConsoleConfChapter} chapter of this
4431 manual.
4432
4433 \smallskip
4434
4435 Please note the \bkeyword{*all*} keyword must be used alone in an ACL list. The
4436 following definition will be interpreted as a "Glob Pattern" for any FileSet
4437 including the "all" string:
4438
4439 \begin{bVerbatim}
4440 FileSetACL = fs-test*, *all*
4441 \end{bVerbatim}
4442
4443 or
4444
4445 \begin{bVerbatim}
4446 FileSetACL = fs-test*
4447 FileSetACL = *all*
4448 \end{bVerbatim}
4449
4450 \smallskip
4451
4452 All \acs{ACL} Resource directives (\bdirectivename{JobACL}, \bdirectivename{ClientACL}, \bdirectivename{FileSetACL}, \ldots{}) can accept
4453 ``Glob Patterns'' such as \bvalue{*.prod} or `\bvalue{job.client1.*} to ease the
4454 configuration.
4455
4456 \begin{bVerbatim}
4457 ClientAcl = test-*
4458 JobACL = job-test-*
4459 FileSetACL = fs-test*
4460 \end{bVerbatim}
4461
4462
4463
4464 \label{blb:CounterResource}
4465 \section{The Counter Resource}
4466 \index[general]{Resource!Counter}
4467 \index[general]{Counter Resource}
4468
4469 The Counter Resource defines a counter variable that can be accessed by
4470 variable expansion used for creating Volume labels with the \bdirectivename{LabelFormat}
4471 directive. See the
4472 \bilink{LabelFormat}{blb:Label} directive in this chapter for more
4473 details.
4474
4475 \begin{bdescription}
4476
4477 \item [Counter]
4478 \index[dir]{Counter}
4479 \index[dir]{Directive!Counter}
4480 Start of the Counter resource. Counter directives are optional.
4481
4482 \bwebdoc{Director:Counter:Name}
4483 \item [Name = \bbracket{name}]
4484 \index[dir]{Name}
4485 \index[dir]{Directive!Name}
4486 The name of the Counter. This is the name you will use in the variable
4487 expansion to reference the counter value.
4488
4489 \bwebdoc{Director:Counter:Minimum}
4490 \item [Minimum = \bbracket{integer}]
4491 \index[dir]{Minimum}
4492 \index[dir]{Directive!Minimum}
4493 This specifies the minimum value that the counter can have. It also becomes
4494 the default. If not supplied, \bdefaultvalue{zero} is assumed.
4495
4496 \bwebdoc{Director:Counter:Maximum}
4497 \item [Maximum = \bbracket{integer}]
4498 \index[dir]{Maximum}
4499 \index[dir]{Directive!Maximum}
4500 \index[dir]{Directive!Maximum}
4501 This is the maximum value value that the counter can have. If not specified
4502 or set to zero, the counter can have a maximum value of 2,147,483,648 (2 to
4503 the 31 power). When the counter is incremented past this value, it is reset
4504 to the Minimum.
4505
4506 \bwebdoc{Director:Counter:*WrapCounter}
4507 \item [*WrapCounter = \bbracket{counter-name}]
4508 \index[dir]{*WrapCounter}
4509 \index[dir]{Directive!*WrapCounter}
4510 If this value is specified, when the counter is incremented past the
4511 maximum
4512 and thus reset to the minimum, the counter specified on the \textbf{WrapCounter}
4513 is incremented. (This is not currently implemented).
4514
4515 \bwebdoc{Director:Counter:Catalog}
4516 \item [Catalog = \bbracket{catalog-name}]
4517 \index[dir]{Catalog}
4518 \index[dir]{Directive!Catalog}
4519 If this directive is specified, the counter and its values will be saved in
4520 the specified catalog. If this directive is not present, the counter will be
4521 redefined each time that \bacula{} is started.
4522
4523 \bwebdoc{Director:Counter:End}
4524 \end{bdescription}
4525
4526 \bwebdoc{StatisticsResource}
4527 \section{The Statistics Resource}
4528 \index[general]{Resource!Statistics}
4529 \index[general]{Statistics Resource}
4530
4531 The \bresourcename{Statistics} Resource defines the statistic collector function that can send
4532 information to a Graphite instance, to a \acs{CSV} file or to \bconsolename{} with the
4533 \bcommandname{statistics} command (See \vref{blb:CollectCommand} for more information).
4534
4535 \begin{bdescription}
4536 \item [Statistics]
4537 \index[dir]{Statistics}
4538 \index[dir]{Directive!Statistics}
4539 Start of the \bresourcename{Statistics} resource. Statistics directives are optional.
4540
4541 \bwebdoc{Director:Statistics:Name}
4542 \item [Name = \bbracket{name}]
4543 \index[dir]{Name}
4544 \index[dir]{Directive!Name}
4545 The Statistics directive \bdirectivename{name} is used by the system administrator. This
4546 directive is required.
4547
4548 \bwebdoc{Director:Statistics:Description}
4549 \item [Description = \bbracket{string}]
4550 \index[dir]{Description}
4551 \index[dir]{Directive!Description}
4552
4553 The text field contains a description of the Statistics that will be
4554 displayed in the graphical user interface. This directive is optional.
4555
4556 \bwebdoc{Director:Statistics:Interval}
4557 \item [Interval = \bbracket{time-interval}]
4558 \index[dir]{Interval}
4559 \index[dir]{Directive!Interval}
4560 \index[dir]{Directive!Interval}
4561
4562 The \bdirectivename{Intervall} directive instructs the Statistics thread how long it should sleep
4563 between every collection iteration. This directive is optional and the default
4564 value is \bdefaultvalue{300} seconds.
4565
4566 \bwebdoc{Director:Statistics:Type}
4567 \item [Type = \bbracket{CSV|Graphite}]
4568 \index[dir]{Type}
4569 \index[dir]{Directive!Type}
4570
4571 The \bdirectivename{Type} directive specifies the Statistics backend, which may be one of the
4572 following: \bvalue{CSV} or \bvalue{Graphite}. This directive is required.
4573 \smallskip
4574
4575 \acs{CSV} is a simple file level backend which saves all required metrics with the
4576 following format to the file: ``\bbracket{time}, \bbracket{metric}, \bbracket{value}\textbackslash{}n''
4577
4578 Where \bbracket{time} is a standard Unix time (a number of seconds from 1/01/1970)
4579 with local timezone as returned by a system call \btool{time()}, \bbracket{metric} is a
4580 \bacula{} metric string and \bbracket{value} is a metric value which could be in numeric
4581 format (\texttt{int}/\texttt{float}) or a string \bvalue{True} or \bvalue{False} for boolean variable. The
4582 \acs{CSV} backend requires the \bvalueddirective{File}{~} parameter.
4583 \smallskip
4584
4585 Graphite is a network backend which will send all required metrics to a Graphite
4586 server. The Graphite backend requires the \bvalueddirective{Host}{~} and \bvalueddirective{Port}{~} directives to be set.
4587
4588 If the Graphite server is not available, the metrics are automatically
4589 spooled in the working directory. When the server can be reached again,
4590 spooled metrics are despooled automatically and the spooling function is
4591 suspended.
4592
4593
4594 \bwebdoc{Director:Statistics:Metrics}
4595 \item [Metrics = \bbracket{metricspec}]
4596 \index[dir]{Metrics}
4597 \index[dir]{Directive!Metrics}
4598
4599 The \bdirectivename{Metrics} directive allow metric filtering and \bbracket{metricspec} is a filter which
4600 enables to use \bvalue{*} and \bvalue{?} characters to match the required metric name in the
4601 same way as found in shell wildcard resolution. You can exclude filtered
4602 metric with \bvalue{!} prefix. You can define any number of filters for a single
4603 Statistics. Metrics filter is executed in order as found in
4604 configuration. This directive is optional and if not used all available
4605 metrics will be saved by this statistics backend.
4606 \smallskip
4607
4608 Example:
4609 \begin{bVerbatim}
4610 # Include all metric starting with "bacula.jobs"
4611 Metrics = "bacula.jobs.*"
4612
4613 # Exclude any metric starting with "bacula.jobs"
4614 Metrics = "!bacula.jobs.*"
4615 \end{bVerbatim}
4616
4617 \bwebdoc{Director:Statistics:Prefix}
4618 \item [Prefix = \bbracket{string}]
4619 \index[dir]{Prefix}
4620 \index[dir]{Directive!Prefix}
4621
4622 The \bdirectivename{Prefix} allows to alter the metrics name saved by statistics to
4623 distinguish between different installations or daemons. The prefix string
4624 will be added to metric name as: ``\bbracket{prefix}.\bbracket{metric\_name}'' This directive is
4625 optional.
4626
4627 \bwebdoc{Director:Statistics:Prefix}
4628 \item [File = \bbracket{filename}]
4629 \index[dir]{File}
4630 \index[dir]{Directive!File}
4631
4632 The File is used by the \acs{CSV} statistics backend and point to the full
4633 path and filename of the file where metrics will be saved. With the \acs{CSV}
4634 type, the \bdirectivename{File} directive is required. The statistics thread must have the
4635 permissions to write to the selected file or create a new file if the file
4636 doesn't exist. If statistics is unable to write to the file or create a new
4637 one then the collection terminates and an error message will be
4638 generated. The file is only open during the dump and is closed
4639 otherwise. Statistics file rotation could be executed by a \btool{mv} shell command.
4640
4641 \bwebdoc{Director:Statistics:Host}
4642 \item [Host = \bbracket{hostname}]
4643 \index[dir]{Host}
4644 \index[dir]{Directive!Host}
4645
4646 The \bdirectivename{Host} directive is used for Graphite backend and specify the
4647 hostname or the \acs{IP} address of the Graphite server. When the directive \bdirectivename{Type}
4648 is set to Graphite, the Host directive is required.
4649
4650 \bwebdoc{Director:Statistics:Port}
4651 \item [Host = \bbracket{number}]
4652 \index[dir]{Port}
4653 \index[dir]{Directive!Port}
4654
4655 The \bdirectivename{Port} directive is used for Graphite backend and specify the \acs{TCP} port
4656 number of the Graphite server. When the directive \bdirectivename{Type}
4657 is set to Graphite, the \bdirectivename{Port} directive is required.
4658
4659
4660 \bwebdoc{Director:Statistics:End}
4661 \end{bdescription}
4662
4663
4664 \label{blb:Console:AuthenticationPlugin}
4665 \section{Console Multi-Factor Authentication Plugins}
4666 \label{TOTPPlugin}
4667
4668 \subsection{Time-based One-Time Password (TOTP) Authentication Plugin}
4669
4670 The TOTP Authentication Plugin is compatible with the RFC 6238. Many smartphone
4671 apps are available to store the keys and compute the TOTP code.
4672
4673 \begin{bVerbatim}
4674 Console {
4675 Name = "totpconsole"
4676 Password = "xxx"
4677
4678 Authentication Plugin = "totp:<parameters>"
4679 }
4680 \end{bVerbatim}
4681
4682 where \texttt{parameters} are the space separated list of one or more plugin parameters:
4683
4684 \begin{itemize}
4685 \item [keydir] - The directory where the TOTP keys are stored. \texttt{/opt/bacula/etc/conf.d/totp} by default.
4686 \item [no\_qrcode] - Do not generate QR code at the first connection. The Bacula administrator must provide the
4687 TOTP key to users manually using the \texttt{btotp} command for example.
4688 \item [sendcommand] - Use the command specified by \texttt{sendcommand} to send the QRCode as a PNG image to the user.
4689 \end{itemize}
4690
4691 The working configuration examples:
4692
4693 \smallskip
4694 bacula-dir.conf - Console resource configuration for BPAM TOTP Plugin example.
4695
4696 \begin{bVerbatim}
4697 # In bacula-dir.conf
4698 Console {
4699 Name = "totpconsole"
4700 Password = "xxx"
4701
4702 # New directive
4703 Authentication Plugin = "totp"
4704 }
4705
4706 # in bconsole.conf
4707 Console {
4708 Name = totpconsole
4709 Password = "xxx" # Same as in bacula-dir.conf/Console
4710 }
4711 Director {
4712 Name = mydir-dir
4713 Address = localhost
4714 Password = notused
4715 }
4716 \end{bVerbatim}
4717
4718 At the first console connection, if the TLS link is correctly setup
4719 (using the shared secret key), the plugin will generate a specific
4720 random key for the console and display a QR code in the console
4721 output. The user must then scan the QR code with his smartphone using
4722 an app such as Google Authenticator or Aegis (Opensource).
4723
4724 \smallskip
4725
4726 The program \texttt{qrencode} ($>=$ 4.0) is used to convert the otpauth
4727 URL to a QR code.
4728
4729 \smallskip
4730
4731 The \texttt{btotp} command can be used to manipulate TOTP keys. For example,
4732 to generate the QR code in the terminal:
4733
4734 \begin{bVerbatim}
4735 # /opt/bacula/bin/btotp -n totpconsole -q
4736 \end{bVerbatim}
4737
4738 To generate the otpauth URL in the terminal (can be used to generate a
4739 QRcode later) with \texttt{qrencode}:
4740
4741 \begin{bVerbatim}
4742 # /opt/bacula/bin/btotp -n totpconsole -u
4743 otpauth://totp/Bacula:totpconsole?secret=OR2TM22...&issuer=Bacula
4744 \end{bVerbatim}
4745
4746 \smallskip
4747
4748 In this example, the QR code is sent by email to the console owner:
4749 \begin{bVerbatim}
4750 # In bacula-dir.conf
4751 Console {
4752 Name = "roberto"
4753 Password = "xxx"
4754
4755 # New directive
4756 Authentication Plugin = "totp: sendcommand=\"mpack -s 'Bacula Console Access for %d' -d /opt/bacula/etc/template %a %[email protected]\"\""
4757 }
4758
4759 # in bconsole.conf
4760 Console {
4761 Name = roberto
4762 Password = "xxx" # Same as in bacula-dir.conf/Console
4763 }
4764 Director {
4765 Name = mydir-dir
4766 Address = localhost
4767 Password = notused
4768 }
4769 \end{bVerbatim}
4770
4771 At the first console connection, the plugin will generate a specific
4772 random key for the console and send a QR code PNG file via the command
4773 configured. In the example, the mail command mpack will send an email
4774 with the attachement to the email ``[email protected]''
4775
4776 \begin{bVerbatim}
4777 Subject: Bacula Console Access for mydirector-dir
4778
4779 Please find the QR Code needed to access the
4780 Bacula director
4781
4782 ---image attached---
4783
4784 \end{bVerbatim}
4785
4786 The following variables can be used in the \texttt{sendcommand} string:
4787 \begin{itemize}
4788 \item [\%a] - Path to the QR code png file
4789 \item [\%d] - Director name
4790 \item [\%c] - Console name
4791 \end{itemize}
4792
4793 \subsection{LDAP Authentication Plugin}
4794
4795 A LDAP Authentication Plugin that is suitable to connect OpenLDAP or
4796 ActiveDirectory connector plugins is available.
4797
4798 \begin{bVerbatim}
4799 Console {
4800 Name = "ldapconsole"
4801 Password = "xxx"
4802
4803 Authentication Plugin = "ldap:<parameters>"
4804 }
4805 \end{bVerbatim}
4806
4807 where \texttt{parameters} are the space separated list of one or more plugin parameters:
4808
4809 \begin{itemize}
4810 \item [url] - LDAP Directory service location, i.e. "url=ldap://10.0.0.1/"
4811 \item [binddn] - DN used to connect to LDAP Directory service to perform required \texttt{query}
4812 \item [bindpass] - DN password used to connect to LDAP Directory service to perform required \texttt{query}
4813 \item [query] - a query performed on LDAP Directory serice to find user for authentication.
4814 The \texttt{query} string is composed as \texttt{<basedn>/<filter>}. Where `\texttt{<basedn>} is a DN search starting
4815 point and \texttt{<filter>} is a standard LDAP search object filter which support dynamic string
4816 substitution: \texttt{\%u} will be replaced by credential's username and \texttt{\%p} by credential's
4817 password, i.e. \texttt{query=dc=bacula,dc=com/(cn=\%u)}.
4818 \item [starttls] - instruct BPAM LDAP Plugin to use \texttt{StartTLS} extension if LDAP Directory service
4819 will support it and follback to no TLS if this extension is not available.
4820 \item [starttlsforce] - does the same what `starttls` but resport error on fallback.
4821 \end{itemize}
4822
4823 The working configuration examples:
4824
4825 \smallskip
4826 bacula-dir.conf - Console resource configuration for BPAM LDAP Plugin with OpenLDAP authentication example.
4827
4828 \begin{bVerbatim}
4829 Console {
4830 Name = "bacula_ldap_console"
4831 Password = "xxx"
4832
4833 # New directive (on a single line)
4834 Authentication Plugin = "ldap:url=ldap://ldapsrv/
4835 binddn=cn=root,dc=bacula,dc=com bindpass=secret
4836 query=dc=bacula,dc=com/(cn=%u) starttls"
4837 ...
4838 }
4839 \end{bVerbatim}
4840
4841
4842 bacula-dir.conf - Console resource configuration for BPAM LDAP Plugin with Active Directory authentication example.
4843
4844 {\small
4845 \begin{bVerbatim}
4846 Console {
4847 Name = "bacula_ad_console"
4848 Password = "xxx"
4849
4850 # New directive (on a single line)
4851 Authentication Plugin = "ldap:url=ldaps://ldapsrv/
4852 binddn=cn=bacula,ou=Users,dc=bacula,dc=com bindpass=secret
4853 query=dc=bacula,dc=com/(&(objectCategory=person)(objectClass=user)(sAMAccountName=%u))"
4854 ...
4855 }
4856 \end{bVerbatim}
4857 }
4858
4859 \label{blb:SampleDirectorConfiguration}
4860 \section{Example Director Configuration File}
4861 \index[general]{File!Example Director Configuration}
4862 \index[general]{Example Director Configuration File}
4863
4864 An example Director configuration file might be the following:
4865
4866 \begin{bVerbatim}
4867 #
4868 # Default Bacula Director Configuration file
4869 #
4870 # The only thing that MUST be changed is to add one or more
4871 # file or directory names in the Include directive of the
4872 # FileSet resource.
4873 #
4874 # For Bacula release 1.15 (5 March 2002) -- redhat
4875 #
4876 # You might also want to change the default email address
4877 # from root to your address. See the "mail" and "operator"
4878 # directives in the Messages resource.
4879 #
4880 Director { # define myself
4881 Name = rufus-dir
4882 QueryFile = "/home/kern/bacula/bin/query.sql"
4883 WorkingDirectory = "/home/kern/bacula/bin/working"
4884 PidDirectory = "/home/kern/bacula/bin/working"
4885 Password = "XkSfzu/Cf/wX4L8Zh4G4/yhCbpLcz3YVdmVoQvU3EyF/"
4886 }
4887 # Define the backup Job
4888 Job {
4889 Name = "NightlySave"
4890 Type = Backup
4891 Level = Incremental # default
4892 Client=rufus-fd
4893 FileSet="Full Set"
4894 Schedule = "WeeklyCycle"
4895 Storage = DLTDrive
4896 Messages = Standard
4897 Pool = Default
4898 }
4899 Job {
4900 Name = "Restore"
4901 Type = Restore
4902 Client=rufus-fd
4903 FileSet="Full Set"
4904 Where = /tmp/bacula-restores
4905 Storage = DLTDrive
4906 Messages = Standard
4907 Pool = Default
4908 }
4909
4910 # List of files to be backed up
4911 FileSet {
4912 Name = "Full Set"
4913 Include {
4914 Options { signature=SHA1}
4915 #
4916 # Put your list of files here, one per line or include an
4917 # external list with:
4918 #
4919 # @file-name
4920 #
4921 # Note: / backs up everything
4922 File = /
4923 }
4924 Exclude {}
4925 }
4926 # When to do the backups
4927 Schedule {
4928 Name = "WeeklyCycle"
4929 Run = level=Full sun at 2:05
4930 Run = level=Incremental mon-sat at 2:05
4931 }
4932 # Client (File Services) to backup
4933 Client {
4934 Name = rufus-fd
4935 Address = rufus
4936 Catalog = MyCatalog
4937 Password = "MQk6lVinz4GG2hdIZk1dsKE/LxMZGo6znMHiD7t7vzF+"
4938 File Retention = 60d # sixty day file retention
4939 Job Retention = 1y # 1 year Job retention
4940 AutoPrune = yes # Auto apply retention periods
4941 }
4942 # Definition of DLT tape storage device
4943 Storage {
4944 Name = DLTDrive
4945 Address = rufus
4946 Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
4947 Device = "HP DLT 80" # same as Device in Storage daemon
4948 Media Type = DLT8000 # same as MediaType in Storage daemon
4949 }
4950 # Definition for a DLT autochanger device
4951 Storage {
4952 Name = Autochanger
4953 Address = rufus
4954 Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
4955 Device = "Autochanger" # same as Device in Storage daemon
4956 Media Type = DLT-8000 # Different from DLTDrive
4957 Autochanger = yes
4958 }
4959 # Definition of DDS tape storage device
4960 Storage {
4961 Name = SDT-10000
4962 Address = rufus
4963 Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
4964 Device = SDT-10000 # same as Device in Storage daemon
4965 Media Type = DDS-4 # same as MediaType in Storage daemon
4966 }
4967 # Definition of 8mm tape storage device
4968 Storage {
4969 Name = "8mmDrive"
4970 Address = rufus
4971 Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
4972 Device = "Exabyte 8mm"
4973 MediaType = "8mm"
4974 }
4975 # Definition of file storage device
4976 Storage {
4977 Name = File
4978 Address = rufus
4979 Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
4980 Device = FileStorage
4981 Media Type = File
4982 }
4983 # Generic catalog service
4984 Catalog {
4985 Name = MyCatalog
4986 dbname = bacula; user = bacula; password = ""
4987 }
4988 # Reasonable message delivery -- send most everything to
4989 # the email address and to the console
4990 Messages {
4991 Name = Standard
4992 mail = root@localhost = all, !skipped, !terminate
4993 operator = root@localhost = mount
4994 console = all, !skipped, !saved
4995 }
4996
4997 # Default pool definition
4998 Pool {
4999 Name = Default
5000 Pool Type = Backup
5001 AutoPrune = yes
5002 Recycle = yes
5003 }
5004 #
5005 # Restricted console used by tray-monitor to get the status of the director
5006 #
5007 Console {
5008 Name = Monitor
5009 Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR"
5010 CommandACL = status, .status
5011 }
5012 \end{bVerbatim}