Debian Codegraph @

manuals/en/main/storedconf.tex

raw
1 \chapter{Storage Daemon Configuration}
2 \label{blb:StoredConfChapter}
3 \index[general]{Storage Daemon Configuration}
4 \index[general]{Configuration!Storage Daemon}
5
6 The Storage Daemon configuration file has relatively few resource definitions.
7 However, due to the great variation in backup media and system capabilities,
8 the storage daemon must be highly configurable. As a consequence, there are
9 quite a large number of directives in the Device Resource definition that
10 allow you to define all the characteristics of your Storage device (normally a
11 tape drive). Fortunately, with modern storage devices, the defaults are
12 sufficient, and very few directives are actually needed.
13
14 Examples of \textbf{Device} resource directives that are known to work for a
15 number of common tape drives can be found in the \bdirectoryname{\bbracket{bacula-src}/examples/devices}
16 directory, and most will also be listed here.
17
18 For a general discussion of configuration file and resources including the
19 data types recognized by \textbf{\bacula{}}, please see the
20 \bilink{Configuration}{blb:ConfigureChapter} chapter of this manual. The
21 following Storage Resource definitions must be defined:
22
23 \begin{bitemize}
24 \item
25 \bilink{Storage}{blb:StorageResource2} -- to define the name of the
26 Storage daemon.
27 \item
28 \bilink{Director}{blb:DirectorResource1} -- to define the Director's
29 name and his access password.
30 \item
31 \bilink{Device}{blb:DeviceResource} -- to define the
32 characteristics of your storage device (tape drive).
33 \item
34 \bilink{Messages}{blb:MessagesChapter} -- to define where error and
35 information messages are to be sent.
36 \end{bitemize}
37
38 \section{Storage Resource}
39 \label{blb:StorageResource2}
40 \index[general]{Resource!Storage}
41 \index[general]{Storage Resource}
42
43 In general, the properties specified under the Storage resource define global
44 properties of the Storage daemon. Each Storage daemon configuration file must
45 have one and only one Storage resource definition.
46
47 \begin{bdescription}
48
49 \bwebdoc{Storage:Storage:Name}
50 \item [Name = \bbracket{Storage-Daemon-Name}]
51 \index[sd]{Name}
52 \index[sd]{Directive!Name}
53 Specifies the Name of the Storage daemon. This directive is required.
54
55 \bwebdoc{Storage:Storage:WorkingDirectory}
56 \item [Working Directory = \bbracket{Directory}]
57 \index[sd]{Working Directory}
58 \index[sd]{Directive!Working Directory}
59 This directive is mandatory and specifies a directory in which the Storage
60 daemon may put its status files. This directory should be used only by \textbf{\bacula{}},
61 but may be shared by other \bacula{} daemons provided the names
62 given to each daemon are unique. This directive is
63 required
64
65 \bwebdoc{Storage:Storage:PidDirectory}
66 \item [Pid Directory = \bbracket{Directory}]
67 \index[sd]{Pid Directory}
68 \index[sd]{Directive!Pid Directory}
69 This directive is mandatory and specifies a directory in which the Storage
70 daemon may put its process Id file files. The process Id file is used to
71 shutdown \bacula{} and to prevent multiple copies of \bacula{} from running
72 simultaneously. This directive is required. Standard shell expansion of the
73 \textbf{Directory} is done when the configuration file is read so that values
74 such as \textbf{\$HOME} will be properly expanded.
75
76 Typically on Linux systems, you will set this to: \bdirectoryname{/var/run}. If you are
77 not installing \bacula{} in the system directories, you can use the \textbf{Working Directory}
78 as defined above.
79
80 \bwebdoc{Storage:Storage:DedupDirectory}
81 \item [Dedup Directory = \bbracket{Directory}]
82 \index[sd]{Dedup Directory}
83 \index[sd]{Directive!Dedup Directory}
84
85 This directive is mandatory when using Global Endpoint Deduplication
86 feature, and specifies a directory in which the Storage daemon may put data
87 block files for all devices of the type \textbf{dedup}. The \textbf{Dedup Directory}
88 can be very large after some point, we advise you to use a
89 logical volume manager to be able to extend the filesystem when needed with
90 new disks.
91
92 Standard shell expansion of the \textbf{Directory} is done when the
93 configuration file is read so that values such as \textbf{\$HOME} will be
94 properly expanded.
95
96 \bwebdoc{Storage:Storage:DedupIndexDirectory}
97 \item [Dedup Index Directory = \bbracket{Directory}]
98 \index[sd]{Dedup Index Directory}
99 \index[sd]{Directive!Dedup Index Directory}
100 This directive is optional and specifies a directory in which the Storage
101 daemon may put its index files for all devices of the type \textbf{dedup}.
102
103 Standard shell expansion of the \textbf{Directory} is done when the
104 configuration file is read so that values such as \textbf{\$HOME} will be
105 properly expanded. The default value is set to \bdefaultvalue{DedupDirectory} when
106 set.
107
108 \bwebdoc{Storage:Storage:HeartbeatInterval}
109 \item [Heartbeat Interval = \bbracket{time-interval}]
110 \index[sd]{Heartbeat Interval}
111 \index[sd]{Directive!Heartbeat Interval}
112 \index[general]{Heartbeat Interval}
113 \index[general]{Broken pipe}
114 This directive defines an interval of time in seconds. When
115 the Storage daemon is waiting for the operator to mount a
116 tape, each time interval, it will send a heartbeat signal to
117 the File daemon. The default interval is \bdefaultvalue{300s}.
118 This feature is particularly useful if you
119 have a router such as 3Com that does not follow Internet
120 standards and times out an valid connection after a short
121 duration despite the fact that keepalive is set. This usually
122 results in a broken pipe error message.
123
124 \bwebdoc{Storage:Storage:ClientConnectWait}
125 \item [Client Connect Wait = \bbracket{time-interval}]
126 \index[sd]{Connect Wait}
127 \index[sd]{Directive!Connect Wait}
128 \index[general]{Client Connect Wait}
129 This directive defines an interval of time in seconds that
130 the Storage daemon will wait for a Client (the File daemon)
131 to connect. The default is \bdefaultvalue{30 minutes}. Be aware that the
132 longer the Storage daemon waits for a Client, the more
133 resources will be tied up.
134
135 \bwebdoc{Storage:Storage:MaximumConcurrentJobs}
136 \item [Maximum Concurrent Jobs = \bbracket{number}]
137 \index[sd]{Maximum Concurrent Jobs}
138 \index[sd]{Directive!Maximum Concurrent Jobs}
139 where \bbracket{number} is the maximum number of Jobs that may run
140 concurrently. The default is set to \bdefaultvalue{20}, but you may set it to a larger
141 number. Each contact from the Director (e.g. status request, job start
142 request) is considered as a Job, so if you want to be able to do a \bcommandname{status}
143 request in the console at the same time as a Job is running, you
144 will need to set this value greater than 1. To run simultaneous Jobs,
145 you will need to set a number of other directives in the Director's
146 configuration file. Which ones you set depend on what you want, but you
147 will almost certainly need to set the \textbf{Maximum Concurrent Jobs} in
148 the Storage resource in the Director's configuration file and possibly
149 those in the Job and Client resources.
150
151 \bwebdoc{Storage:Storage:SDAddresses}
152 \item [SDAddresses = \bbracket{IP-address-specification}]
153 \index[sd]{SDAddresses}
154 \index[sd]{Directive!SDAddresses}
155 Specify the ports and addresses on which the Storage daemon will listen
156 for Director connections. Normally, the default is sufficient and you
157 do not need to specify this directive. Probably the simplest way to
158 explain how this directive works is to show an example:
159
160 \begin{bVerbatim}
161 SDAddresses = { ip = {
162 addr = 1.2.3.4; port = 1205; }
163 ipv4 = {
164 addr = 1.2.3.4; port = http; }
165 ipv6 = {
166 addr = 1.2.3.4;
167 port = 1205;
168 }
169 ip = {
170 addr = 1.2.3.4
171 port = 1205
172 }
173 ip = {
174 addr = 1.2.3.4
175 }
176 ip = {
177 addr = 201:220:222::2
178 }
179 ip = {
180 addr = bluedot.thun.net
181 }
182 }
183 \end{bVerbatim}
184
185 where ip, ip4, ip6, addr, and port are all keywords. Note, that the address
186 can be specified as either a dotted quadruple, or IPv6 colon notation, or as
187 a symbolic name (only in the ip specification). Also, port can be specified
188 as a number or as the mnemonic value from the \bfilename{/etc/services} file.
189 If a port is not specified, the default will be used. If an ip section is specified,
190 the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then
191 only IPv4 resolutions will be permitted, and likewise with ip6.
192
193 Using this directive, you can replace both the SDPort and SDAddress
194 directives shown below.
195
196 \bwebdoc{Storage:Storage:SdPort}
197 \item [SDPort = \bbracket{port-number}]
198 \index[sd]{SDPort}
199 \index[sd]{Directive!SDPort}
200 Specifies port number on which the Storage daemon listens for Director
201 connections. The default is \bdefaultvalue{9103}.
202
203 \bwebdoc{Storage:Storage:SdAddress}
204 \item [SDAddress = \bbracket{IP-Address}]
205 \index[sd]{SDAddress}
206 \index[sd]{Directive!SDAddress}
207 This directive is optional, and if it is specified, it will cause the
208 Storage daemon server (for Director and File daemon connections) to bind
209 to the specified \textbf{IP-Address}, which is either a domain name or an
210 IP address specified as a dotted quadruple. If this directive is not
211 specified, the Storage daemon will bind to any available address (the
212 default).
213
214 \bwebdoc{Storage:Storage:CommCompression}
215 \item[CommCompression = \byesorno{}]
216 \index[sd]{CommCompression}
217 \index[sd]{Directive!CommCompression}
218 \index[sd]{Compression}
219
220 If the two \bacula{} components (DIR, FD, SD, bconsole) have the comm line
221 compression enabled, the line compression will be enabled. The default value
222 is yes.
223
224 In many cases, the volume of data transmitted across the communications line
225 can be reduced by a factor of three when this directive is
226 \bdefaultvalue{enabled}. In the case that the compression is not effective,
227 \bacula{} turns it off on a record by record basis. \smallskip
228
229 If you are backing up data that is already compressed the comm line compression
230 will not be effective, and you are likely to end up with an average compression
231 ratio that is very small. In this case, \bacula{} reports \bvalue{None} in the
232 Job report.
233
234 \input{StorageStorageTls}
235 \bwebdoc{Storage:Storage:End}
236 \end{bdescription}
237
238 The following is a typical Storage daemon Storage definition.
239
240 \begin{bVerbatim}
241 #
242 # "Global" Storage daemon configuration specifications appear
243 # under the Storage resource.
244 #
245 Storage {
246 Name = "Storage daemon"
247 Address = localhost
248 WorkingDirectory = "~/bacula/working"
249 Pid Directory = "~/bacula/working"
250 }
251 \end{bVerbatim}
252
253 \section{Director Resource}
254 \label{blb:DirectorResource1}
255 \index[general]{Director Resource}
256 \index[general]{Resource!Director}
257
258 The Director resource specifies the Name of the Director which is permitted
259 to use the services of the Storage daemon. There may be multiple Director
260 resources. The Director Name and Password must match the corresponding
261 values in the Director's configuration file.
262
263 \begin{bdescription}
264
265 \bwebdoc{Storage:Director:Name}
266 \item [Name = \bbracket{Director-Name}]
267 \index[sd]{Name}
268 \index[sd]{Directive!Name}
269 Specifies the Name of the Director allowed to connect to the Storage daemon.
270 This directive is required.
271
272 \bwebdoc{Storage:Director:Password}
273 \item [Password = \bbracket{Director-password}]
274 \index[sd]{Password}
275 \index[sd]{Directive!Password}
276 Specifies the password that must be supplied by the above named Director.
277 This directive is required.
278
279 \bwebdoc{Storage:Director:Monitor}
280 \item [Monitor = \byesorno{}]
281 \index[sd]{Monitor}
282 \index[sd]{Directive!Monitor}
283 If Monitor is set to \bdefaultvalue{no} (default), this director will have full
284 access to this Storage daemon. If Monitor is set to \bvalue{yes}, this
285 director will only be able to fetch the current status of this Storage
286 daemon.
287
288 Please note that if this director is being used by a Monitor, we highly
289 recommend to set this directive to \bvalue{yes} to avoid serious security
290 problems.
291
292 \input{StorageDirectorTls}
293 \bwebdoc{Storage:Director:End1}
294 \end{bdescription}
295
296 The following is an example of a valid Director resource definition:
297
298 \begin{bVerbatim}
299 Director {
300 Name = MainDirector
301 Password = my_secret_password
302 }
303 \end{bVerbatim}
304
305 \label{blb:DeviceResource}
306 \section{Device Resource}
307 \index[general]{Resource!Device}
308 \index[general]{Device Resource}
309
310 The Device Resource specifies the details of each device (normally a tape
311 drive) that can be used by the Storage daemon. There may be multiple
312 Device resources for a single Storage daemon. In general, the properties
313 specified within the Device resource are specific to the Device.
314
315 \begin{bdescription}
316
317 \bwebdoc{Storage:Device:Name}
318 \item [Name = \bbracket{Device-Name}]
319 \index[sd]{Name}
320 \index[sd]{Directive!Name}
321 Specifies the Name that the Director will use when asking to backup or
322 restore to or from to this device. This is the logical Device name, and may
323 be any string up to 127 characters in length. It is generally a good idea to
324 make it correspond to the English name of the backup device. The physical
325 name of the device is specified on the \textbf{Archive Device} directive
326 described below. The name you specify here is also used in your Director's
327 conf file on the
328 \bilink{Device directive}{blb:StorageResource2} in its Storage
329 resource.
330
331 \bwebdoc{Storage:Device:ArchiveDevice}
332 \item [Archive Device = \bbracket{name-string}]
333 \index[sd]{Archive Device}
334 \index[sd]{Directive!Archive Device}
335 The specified \textbf{name-string} gives the system file name of the storage
336 device managed by this storage daemon. This will usually be the device file
337 name of a removable storage device (tape drive), for example
338 \bfilename{/dev/nst0} or \bfilename{/dev/rmt/0mbn}. It may also be a directory name
339 if you are archiving to disk storage. In this case, you must supply the
340 full absolute path to the directory. When specifying a tape device, it
341 is preferable that the "non-rewind" variant of the device file name be
342 given. In addition, on systems such as Sun, which have multiple tape
343 access methods, you must be sure to specify to use Berkeley I/O
344 conventions with the device. The \textbf{b} in the Solaris (Sun) archive
345 specification \bfilename{/dev/rmt/0mbn} is what is needed in this case.
346 \bacula{} does not support SysV tape drive behavior.
347
348 As noted above, normally the Archive Device is the name of a tape drive, but
349 you may also specify an absolute path to an existing directory. If the
350 Device is a directory \bacula{} will write to file storage in the specified
351 directory, and the filename used will be the Volume name as specified in the
352 Catalog. If you want to write into more than one directory (i.e. to spread
353 the load to different disk drives), you will need to define two Device
354 resources, each containing an Archive Device with a different directory.
355 \label{blb:SetupFifo}
356 In addition to a tape device name or a directory name, \bacula{} will accept the
357 name of a FIFO. A FIFO is a special kind of file that connects two programs
358 via kernel memory. If a FIFO device is specified for a backup operation, you
359 must have a program that reads what \bacula{} writes into the FIFO. When the
360 Storage daemon starts the job, it will wait for \textbf{MaximumOpenWait} seconds
361 for the read program to start reading, and then time it out and terminate
362 the job. As a consequence, it is best to start the read program at the
363 beginning of the job perhaps with the \textbf{RunBeforeJob} directive. For this
364 kind of device, you never want to specify \textbf{AlwaysOpen}, because you want
365 the Storage daemon to open it only when a job starts, so you must explicitly
366 set it to \bvalue{no}. Since a FIFO is a one way device, \bacula{} will not attempt
367 to read a label of a FIFO device, but will simply write on it. To create a
368 FIFO Volume in the catalog, use the \bcommandname{add} command rather than the
369 \bcommandname{label} command to avoid attempting to write a label.
370
371 \begin{bVerbatim}
372 Device {
373 Name = FifoStorage
374 Media Type = Fifo
375 Device Type = Fifo
376 Archive Device = /tmp/fifo
377 LabelMedia = yes
378 Random Access = no
379 AutomaticMount = no
380 RemovableMedia = no
381 MaximumOpenWait = 60
382 AlwaysOpen = no
383 }
384 \end{bVerbatim}
385
386 During a restore operation, if the Archive Device is a FIFO, \bacula{} will
387 attempt to read from the FIFO, so you must have an external program that
388 writes into the FIFO. \bacula{} will wait \textbf{MaximumOpenWait} seconds for the
389 program to begin writing and will then time it out and terminate the job. As
390 noted above, you may use the \textbf{RunBeforeJob} to start the writer program
391 at the beginning of the job.
392
393 The Archive Device directive is required.
394
395 \bwebdoc{Storage:Device:DeviceType}
396 \item [Device Type = \bbracket{type-specification}]
397 \index[sd]{Device Type}
398 \index[sd]{Directive!Device Type}
399 The Device Type specification allows you to explicitly tell \bacula{}
400 what kind of device you are defining. It the \emph{type-specification}
401 may be one of the following:
402 \begin{bdescription}
403 \item [File]
404 Tells \bacula{} that the device is a file. It may either be a
405 file defined on fixed medium or a removable filesystem such as
406 USB. All files must be random access devices.
407 \item [Tape]
408 The device is a tape device and thus is sequential access. Tape devices
409 are controlled using ioctl() calls.
410 \item [Fifo]
411 The device is a first-in-first out sequential access read-only
412 or write-only device.
413 \item [Aligned]
414 Tells \bacula{} that the device is special Aligned Device. Please see
415 the specific Aligned User's guide for more information.
416 \item [Dedup]
417 The device is a Deduplication device. The Storage Daemon will
418 use the deduplication engine. Please see the specific Deduplication User's
419 guide for more information.
420 \item [Cloud]
421 The device is a Cloud device. The Storage Daemon will
422 use the Cloud to upload/download volumes. Please see the specific Cloud User's
423 guide for more information.
424 \end{bdescription}
425
426 The Device Type directive is not required, and if not specified, \bacula{}
427 will attempt to guess what kind of device has been specified using the
428 Archive Device specification supplied. There are several advantages to
429 explicitly specifying the Device Type. First, on some systems, block and
430 character devices have the same type.
431 Secondly, if you explicitly specify the Device Type, the mount point
432 need not be defined until the device is opened. This is the case with
433 most removable devices such as USB that are mounted by the HAL daemon.
434 If the Device Type is not explicitly specified, then the mount point
435 must exist when the Storage daemon starts.
436
437 \bwebdoc{Storage:Device:Enabled}
438 \item [Enabled = \byesorno{}]
439 \index[sd]{Enabled}
440 \index[sd]{Directive!Enabled}
441 This directive allows you to enable or disable the \bresourcename{Device} resource.
442
443 \bwebdoc{Storage:Device:MediaType}
444 \item [Media Type = \bbracket{name-string}]
445 \index[sd]{Media Type}
446 \index[sd]{Directive!Media Type}
447 The specified \textbf{name-string} names the type of media supported by this
448 device, for example, "DLT7000". Media type names are arbitrary in that you
449 set them to anything you want, but they must be known to the volume
450 database to keep track of which storage daemons can read which volumes. In
451 general, each different storage type should have a unique Media Type
452 associated with it. The same \textbf{name-string} must appear in the
453 appropriate Storage resource definition in the Director's configuration
454 file.
455
456 Even though the names you assign are arbitrary (i.e. you choose the name
457 you want), you should take care in specifying them because the Media Type
458 is used to determine which storage device \bacula{} will select during
459 restore. Thus you should probably use the same Media Type specification
460 for all drives where the Media can be freely interchanged. This is not
461 generally an issue if you have a single Storage daemon, but it is with
462 multiple Storage daemons, especially if they have incompatible media.
463
464 For example, if you specify a Media Type of "DDS-4" then during the
465 restore, \bacula{} will be able to choose any Storage Daemon that handles
466 "DDS-4". If you have an autochanger, you might want to name the Media Type
467 in a way that is unique to the autochanger, unless you wish to possibly use
468 the Volumes in other drives. You should also ensure to have unique Media
469 Type names if the Media is not compatible between drives. This
470 specification is required for all devices.
471
472 In addition, if you are using disk storage, each Device resource will
473 generally have a different mount point or directory. In order for
474 \bacula{} to select the correct Device resource, each one must have a
475 unique Media Type.
476
477
478 \bwebdoc{Storage:Device:Autochanger}
479 \label{blb:Autochanger}
480 \item [Autochanger = \byesorno{}]
481 \index[sd]{Autochanger}
482 \index[sd]{Directive!Autochanger}
483 If \bvalue{yes}, this device belongs to an automatic tape changer, and you
484 must specify an \textbf{Autochanger} resource that points to the \textbf{Device}
485 resources. You must also specify a
486 \textbf{Changer Device}. If the Autochanger directive is set to \bdefaultvalue{no}
487 (default), the volume must be manually changed. You should also
488 have an identical directive to the
489 \bilink{Storage resource}{blb:Autochanger1} in the Director's
490 configuration file so that when labeling tapes you are prompted for the slot.
491
492 \bwebdoc{Storage:Device:ChangerDevice}
493 \item [Changer Device = \bbracket{name-string}]
494 \index[sd]{Changer Device}
495 \index[sd]{Directive!Changer Device}
496 The specified \textbf{name-string} must be the \textbf{generic SCSI} device
497 name of the autochanger that corresponds to the normal read/write
498 \textbf{Archive Device} specified in the Device resource. This
499 generic SCSI device name should be specified if you have an autochanger
500 or if you have a standard tape drive and want to use the
501 \textbf{Alert Command} (see below). For example, on Linux systems, for
502 an Archive Device name of \bfilename{/dev/nst0}, you would specify
503 \bfilename{/dev/sg0} for the Changer Device name. Depending on your exact
504 configuration, and the number of autochangers or the type of
505 autochanger, what you specify here can vary. This directive is
506 optional. See the \bilink{ Using Autochangers}{blb:AutochangersChapter} chapter
507 of this manual for more details of using this and the following
508 autochanger directives.
509
510 \bwebdoc{Storage:Device:ChangerCommand}
511 \item [Changer Command = \bbracket{name-string}]
512 \index[sd]{Changer Command}
513 \index[sd]{Directive!Changer Command}
514 The \textbf{name-string} specifies an external program to be called that will
515 automatically change volumes as required by \textbf{\bacula{}}. Normally,
516 this directive will be specified only in the \textbf{AutoChanger} resource,
517 which is then used for all devices. However, you may also specify
518 the different \textbf{Changer Command} in each Device resource.
519 Most frequently,
520 you will specify the \bacula{} supplied \mtxchanger{} script as follows:
521
522 \begin{bVerbatim}
523 Changer Command = "/path/mtx-changer %c %o %S %a %d"
524 \end{bVerbatim}
525
526 and you will install the \btool{mtx} on your system (found in the \textbf{depkgs}
527 release). An example of this command is in the default \bfilename{bacula-sd.conf} file.
528 For more details on the substitution characters that may be specified to
529 configure your autochanger please see the
530 \bilink{Autochangers}{blb:AutochangersChapter} chapter of this manual.
531 For FreeBSD users, you might want to see one of the several \btool{chio}
532 scripts in \bdirectoryname{examples/autochangers}.
533
534 \bwebdoc{Storage:Device:ControlDevice}
535 \item [Control Device = \bbracket{name-string}]
536 \index[sd]{Control Device}
537 The control device is the \acs{SCSI} control device that corresponds to the
538 \bdirectivename{Archive Device}. The correspondance can be done via the \btool{lssci -g}
539 command.
540 \begin{bVerbatim}
541 /opt/bacula# lsscsi -g
542 [1:0:0:0] tape HP Ultrium 4-SCSI H61W /dev/st0 /dev/sg0
543 [1:0:0:1] tape HP Ultrium 4-SCSI H61W /dev/st1 /dev/sg1
544 [1:0:0:2] mediumx HP MSL G3 Series E.00 - /dev/sg2
545 \end{bVerbatim}
546
547 \bwebdoc{Storage:Device:AlertCommand}
548 \item [Alert Command = \bbracket{name-string}]
549 \index[sd]{Alert Command}
550 The \textbf{name-string} specifies an external program to be called at the
551 completion of each Job after the device is released. The purpose of this
552 command is to check for Tape Alerts, which are present when something is
553 wrong with your tape drive (at least for most modern tape drives). The same
554 substitution characters that may be specified in the Changer Command may
555 also be used in this string. For more information, please see the
556 \bilink{Autochangers}{blb:AutochangersChapter} chapter of this manual.
557
558 The directive in the Device resource can call the \btool{tapealert} script
559 that is installed in the scripts directory. It is defined as follows:
560 \begin{bVerbatim}
561 Device {
562 Name = ...
563 Archive Device = /dev/nst0
564 Alert Command = "/opt/bacula/scripts/tapealert %l"
565 Control Device = /dev/sg1 # must be SCSI ctl for /dev/nst0
566 ...
567 }
568 \end{bVerbatim}
569
570 Once the above mentioned two directives (\bdirectivename{Alert Command} and \bdirectivename{Control Device})
571 are in place in each of your \bresourcename{Device} resources, \bacula{} will check for tape
572 alerts at two points:
573 \begin{bitemize}
574 \item After the Drive is used and it becomes idle.
575 \item After each read or write error on the drive.
576 \end{bitemize}
577
578 At each of the above times, \bacula{} will call the new \btool{tapealert}
579 script, which uses the \btool{tapeinfo} program. The \btool{tapeinfo} utility is
580 part of the \btool{apt} \texttt{sg3-utils} and \btool{rpm} \texttt{sg3\_utils} packages.
581 Then for each tape alert that \bacula{} finds for that drive, it will emit
582 a Job message that is either \texttt{INFO}, \texttt{WARNING}, or \texttt{FATAL}
583 depending on the designation in the
584 \bfootref{http://www.t10.org}{Tape Alert published by the T10 Technical Committee on SCSI Storage Interfaces}.
585 For the specification, please see: \url{http://www.t10.org/ftp/t10/document.02/02-142r0.pdf}
586 \bwebdoc{Storage:Device:WormCommand}
587 \item [Worm Command = \bbracket{name-string}]
588 \index[sd]{Worm Command}
589
590 The \bvalue{name-string} specifies an external program to be called when
591 loading a new volume. The purpose of this command is to check if the
592 current tape is a \acs{WORM}\footnote{\acl{WORM}} tape. The same
593 substitution characters that may be specified in the \bdirectivename{Changer Command} ay
594 also be used in this string.
595
596 The directive in the \bresourcename{Device} resource can call the \btool{isworm} script
597 that is installed in the scripts directory. It is defined as follows:
598
599 \begin{bVerbatim}
600 Device {
601 Name = ...
602 Archive Device = /dev/nst0
603 Worm Command = "/opt/bacula/scripts/isworm %l"
604 Control Device = /dev/sg1 # must be SCSI ctl for /dev/nst0
605 ...
606 }
607 \end{bVerbatim}
608
609 \bacula{} will call the \btool{isworm} script, which uses the
610 \btool{tapeinfo} and \btool{sdparm} program.
611
612
613 \bwebdoc{Storage:Device:DriveIndex}
614 \item [Drive Index = \bbracket{number}]
615 \index[sd]{Drive Index}
616 \index[sd]{Directive!Drive Index}
617 The \textbf{Drive Index} that you specify is passed to the \mtxchanger{}
618 script and is thus passed to the \mtx{} program. By
619 default, the Drive Index is \bdefaultvalue{zero}, so if you have only one drive in your
620 autochanger, everything will work normally. However, if you have
621 multiple drives, you must specify multiple \bacula{} Device resources (one
622 for each drive). The first Device should have the Drive Index set to 0,
623 and the second Device Resource should contain a Drive Index set to 1,
624 and so on. This will then permit you to use two or more drives in your
625 autochanger. As of \bacula{} version 1.38.0, using the \textbf{Autochanger}
626 resource, \bacula{} will automatically ensure that only one drive at a time
627 uses the autochanger script, so you no longer need locking scripts as in
628 the past -- the default \mtxchanger{} script works for any number of
629 drives.
630
631 \bwebdoc{Storage:Device:Autoselect}
632 \item [Autoselect = \byesorno{}]
633 \index[sd]{Autoselect}
634 \index[sd]{Directive!Autoselect}
635 If this directive is set to \bdefaultvalue{yes} (default), and the Device
636 belongs to an autochanger, then when the Autochanger is referenced
637 by the Director, this device can automatically be selected. If this
638 directive is set to \bvalue{no}, then the Device can only be referenced
639 by directly using the Device name in the Director. This is useful
640 for reserving a drive for something special such as a high priority
641 backup or restore operations.
642
643 \bwebdoc{Storage:Device:MaximumConcurrentJobs}
644 \item[Maximum Concurrent Jobs = \bbracket{num}]
645 \index[sd]{MaximumConcurrentJobs}
646 \index[sd]{Directive!MaximumConcurrentJobs}
647
648 \bdirectivename{Maximum Concurrent Jobs} is a directive that permits setting the maximum
649 number of Jobs that can run concurrently on a specified Device. Using this
650 directive, it is possible to have different Jobs using multiple drives, because
651 when the Maximum Concurrent Jobs limit is reached, the Storage Daemon will
652 start new Jobs on any other available compatible drive. This facilitates
653 writing to multiple drives with multiple Jobs that all use the same Pool.
654
655 \bwebdoc{Storage:Device:MaximumChangerWait}
656 \item [Maximum Changer Wait = \bbracket{time}]
657 \index[sd]{Maximum Changer Wait}
658 \index[sd]{Directive!Maximum Changer Wait}
659 This directive specifies the maximum time in seconds for \bacula{} to wait
660 for an autochanger to change the volume. If this time is exceeded,
661 \bacula{} will invalidate the Volume slot number stored in the catalog and
662 try again. If no additional changer volumes exist, \bacula{} will ask the
663 operator to intervene. The default is \bdefaultvalue{5 minutes}.
664 % TODO: if this is the format, then maybe "5 minutes" should be in
665 % TODO: quotes? define style. see others.
666
667 \bwebdoc{Storage:Device:MaximumRewindWait}
668 \item [Maximum Rewind Wait = \bbracket{time}]
669 \index[sd]{Maximum Rewind Wait}
670 \index[sd]{Directive!Maximum Rewind Wait}
671 This directive specifies the maximum time in seconds for \bacula{} to wait
672 for a rewind before timing out. If this time is exceeded,
673 \bacula{} will cancel the job. The default is \bdefaultvalue{5 minutes}.
674
675 \bwebdoc{Storage:Device:MaximumOpenWait}
676 \item [Maximum Open Wait = \bbracket{time}]
677 \index[sd]{Maximum Open Wait}
678 \index[sd]{Directive!Maximum Open Wait}
679 This directive specifies the maximum time in seconds that
680 \bacula{} will wait for a device that is busy. The default is \bdefaultvalue{5 minutes}.
681 If the device cannot be obtained, the current Job will be terminated in
682 error. \bacula{} will re-attempt to open the drive the next time a Job
683 starts that needs the the drive.
684
685 \bwebdoc{Storage:Device:AlwaysOpen}
686 \item [Always Open = \byesorno{}]
687 \index[sd]{Always Open}
688 \index[sd]{Directive!Always Open}
689 If \bdefaultvalue{yes} (default), \bacula{} will always keep the device open unless
690 specifically \textbf{unmounted} by the Console program. This permits
691 \bacula{} to ensure that the tape drive is always available, and properly
692 positioned. If you set
693 \textbf{AlwaysOpen} to \bvalue{no}, \textbf{\bacula{}} will only open the
694 drive when necessary, and at the end of the Job if no other Jobs are
695 using the drive, it will be freed. The next time \bacula{} wants to append
696 to a tape on a drive that was freed, \bacula{} will rewind the tape and
697 position it to the end. To avoid unnecessary tape positioning and to
698 minimize unnecessary operator intervention, it is highly recommended
699 that \textbf{Always Open = yes}. This also ensures that the drive is
700 available when \bacula{} needs it.
701
702 If you have \textbf{Always Open = yes} (recommended) and you want to use the
703 drive for something else, simply use the \bcommandname{unmount} command in the
704 Console program to release the drive. However, don't forget to remount the
705 drive with \bcommandname{mount} when the drive is available or the next \bacula{} job
706 will block.
707
708 For File storage, this directive is ignored. For a FIFO storage device, you
709 must set this to \bvalue{no}.
710
711 Please note that if you set this directive to \bvalue{no} \bacula{} will release
712 the tape drive between each job, and thus the next job will rewind the tape
713 and position it to the end of the data. This can be a very time consuming
714 operation. In addition, with this directive set to no, certain multiple
715 drive autochanger operations will fail. We strongly recommend to keep
716 \textbf{Always Open} set to \bvalue{yes}
717
718 \bwebdoc{Storage:Volume:VolumePollInterval}
719 \item [Volume Poll Interval = \bbracket{time}]
720 \index[sd]{Volume Poll Interval}
721 \index[sd]{Directive!Volume Poll Interval}
722 If the time specified on this directive is non-zero, after asking the
723 operator to mount a new volume \bacula{} will periodically poll (or read) the
724 drive at the specified interval to see if a new volume has been mounted. If
725 the time interval is zero, no polling will occur.
726 The default value is \bdefaultvalue{5 mins}. This directive can be useful
727 if you want to avoid operator intervention via the
728 console. Instead, the operator can simply remove the old volume and insert
729 the requested one, and \bacula{} on the next poll will recognize the new tape
730 and continue. Please be aware that if you set this interval too small, you
731 may excessively wear your tape drive if the old tape remains in the drive,
732 since \bacula{} will read it on each poll. This can be avoided by ejecting the
733 tape using the \textbf{Offline On Unmount} and the \textbf{Close on Poll}
734 directives.
735 However, if you are using a Linux 2.6 kernel or other OSes
736 such as FreeBSD or Solaris, the Offline On Unmount will leave the drive
737 with no tape, and \bacula{} will not be able to properly open the drive and
738 may fail the job. For more information on this problem, please see the
739 \bxlink{description of Offline On Unmount}{blb:NoTapeInDrive}{problems}{subsection}
740 in the \bxlink{Tape Testing}{blb:TapeTestingChapter}{problems}{chapter} of the \bproblemman{}.
741
742 \bwebdoc{Storage:Device:CloseOnPoll}
743 \item [Close on Poll = \byesorno{}]
744 \index[sd]{Close on Poll}
745 \index[sd]{Directive!Close on Poll}
746 If \bvalue{yes}, \bacula{} close the device (equivalent to an unmount except no
747 mount is required) and reopen it at each poll. Normally this is not too
748 useful unless you have the \textbf{Offline on Unmount} directive set, in which
749 case the drive will be taken offline preventing wear on the tape during any
750 future polling. Once the operator inserts a new tape, \bacula{} will recognize
751 the drive on the next poll and automatically continue with the backup.
752 Please see above more more details.
753
754 \bwebdoc{Storage:Device:SyncOnClose}
755 \item [Sync On Close = \byesorno{}]
756 \index[sd]{Sync On Close}
757 \index[sd]{Directive!Sync On Close}
758
759 If \bvalue{yes}, \bacula{} will sync the device at the end of each job and
760 when closing the device. Normally it might be useful if you store the data on
761 network filesystems. The default value is \bvalue{yes}.
762
763 \bwebdoc{Storage:Device:SetVolumeImmutable}
764 \item [Set Volume Immutable = \byesorno{}]
765 \index[sd]{Directive!Set Volume Immutable}
766 Warning:
767 Only for file-based devices.
768
769 This feature can only be used if Bacula is run as a systemd service because only then, with proper capabilities set for
770 the daemon, it's allowed to manage Volume Files' attributes.
771
772 If \bvalue{yes}, this device sets the 'Immutable' file attribute for each volume when setting it's status to 'Full'.
773 Attribute is cleared when the volume is relabeled/truncated.
774
775 When this directive is set and the volume is Full, there is no other way than to wait for
776 the 'MinimumVolumeProtectionTime' to expire so that the volume can be relabeled/reused.
777
778 Note that Immutable flag is set only for Full volumes, setting it for other statuses (e.g. 'Used' volumes)
779 is not currently supported.
780
781 The default is \bdefaultvalue{no}.
782
783 \bwebdoc{Storage:Device:SetVolumeAppendOnly}
784 \item [Set Volume Append Only = \byesorno{}]
785 \index[sd]{Directive!Set Volume Append Only}
786 Warning:
787 Only for file-based devices.
788
789 This feature can only be used if Bacula is run as a systemd service because only then, with proper capabilities set for
790 the daemon, it's allowed to manage Volume Files' attributes.
791
792 If \bvalue{yes}, this device sets the 'Append\_Only' file attribute for each volume that is created
793 (either automatically or using the label command), at the moment of writing first backup job.
794 Attribute is cleared when the volume is relabeled/truncated.
795 Note that the flag is set when Bacula actually uses volume for the first time, not when the volume is labelled (either automatically
796 or using the `label` command).
797
798 The default is \bdefaultvalue{no}.
799
800 \bwebdoc{Storage:Device:MinimumVolumeProtectionTime}
801 \item [Minimum Volume Protection Time = \bbracket{time-interval}]
802 \index[sd]{Directive!Minimum Volume Protection Time}
803 Warning:
804 Only for file-based devices.
805
806 This feature can only be used if Bacula is run as a systemd service because only then, with proper capabilities set for
807 the daemon, it's allowed to manage Volume Files' attributes.
808
809 This directive defines an interval of time in which the Storage Daemon respects the 'Immutable' file attribute which is
810 set when marking volume as Full. Bacula won't allow relabeling or reusing such a volume before this period expires.
811
812 When this directive is set to 0, the drive device will not be able to truncate/relabel volumes at all, effectively
813 keeping volumes all the time for further usage.
814
815 The default is \bdefaultvalue{30 days}.
816
817 \bwebdoc{Storage:Device:MaximumOpenWait}
818 \item [Maximum Open Wait = \bbracket{time}]
819 \index[sd]{Maximum Open Wait}
820 \index[sd]{Directive!Maximum Open Wait}
821 This directive specifies the maximum amount of time in seconds that
822 \bacula{} will wait for a device that is busy. The default is \bdefaultvalue{5 minutes}.
823 If the device cannot be obtained, the current Job will be terminated in
824 error. \bacula{} will re-attempt to open the drive the next time a Job
825 starts that needs the the drive.
826
827
828 \bwebdoc{Storage:Device:RemovableMedia}
829 \label{blb:removablemedia}
830 \item [Removable Media = \byesorno{}]
831 \index[sd]{Removable media}
832 \index[sd]{Directive!Removable media}
833 If \bvalue{yes}, this device supports removable media (for example, tapes
834 or CDs). If \bvalue{no}, media cannot be removed (for example, an
835 intermediate backup area on a hard disk). If \textbf{Removable media} is
836 enabled on a File device (as opposed to a tape) the Storage daemon will
837 assume that device may be something like a USB device that can be
838 removed or a simply a removable harddisk. When attempting to open
839 such a device, if the Volume is not found (for File devices, the Volume
840 name is the same as the Filename), then the Storage daemon will search
841 the entire device looking for likely Volume names, and for each one
842 found, it will ask the Director if the Volume can be used. If so,
843 the Storage daemon will use the first such Volume found. Thus it
844 acts somewhat like a tape drive -- if the correct Volume is not found,
845 it looks at what actually is found, and if it is an appendable Volume,
846 it will use it.
847
848 If the removable medium is not automatically mounted (e.g. udev), then
849 you might consider using additional Storage daemon device directives
850 such as \textbf{Requires Mount}, \textbf{Mount Point}, \textbf{Mount Command},
851 and \textbf{Unmount Command}, all of which can be used in conjunction with
852 \textbf{Removable Media}.
853
854
855 \bwebdoc{Storage:Device:RandomAccess}
856 \item [Random Access = \byesorno{}]
857 \index[sd]{Random access}
858 \index[sd]{Directive!Random access}
859 If \bvalue{yes}, the archive device is assumed to be a random access medium
860 which supports the \textbf{lseek} (or \textbf{lseek64} if Largefile is enabled
861 during configuration) facility. This should be set to \bvalue{yes} for all
862 file systems such as USB, and fixed files. It should be set to
863 \bvalue{no} for non-random access devices such as tapes and named pipes.
864
865
866 \bwebdoc{Storage:Device:RequiresMount}
867 \item [Requires Mount = \byesorno{}]
868 \index[sd]{Requires Mount }
869 When this directive is enabled, the Storage daemon will submit
870 a \textbf{Mount Command} before attempting to open the device.
871 You must set this directive to \bvalue{yes} for removable
872 file systems such as USB devices that are not automatically mounted
873 by the operating system when plugged in or opened by \bacula{}.
874 It should be set to \bvalue{no} for
875 all other devices such as tapes and fixed filesystems. It should also
876 be set to \bvalue{no} for any removable device that is automatically
877 mounted by the operating system when opened (e.g. USB devices mounted
878 by udev or hotplug). This directive
879 indicates if the device requires to be mounted using the \textbf{Mount Command}.
880 To be able to write devices need a mount, the following
881 directives must also be defined: \textbf{Mount Point}, \textbf{Mount Command},
882 and \textbf{Unmount Command}.
883
884 \bwebdoc{Storage:Device:MountPoint}
885 \item [Mount Point = \bbracket{directory}]
886 \index[sd]{Mount Point}
887 Directory where the device can be mounted.
888 This directive is used only
889 for devices that have \textbf{Requires Mount} enabled such as
890 USB file devices.
891
892 \bwebdoc{Storage:Device:MountCommand}
893 \item [Mount Command = \bbracket{name-string}]
894 \index[sd]{Mount Command}
895 This directive specifies the command that must be executed to mount
896 devices such as many USB devices. Before the command is
897 executed, \%a is replaced with the Archive Device, and \%m with the Mount
898 Point.
899
900 See the \bilink{Edit Codes}{blb:mountcodes} section below for more details of
901 the editing codes that can be used in this directive.
902
903 If you need to specify multiple commands, create a shell script.
904
905 \bwebdoc{Storage:Device:UnmountCommand}
906 \item [Unmount Command = \bbracket{name-string}]
907 \index[sd]{Unmount Command}
908 This directive specifies the command that must be executed to unmount
909 devices such as many USB devices. Before the command is
910 executed, \%a is replaced with the Archive Device, and \%m with the Mount
911 Point.
912
913 Most frequently, you will define it as follows:
914
915 \begin{bVerbatim}
916 Unmount Command = "/bin/umount %m"
917 \end{bVerbatim}
918
919 See the \bilink{Edit Codes}{blb:mountcodes} section below for more details of
920 the editing codes that can be used in this directive.
921
922 If you need to specify multiple commands, create a shell script.
923
924 \bwebdoc{Storage:Device:BlockChecksum}
925 \item[Block Checksum = \byesorno{}]
926 \index[sd]{Directive!Block Checksum}
927 You may turn off the Block Checksum (CRC32) code that \bacula{} uses when
928 writing blocks to a Volume. Doing so can reduce the Storage daemon CPU usage
929 slightly. It will also permit \bacula{} to read a Volume that has corrupted
930 data.
931
932 The default is \bdefaultvalue{yes} -- i.e. the checksum is computed on write and
933 checked on read.
934
935 \textbf{We do not recommend to turn this off} particularly on older tape
936 drives or for disk Volumes where doing so may allow corrupted data to go
937 undetected.
938
939 \bwebdoc{Storage:Device:MinimumBlockSize}
940 \item [Minimum block size = \bbracket{size-in-bytes}]
941 \index[sd]{Minimum block size}
942 \index[sd]{Directive!Minimum block size}
943 On most modern tape drives, you will not need or want to specify this
944 directive, and if you do so, it will be to make \bacula{} use fixed block
945 sizes. This statement applies only to non-random access devices (e.g.
946 tape drives). Blocks written by the storage daemon to a non-random
947 archive device will never be smaller than the given \textbf{size-in-bytes}.
948 The Storage daemon will attempt to efficiently fill blocks with data
949 received from active sessions but will, if necessary, add padding to a
950 block to achieve the required minimum size.
951
952 To force the block size to be fixed, as is the case for some non-random
953 access devices (tape drives), set the \textbf{Minimum block size} and the
954 \textbf{Maximum block size} to the same value (zero included). The default
955 is that both the minimum and maximum block size are \bdefaultvalue{zero} and the default
956 block size is \bdefaultvalue{64,512 bytes}.
957
958 For example, suppose you want a fixed block size of 100K bytes, then you
959 would specify:
960
961 \begin{bVerbatim}
962 Minimum block size = 100K
963 Maximum block size = 100K
964 \end{bVerbatim}
965
966 Please note that if you specify a fixed block size as shown above, the tape
967 drive must either be in variable block size mode, or if it is in fixed block
968 size mode, the block size (generally defined by \btool{mt}) \textbf{must} be
969 identical to the size specified in \bacula{} -- otherwise when you attempt to
970 re-read your Volumes, you will get an error.
971
972 If you want the block size to be variable but with a 64K minimum and \bdefaultvalue{200K}
973 maximum (and default as well), you would specify:
974
975 \begin{bVerbatim}
976 Minimum block size = 64K
977 Maximum blocksize = 256K
978 \end{bVerbatim}
979
980 \bwebdoc{Storage:Device:MaximumBlockSize}
981 \item [Maximum block size = \bbracket{size-in-bytes}]
982 \index[sd]{Maximum Block Size}
983 \index[sd]{Directive!Maximum block size}
984 On most modern tape drives, you will not need to specify this directive.
985 If you do so, it will most likely be to reduce shoe-shine and improve
986 performance on more modern LTO drives. The Storage daemon will always
987 attempt to write blocks of the specified \textbf{size-in-bytes} to the
988 archive device. As a consequence, this statement specifies both the
989 default block size and the maximum block size. The size written never
990 exceeds the given \textbf{size-in-bytes}. If adding data to a block would
991 cause it to exceed the given maximum size, the block will be written to
992 the archive device, and the new data will begin a new block.
993
994 If no value is specified or zero is specified, the Storage daemon will
995 use a default block size of \bdefaultvalue{64,512 bytes} (126 * 512).
996
997 The maximum \textbf{size-in-bytes} possible is 4,000,000.
998
999 \bwebdoc{Storage:Device:HardwareEndOfMedium}
1000 \item [Hardware End of Medium = \byesorno{}]
1001 \index[sd]{Hardware End of Medium}
1002 \index[sd]{Directive!Hardware End of Medium}
1003 If \bvalue{no}, the archive device is not required to support end of medium
1004 ioctl request, and the storage daemon will use the forward space file
1005 function to find the end of the recorded data. If \bvalue{yes}, the archive
1006 device must support the {\tt ioctl} {\tt MTEOM} call, which will position
1007 the tape to the end of the recorded data. In addition, your SCSI driver must
1008 keep track of the file number on the tape and report it back correctly by
1009 the \textbf{MTIOCGET} ioctl. Note, some SCSI drivers will correctly forward
1010 space to the end of the recorded data, but they do not keep track of the
1011 file number. On Linux machines, the SCSI driver has a \textbf{fast-eod}
1012 option, which if set will cause the driver to lose track of the file
1013 number. You should ensure that this option is always turned off using the
1014 \btool{mt} program.
1015
1016 Default setting for Hardware End of Medium is \bdefaultvalue{yes}. This function is
1017 used before appending to a tape to ensure that no previously written data is
1018 lost. We recommend if you have a non-standard or unusual tape drive that you
1019 use the \btool{btape} program to test your drive to see whether or not it
1020 supports this function. All modern (after 1998) tape drives support this
1021 feature.
1022
1023 \bwebdoc{Storage:Device:FastForwardSpaceFile}
1024 \item [Fast Forward Space File = \byesorno{}]
1025 \index[sd]{Fast Forward Space File}
1026 \index[sd]{Directive!Fast Forward Space File}
1027 If \bvalue{no}, the archive device is not required to support keeping track of
1028 the file number (\textbf{MTIOCGET} ioctl) during forward space file. If \bvalue{yes},
1029 the archive device must support the {\tt ioctl} {\tt MTFSF} call, which
1030 virtually all drivers support, but in addition, your SCSI driver must keep
1031 track of the file number on the tape and report it back correctly by the
1032 \textbf{MTIOCGET} ioctl. Note, some SCSI drivers will correctly forward space,
1033 but they do not keep track of the file number or more seriously, they do not
1034 report end of medium.
1035
1036 Default setting for Fast Forward Space File is \bdefaultvalue{yes}.
1037
1038 \bwebdoc{Storage:Device:UseMtiocget}
1039 \item [Use MTIOCGET = \byesorno{}]
1040 \index[sd]{Use MTIOCGET}
1041 \index[sd]{Directive!Use MTIOCGET}
1042 If \bvalue{no}, the operating system is not required to support keeping track of
1043 the file number and reporting it in the (\textbf{MTIOCGET} ioctl). The default
1044 is \bdefaultvalue{yes}. If you must set this to No, \bacula{} will do the proper file
1045 position determination, but it is very unfortunate because it means that
1046 tape movement is very inefficient.
1047 Fortunately, this operation system deficiency seems to be the case only
1048 on a few *BSD systems. Operating systems known to work correctly are
1049 Solaris, Linux and FreeBSD.
1050
1051 \bwebdoc{Storage:Device:BsfAtEom}
1052 \item [BSF at EOM = \byesorno{}]
1053 \index[sd]{BSF at EOM}
1054 \index[sd]{Directive!BSF at EOM}
1055 If \bdefaultvalue{no}, the default, no special action is taken by \bacula{} with the End
1056 of Medium (end of tape) is reached because the tape will be positioned after
1057 the last EOF tape mark, and \bacula{} can append to the tape as desired.
1058 However, on some systems, such as FreeBSD, when \bacula{} reads the End of
1059 Medium (end of tape), the tape will be positioned after the second EOF tape
1060 mark (two successive EOF marks indicated End of Medium). If \bacula{} appends
1061 from that point, all the appended data will be lost. The solution for such
1062 systems is to specify \textbf{BSF at EOM} which causes \bacula{} to backspace over
1063 the second EOF mark. Determination of whether or not you need this directive
1064 is done using the \bcommandname{test} command in the \btool{btape} program.
1065
1066
1067 \bwebdoc{Storage:Device:TwoEof}
1068 \item [TWO EOF = \byesorno{}]
1069 \index[sd]{TWO EOF}
1070 \index[sd]{Directive!TWO EOF}
1071 If \bvalue{yes}, \bacula{} will write two end of file marks when terminating a
1072 tape -- i.e. after the last job or at the end of the medium. If \bdefaultvalue{no},
1073 the default, \bacula{} will only write one end of file to terminate the tape.
1074
1075 \bwebdoc{Storage:Device:BackwardSpaceRecord}
1076 \item [Backward Space Record = \byesorno{}]
1077 \index[sd]{Backward Space Record}
1078 \index[sd]{Directive!Backward Space Record}
1079 If \bvalue{yes}, the archive device supports the {\tt MTBSR ioctl} to backspace
1080 records. If \bvalue{no}, this call is not used and the device must be rewound
1081 and advanced forward to the desired position. Default is \bdefaultvalue{yes} for non
1082 random-access devices. This function if enabled is used at the end of a
1083 Volume after writing the end of file and any ANSI/IBM labels to determine
1084 whether or not the last block was written correctly. If you turn this
1085 function off, the test will not be done. This causes no harm as the re-read
1086 process is precautionary rather than required.
1087
1088 \bwebdoc{Storage:Device:BackwardSpaceFile}
1089 \item [Backward Space File = \byesorno{}]
1090 \index[sd]{Backward Space File}
1091 \index[sd]{Directive!Backward Space File}
1092 If \bvalue{yes}, the archive device supports the \textbf{MTBSF} and \textbf{MTBSF ioctl}s
1093 to backspace over an end of file mark and to the start of a file. If
1094 \bvalue{no}, these calls are not used and the device must be rewound and
1095 advanced forward to the desired position. Default is \bdefaultvalue{yes} for non
1096 random-access devices.
1097
1098 \bwebdoc{Storage:Device:ForwardSpaceRecord}
1099 \item [Forward Space Record = \byesorno{}]
1100 \index[sd]{Forward Space Record}
1101 \index[sd]{Directive!Forward Space Record}
1102 If \bvalue{yes}, the archive device must support the \textbf{MTFSR ioctl} to
1103 forward space over records. If \bvalue{no}, data must be read in order to
1104 advance the position on the device. Default is \bdefaultvalue{yes} for non
1105 random-access devices.
1106
1107 \bwebdoc{Storage:Device:ForwardSpaceFile}
1108 \item [Forward Space File = \byesorno{}]
1109 \index[sd]{Forward Space File}
1110 \index[sd]{Directive!Forward Space File}
1111 If \bvalue{yes}, the archive device must support the \texttt{MTFSF ioctl} to
1112 forward space by file marks. If \bvalue{no}, data must be read to advance the
1113 position on the device. Default is \bdefaultvalue{yes} for non random-access devices.
1114
1115 \bwebdoc{Storage:Device:OfflineOnUnmount}
1116 \item [Offline On Unmount = \byesorno{}]
1117 \index[sd]{Offline On Unmount}
1118 \index[sd]{Directive!Offline On Unmount}
1119 The default for this directive is \bdefaultvalue{no}. If \bvalue{yes} the archive device
1120 must support the {\tt MTOFFL ioctl} to rewind and take the volume offline. In
1121 this case, \bacula{} will issue the offline (eject) request before closing the
1122 device during the \bcommandname{unmount} command. If \bvalue{no} \bacula{} will not attempt
1123 to offline the device before unmounting it. After an offline is issued, the
1124 cassette will be ejected thus \textbf{requiring operator intervention} to
1125 continue, and on some systems require an explicit load command to be issued
1126 (\btool{mt -f /dev/xxx load}) before the system will recognize the tape. If you
1127 are using an autochanger, some devices require an offline to be issued prior
1128 to changing the volume. However, most devices do not and may get very
1129 confused.
1130
1131 If you are using a Linux 2.6 kernel or other OSes
1132 such as FreeBSD or Solaris, the Offline On Unmount will leave the drive
1133 with no tape, and \bacula{} will not be able to properly open the drive and
1134 may fail the job. For more information on this problem, please see the
1135 \bxlink{description of Offline On Unmount}{blb:NoTapeInDrive}{problems}{subsection}
1136 in the \bxlink{Tape Testing}{blb:TapeTestingChapter}{problems}{chapter} of the \bproblemman{}.
1137
1138 \bwebdoc{Storage:Device:MaximumVolumeSize}
1139 \item [Maximum Volume Size = \bbracket{size}]
1140 \index[sd]{Maximum Volume Size}
1141 \index[sd]{Directive!Maximum Volume Size}
1142 No more than \textbf{size} bytes will be written onto a given volume on the
1143 archive device. This directive is used mainly in testing \bacula{} to
1144 simulate a small Volume. It can also be useful if you wish to limit the
1145 size of a File Volume to say less than 2GB of data. In some rare cases
1146 of really antiquated tape drives that do not properly indicate when the
1147 end of a tape is reached during writing (though I have read about such
1148 drives, I have never personally encountered one). Please note, this
1149 directive is deprecated (being phased out) in favor of the \textbf{Maximum Volume Bytes}
1150 defined in the Director's configuration file.
1151
1152 \bwebdoc{Storage:Device:MaximumFileSize}
1153 \item [Maximum File Size = \bbracket{size}]
1154 \index[sd]{Maximum File Size}
1155 \index[sd]{Directive!Maximum File Size}
1156 No more than \textbf{size} bytes will be written into a given logical file
1157 on the volume. Once this size is reached, an end of file mark is
1158 written on the volume and subsequent data are written into the next
1159 file. Breaking long sequences of data blocks with file marks permits
1160 quicker positioning to the start of a given stream of data and can
1161 improve recovery from read errors on the volume. The default is \bdefaultvalue{one Gigabyte}.
1162 This directive creates \acs{EOF} marks only on tape media.
1163 However, regardless of the medium type (tape, disk, USB ...) each time
1164 a the Maximum File Size is exceeded, a record is put into the catalog
1165 database that permits seeking to that position on the medium for
1166 restore operations. If you set this to a small value (e.g. 1MB),
1167 you will generate lots of database records (JobMedia) and may
1168 significantly increase CPU/disk overhead.
1169
1170 If you are configuring an LTO-3 or LTO-4 tape, you probably will
1171 want to set the \bdirectivename{Maximum File Size} to \bvalue{2GB} to avoid making
1172 the drive stop to write an \acs{EOF} mark.
1173
1174 Note, this directive does not limit the size of Volumes that \bacula{}
1175 will create regardless of whether they are tape or disk volumes. It
1176 changes only the number of EOF marks on a tape and the number of
1177 block positioning records (see below) that are generated. If you
1178 want to limit the size of all Volumes for a particular device, use
1179 the \bdirectivename{Maximum Volume Size} directive (above), or use the
1180 \bdirectivename{Maximum Volume Bytes} directive in the Director's Pool resource,
1181 which does the same thing but on a Pool (Volume) basis.
1182
1183 \bwebdoc{Storage:Device:MaximumFileIndex}
1184 \item [Maximum File Index = \bbracket{size}]
1185 \index[sd]{Maximum File Index}
1186 \index[sd]{Directive!Maximum File Index}
1187
1188 Some data might include information about the actual position of a block in
1189 the data stream. This information is stored in the catalog inside the
1190 \btable{FileMedia} table. By default, one index record will be created every 100MB of
1191 data. The index permits quicker positioning to the start of a given block in
1192 the \bacula{} Volume and can improve the Single Item Restore feature. If you
1193 set this to a small value (e.g. 1MB), you will generate lots of database
1194 records (FileMedia) and may significantly increase \acs{CPU}/disk overhead.
1195
1196 \bwebdoc{Storage:Device:MaximumPartSize}
1197 \item [Maximum Part Size = \bbracket{size}]
1198 \index[sd]{Maximum Part Size}
1199 \index[sd]{Directive!Maximum Part Size}
1200
1201 This directive allows one to specify the maximum size for each part.
1202 Smaller part sizes will reduce restore costs, but may require a small
1203 additional overhead to handle multiple parts. The maximum number of parts
1204 permitted in a Cloud Volume is \bvalue{524,288}. The maximum size of any given part
1205 is approximately 17.5TB.
1206
1207 \bwebdoc{Storage:Device:BlockPositioning}
1208 \item [Block Positioning = \byesorno{}]
1209 \index[sd]{Block Positioning}
1210 \index[sd]{Directive!Block Positioning}
1211 This directive tells \bacula{} not to use block positioning when doing restores.
1212 Turning this directive off can cause \bacula{} to be \textbf{extremely} slow
1213 when restoring files. You might use this directive if you wrote your
1214 tapes with \bacula{} in variable block mode (the default), but your drive
1215 was in fixed block mode. The default is \bdefaultvalue{yes}.
1216
1217 \bwebdoc{Storage:Device:MaximumNetworkBufferSize}
1218 \item [Maximum Network Buffer Size = \bbracket{bytes}]
1219 \index[sd]{Maximum Network Buffer Size}
1220 \index[sd]{Directive!Maximum Network Buffer Size}
1221 where \emph{bytes} specifies the initial network buffer size to use with the
1222 File daemon. This size will be adjusted down if it is too large until
1223 it is accepted by the OS. Please use care in setting this value since if
1224 it is too large, it will be trimmed by 512 bytes until the OS is happy,
1225 which may require a large number of system calls. The default value is
1226 \bdefaultvalue{32,768} bytes. The maximum value is \bvalue{1,000,000} bytes.
1227
1228 The default size was chosen to be relatively large but not too big in
1229 the case that you are transmitting data over Internet. It is clear that
1230 on a high speed local network, you can increase this number and improve
1231 performance. For example, some users have found that if you use a value
1232 of 65,536 bytes they get five to ten times the throughput. Larger values for
1233 most users don't seem to improve performance. If you are interested
1234 in improving your backup speeds, this is definitely a place to
1235 experiment. You will probably also want to make the corresponding change
1236 in each of your File daemons conf files.
1237
1238
1239 \bwebdoc{Storage:Device:MaximumSpoolSize}
1240 \item [Maximum Spool Size = \bbracket{bytes}]
1241 \index[sd]{Maximum Spool Size}
1242 \index[sd]{Directive!Maximum Spool Size}
1243 where the bytes specify the maximum spool size for all jobs that are
1244 running. The default is \bdefaultvalue{no limit}.
1245
1246 \bwebdoc{Storage:Device:MaximumJobSpoolSize}
1247 \item [Maximum Job Spool Size = \bbracket{bytes}]
1248 \index[sd]{Maximum Job Spool Size}
1249 \index[sd]{Directive!Maximum Job Spool Size}
1250 where the bytes specify the maximum spool size for any one job that is
1251 running. The default is \bdefaultvalue{no limit}.
1252 This directive is implemented only in version 1.37 and later.
1253
1254 \bwebdoc{Storage:Device:SpoolDirectory}
1255 \item [Spool Directory = \bbracket{directory}]
1256 \index[sd]{Spool Directory}
1257 \index[sd]{Directive!Spool Directory}
1258 specifies the name of the directory to be used to store the spool files for
1259 this device. This directory is also used to store temporary part files when
1260 writing to a device that requires mount (USB). The default is to use the
1261 \bdefaultvalue{working directory}.
1262
1263 \bwebdoc{Storage:Device:UseLintape}
1264 \item [Use LinTape = \byesorno{}]
1265 \index[sd]{Use Lintape}
1266 \index[sd]{Directive!Use Lintape}
1267 If \bvalue{yes}, the archive device must use the \texttt{IBM Lintape} Kernel interface instead
1268 of the standard \texttt{ST} Linux Kernel module. The \texttt{Use MTIOCGET = No} should be
1269 used when using the Lintape module. The default is \bdefaultvalue{no}, the use
1270 of the default \texttt{ST} Linux Kernel module is recommended.
1271
1272 \end{bdescription}
1273
1274
1275 % comes from the newbsfeature, but we need also to generate bweb documentation
1276 \section{Cloud Resource}
1277
1278 The Cloud Storage Driver must be installed in the \bacula{} Storage Daemon
1279 \bdirectivename{Plugin Directory} to be used.
1280
1281 \begin{bdescription}
1282 \label{Storage:Cloud:Name}
1283 \item [Name = \bbracket{Device-Name}]
1284 \index[sd]{Name}
1285 \index[sd]{Directive!Name}
1286
1287 The name of the Cloud resource. This is the logical Cloud name, and may be
1288 any string up to 127 characters in length.% Shown as \textbf{S3Cloud} above.
1289
1290 \label{Storage:Cloud:Description}
1291 \item [Description = \bbracket{Text}]
1292 The description is used for display purposes as is the case with all resource.
1293
1294 \label{Storage:Cloud:Driver}
1295 \item [Driver = \bbracket{DriverName}]
1296 \index[sd]{Driver}
1297
1298 This defines which driver to use. It can be \bvalue{S3} or \bvalue{Amazon}.
1299 There is also a \bvalue{File} driver, which is used mostly for testing.
1300
1301 \label{Storage:Cloud:HostName}
1302 \item [Host Name = \bbracket{Name}]
1303 \index[sd]{HostName}
1304 This directive specifies the hostname to be used in the \acs{URL}. Each Cloud
1305 service provider has a different and unique hostname. The maximum size is
1306 255 characters and may contain a \acs{TCP} port specification. This directive is not
1307 used with Azure cloud.
1308
1309 \label{Storage:Cloud:BucketName}
1310 \item [Bucket Name = \bbracket{Name}]
1311 \index[sd]{BucketName}
1312
1313 This directive specifies the bucket name that you wish to use on the Cloud
1314 service. This name is normally a unique name that you create on the cloud
1315 service that identifies where you want to place your Cloud Volumes. The
1316 maximum bucket name size is 255 characters.
1317
1318 \label{Storage:Cloud:AccessKey}
1319 \item [Access Key = \bbracket{String}]
1320 \index[sd]{AccessKey}
1321
1322 The access key is your unique user identifier given to you by your cloud
1323 service provider.
1324
1325 \label{Storage:Cloud:SecretKey}
1326 \item [Secret Key = \bbracket{String}]
1327 \index[sd]{SecretKey}
1328
1329 The secret key is the security key that was given to you by your cloud
1330 service provider. It is equivalent to a password.
1331
1332 \label{Storage:Cloud:Protocol}
1333 \item [Protocol = \bbracket{HTTP | HTTPS}]
1334 \index[sd]{Protocol}
1335
1336 The protocol defines the communications protocol to use with the cloud
1337 service provider. The two protocols currently supported are: \acs{HTTPS}
1338 and \acs{HTTP}. The default is \acs{HTTPS}.
1339
1340 \label{Storage:Cloud:UriStyle}
1341 \item [Uri Style = \bbracket{VirtualHost | Path}]
1342 \index[sd]{UriStyle}
1343
1344 This directive specifies the \acs{URI} style to use to communicate with the cloud
1345 service provider. The two \bdirectivename{Uri Styles} currently supported are:
1346 \bvalue{VirtualHost} and \bvalue{Path}. The default is \bdefaultvalue{VirtualHost}.
1347
1348 \label{Storage:Cloud:TruncateCache}
1349 \item [Truncate Cache = \bbracket{Truncate-kw}]
1350 \index[sd]{TruncateCache}
1351
1352 This directive specifies when \bacula{} should automatically remove (truncate)
1353 the local cache parts. Local cache parts can only be removed if they have
1354 been uploaded to the cloud. The currently implemented values are:
1355
1356 \begin{bdescription}
1357 \item [ No ] Do not remove cache. With this option you must manually
1358 delete the cache parts with a \bconsolename{} \bcommandname{truncate cache}
1359 command, or do so with an \textbf{Admin} Job that runs an
1360 \bcommandname{truncate cache} command. This is the default.
1361 \item [ AfterUpload ] Each part will be removed just after it is
1362 uploaded. Note, if this option\footnote{Not yet implemented.} is specified, all restores will require
1363 a download from the Cloud.
1364 \item [ AtEndOfJob ] With this option\footnote{Note yet implemented/}, at the end of the Job, every part that has
1365 been uploaded to the Cloud will be removed (truncated).
1366 \end{bdescription}
1367
1368 \label{Storage:Cloud:Upload}
1369 \item [Upload = \bbracket{Upload-kw}]
1370
1371 This directive specifies when local cache parts
1372 will be uploaded to the Cloud. The options are:
1373
1374 \begin{bdescription}
1375 \item [ No ] Do not upload cache parts. With this option you must manually upload the cache parts with a \bconsolename{}
1376 \bcommandname{upload} command, or do so with an \textbf{Admin} Job that runs an \bcommandname{upload} command. This is the default.
1377 \item [ EachPart ] With this option, each part will be uploaded
1378 when it is complete i.e. when the next part is created or at the
1379 end of the Job.
1380 \item [ AtEndOfJob ] With this option\footnote{Not implemented yet.} all parts that have not been
1381 previously uploaded will be uploaded at the end of the Job.
1382 \end{bdescription}
1383 \label{Storage:Cloud:MaximumConcurrentUploads}
1384 \item [Maximum Concurrent Uploads = \bbracket{number}]
1385 The default is \bdefaultvalue{3}, but by using this directive, you may set it to any value
1386 you want.
1387
1388 \label{Storage:Cloud:MaximumConcurrentDownloads}
1389 \item [Maximum Concurrent Downloads = \bbracket{number}]
1390 The default is \bdefaultvalue{3}, but by using this directive, you may set it to any value
1391 you want.
1392
1393 \label{Storage:Cloud:MaximumUploadBandwidth}
1394 \item [Maximum Upload Bandwidth = \bbracket{speed}]
1395
1396 The default is \bdefaultvalue{unlimited}, but by using this directive, you may limit the
1397 upload bandwidth used globally by all devices referencing this Cloud
1398 resource.
1399
1400 \label{Storage:Cloud:MaximumDownloadBandwidth}
1401 \item [Maximum Download Bandwidth = \bbracket{speed}]
1402
1403 The default is \bdefaultvalue{unlimited}, but by using this directive, you may limit the
1404 download bandwidth used globally by all devices referencing this Cloud
1405 resource.
1406
1407 \label{Storage:Cloud:Region}
1408 \item [Region = \bbracket{String}]
1409
1410 The Cloud resource can be configured to use a specific endpoint within a
1411 region. This directive is required for AWS-V4 regions. ex:
1412 \bvalueddirective{Region}{"eu-central-1"}
1413 \end{bdescription}
1414
1415 An example of a Cloud Resource might be:
1416
1417 \begin{bVerbatim}
1418 Cloud {
1419 Name = AWSCloud
1420 Driver = "Amazon"
1421 HostName = "s3.amazonaws.com"
1422 BucketName = "BaculaVolumes"
1423 AccessKey = "BZIXAIS39DYNER5FZ"
1424 SecretKey = "beesheeg7iTe0Gaex7aedie4aWohfuewohGaa0"
1425 Protocol = HTTPS
1426 UriStyle = VirtualHost
1427 Truncate Cache = No
1428 Upload = EachPart
1429 Region = "us-east-1"
1430 MaximumUploadBandwidth = 5MB/s
1431 }
1432 \end{bVerbatim}
1433
1434 \begin{bdescription}
1435 \label{Storage:Cloud:TransferPriority}
1436 \item [Transfer Priority = \bbracket{High | Medium | Low}]
1437
1438 When restoring directly a part from Glacier, this directive indicates the
1439 rehydration priority level. Values can be \textbf{High}, \textbf{Medium} or
1440 \textbf{Low}. Default is \textbf{High}. Those values match respectively
1441 \textbf{Expeditive}, \textbf{Standard} and \textbf{Bulk} transfers tiers
1442 within S3.
1443
1444 \label{Storage:Cloud:TransferRetention}
1445 \item [Transfer Retention = \bbracket{time-period-specification}]
1446
1447 This directive indicates the number of days S3 should keep the rehydrated
1448 part online. The minimum value is 1 day. The default is 5 days.
1449 \end{bdescription}
1450
1451 \label{blb:mountcodes}
1452 \section{Edit Codes for Mount and Unmount Directives}
1453 \index[general]{Directives!Edit Codes}
1454 \index[general]{Edit Codes for Mount and Unmount Directives }
1455
1456 Before submitting the \textbf{Mount Command}, \textbf{Unmount Command},
1457 \textbf{Write Part Command}, or \textbf{Free Space Command} directives
1458 to the operating system, \bacula{} performs character substitution of the
1459 following characters:
1460
1461 \begin{bVerbatim}
1462 %% = %
1463 %a = Archive device name
1464 %e = erase (set if cannot mount and first part)
1465 %n = part number
1466 %m = mount point
1467 %v = last part name (i.e. filename)
1468 \end{bVerbatim}
1469
1470
1471 \section{Devices that require a mount (USB)}
1472 \index[general]{Devices that require a mount (USB)}
1473
1474 All the directives in this section are implemented only in
1475 \bacula{} version 1.37 and later and hence are available in version 1.38.6.
1476
1477 As of version 1.39.5, the directives
1478 ``Requires Mount'', ``Mount Point'', ``Mount Command'', and ``Unmount Command''
1479 apply to removable filesystems such as USB.
1480
1481 \begin{bdescription}
1482
1483 \bwebdoc{Storage:Device:RequiresMount}
1484 \item [Requires Mount = \byesorno{}]
1485 \index[sd]{Requires Mount}
1486 \index[sd]{Directive!Requires Mount}
1487 You must set this directive to \bvalue{yes} for removable devices such as
1488 USB unless they are automounted, and to \bvalue{no} for all other devices
1489 (tapes/files). This directive indicates if the device requires to be
1490 mounted to be read, and if it must be written in a special way. If it
1491 set, \textbf{Mount Point}, \textbf{Mount Command}, \textbf{Unmount Command}
1492 directives must also be defined.
1493
1494 \bwebdoc{Storage:Device:MountPoint}
1495 \item [Mount Point = \bbracket{directory}]
1496 \index[sd]{Mount Point}
1497 \index[sd]{Directive!Mount Point}
1498 Directory where the device can be mounted.
1499
1500 \bwebdoc{Storage:Device:MountCommand}
1501 \item [Mount Command = \bbracket{name-string}]
1502 \index[sd]{Mount Command}
1503 \index[sd]{Directive!Mount Command}
1504 Command that must be executed to mount the device. Before the command is
1505 executed, \%a is replaced with the Archive Device, and \%m with the Mount
1506 Point.
1507
1508 Most frequently, you will define it as follows:
1509
1510 \begin{bVerbatim}
1511 Mount Command = "/bin/mount -t iso9660 -o ro %a %m"
1512 \end{bVerbatim}
1513
1514 For some media, you may need multiple commands. If so, it is recommended
1515 that you use a shell script instead of putting them all into the Mount
1516 Command. For example, instead of this:
1517
1518 \begin{bVerbatim}
1519 Mount Command = "/usr/local/bin/mymount"
1520 \end{bVerbatim}
1521
1522 Where that script contains:
1523
1524 \begin{bVerbatim}
1525 #!/bin/sh
1526 ndasadmin enable -s 1 -o w
1527 sleep 2
1528 mount /dev/ndas-00323794-0p1 /backup
1529 \end{bVerbatim}
1530
1531 Similar consideration should be given to all other Command parameters.
1532
1533 \bwebdoc{Storage:Device:UnmountCommand}
1534 \item [Unmount Command = \bbracket{name-string}]
1535 \index[sd]{Unmount Command}
1536 \index[sd]{Directive!Unmount Command}
1537 Command that must be executed to unmount the device. Before the command is
1538 executed, \%a is replaced with the Archive Device, and \%m with the Mount
1539 Point.
1540
1541 Most frequently, you will define it as follows:
1542
1543 \begin{bVerbatim}
1544 Unmount Command = "/bin/umount %m"
1545 \end{bVerbatim}
1546
1547 If you need to specify multiple commands, create a shell script.
1548
1549 \end{bdescription}
1550
1551 %% This pulls in the Autochanger resource from another file.
1552 \label{blb:AutochangerRes}
1553 \label{blb:AutochangerResource1}
1554 \input{autochangerres}
1555
1556 \section{Capabilities}
1557 \index[general]{Capabilities}
1558
1559 \begin{bdescription}
1560
1561 \bwebdoc{Storage:Device:LabelMedia}
1562 \item [Label Media = \byesorno{}]
1563 \index[general]{Label Media}
1564 \index[sd]{Label Media}
1565 \index[sd]{Directive!Label Media}
1566 If \bvalue{yes}, permits this device to automatically label blank media
1567 without an explicit operator command. It does so by using an internal
1568 algorithm as defined on the \bilink{Label Format}{blb:Label} record in each
1569 Pool resource. If this is \bdefaultvalue{no} as by default, \bacula{} will label
1570 tapes only by specific operator command (\bcommandname{label} in the Console) or
1571 when the tape has been recycled. The automatic labeling feature is most
1572 useful when writing to disk rather than tape volumes.
1573
1574 \bwebdoc{Storage:Device:AutomaticMount}
1575 \item [Automatic mount = \byesorno{}]
1576 \index[sd]{Automatic mount}
1577 \index[sd]{Directive!Automatic mount}
1578 If \bdefaultvalue{yes} (the default), permits the daemon to examine the device to
1579 determine if it contains a \bacula{} labeled volume. This is done
1580 initially when the daemon is started, and then at the beginning of each
1581 job. This directive is particularly important if you have set
1582 \textbf{Always Open = no} because it permits \bacula{} to attempt to read the
1583 device before asking the system operator to mount a tape. However,
1584 please note that the tape must be mounted before the job begins.
1585
1586 \end{bdescription}
1587
1588 \section{Messages Resource}
1589 \label{blb:MessagesResource1}
1590 \index[general]{Resource!Messages}
1591 \index[general]{Messages Resource}
1592
1593 For a description of the Messages Resource, please see the
1594 \bilink{Messages Resource}{blb:MessagesChapter} Chapter of this
1595 manual.
1596
1597 \bwebdoc{SDStatisticsResource}
1598 \section{The Statistics Resource}
1599 \index[general]{Resource!Statistics}
1600 \index[general]{Statistics Resource}
1601
1602 The \bresourcename{Statistics} Resource defines the statistic collector function that can send
1603 information to a Graphite instance, to a \acs{CSV} file or to bconsole with the
1604 \bcommandname{statistics} command (See \vref{blb:StatisticsCommand} for more information).
1605
1606
1607 \begin{bdescription}
1608
1609 \item [Statistics]
1610 \index[dir]{Statistics}
1611 \index[dir]{Directive!Statistics}
1612 Start of the \bresourcename{Statistics} resource. Statistics directives are optional.
1613
1614 \bwebdoc{Storage:Statistics:Name}
1615 \item [Name = \bbracket{name}]
1616 \index[dir]{Name}
1617 \index[dir]{Directive!Name}
1618
1619 The Statistics directive \bdirectivename{name} is used by the system administrator. This
1620 directive is required.
1621
1622 \bwebdoc{Storage:Statistics:Description}
1623 \item [Description = \bbracket{string}]
1624 \index[dir]{Description}
1625 \index[dir]{Directive!Description}
1626
1627 The text field contains a description of the \bresourcename{Statistics} resource that will
1628 be displayed in the graphical user interface. This directive is optional.
1629
1630 \bwebdoc{Storage:Statistics:Interval}
1631 \item [Interval = \bbracket{time-interval}]
1632 \index[dir]{Interval}
1633 \index[dir]{Directive!Interval}
1634 \index[dir]{Directive!Interval}
1635
1636 The \bdirectivename{Intervall} directive instructs the Statistics collector thread how long
1637 it should sleep between every collection iteration. This directive is
1638 optional and the default value is \bdefaultvalue{300} seconds.
1639
1640 \bwebdoc{Storage:Statistics:Type}
1641 \item [Type = \bbracket{CSV|Graphite}]
1642 \index[dir]{Type}
1643 \index[dir]{Directive!Type}
1644
1645 The \bdirectivename{Type} directive specifies the Statistics backend, which may be one of the
1646 following: \bvalue{\acs{CSV}} or \bvalue{Graphite}. This directive is required.
1647 \smallskip
1648
1649 \acs{CSV} is a simple file level backend which saves all required metrics with the
1650 following format to the file: ``\bbracket{time}, \bbracket{metric}, \bbracket{value}\textbackslash{}n''
1651
1652 Where \bbracket{time} is a standard Unix time (a number of seconds from 1/01/1970)
1653 with local timezone as returned by a system call \btool{time()}, \bbracket{metric} is a
1654 Bacula metric string and \bbracket{value} is a metric value which could be in numeric
1655 format (\texttt{int}/\texttt{float}) or a string \bvalue{True} or \bvalue{False} for boolean variable. The
1656 \acs{CSV} backend requires the \bvalueddirective{File}{~} parameter.
1657 \smallskip
1658
1659 Graphite is a network backend which will send all required metrics to a Graphite
1660 server. The Graphite backend requires the \bvalueddirective{Host}{~} and \bvalueddirective{Port}{~} directives to be set.
1661
1662 If the Graphite server is not available, the metrics are automatically
1663 spooled in the working directory. When the server can be reached again,
1664 spooled metrics are despooled automatically and the spooling function is
1665 suspended.
1666
1667
1668 \bwebdoc{Storage:Statistics:Metrics}
1669 \item [Metrics = \bbracket{metricspec}]
1670 \index[dir]{Metrics}
1671 \index[dir]{Directive!Metrics}
1672
1673 The \bdirectivename{Metrics} directive allow metric filtering and \bbracket{metricspec} is a filter which
1674 enables to use \bvalue{*} and \bvalue{?} characters to match the required metric name in the
1675 same way as found in shell wildcard resolution. You can exclude filtered
1676 metric with \bvalue{!} prefix. You can define any number of filters for a single
1677 Statistics. Metrics filter is executed in order as found in
1678 configuration. This directive is optional and if not used all available
1679 metrics will be saved by this collector backend.
1680 \smallskip
1681
1682 Example:
1683 \begin{bVerbatim}
1684 # Include all metric starting with "bacula.jobs"
1685 Metrics = "bacula.jobs.*"
1686
1687 # Exclude any metric starting with "bacula.jobs"
1688 Metrics = "!bacula.jobs.*"
1689 \end{bVerbatim}
1690
1691 \bwebdoc{Storage:Statistics:Prefix}
1692 \item [Prefix = \bbracket{string}]
1693 \index[dir]{Prefix}
1694 \index[dir]{Directive!Prefix}
1695
1696 The \bdirectivename{Prefix} allows to alter the metrics name saved by collector to
1697 distinguish between different installations or daemons. The prefix string
1698 will be added to metric name as: ``\bbracket{prefix}.\bbracket{metric\_name}'' This directive is
1699 optional.
1700
1701 \bwebdoc{Storage:Statistics:Prefix}
1702 \item [File = \bbracket{filename}]
1703 \index[dir]{File}
1704 \index[dir]{Directive!File}
1705
1706 The \bdirectivename{File} is used by the \acs{CSV} collector backend and point to the full
1707 path and filename of the file where metrics will be saved. With the \acs{CSV}
1708 type, the \bdirectivename{File} directive is required. The collector thread must have the
1709 permissions to write to the selected file or create a new file if the file
1710 doesn't exist. If collector is unable to write to the file or create a new
1711 one then the collection terminates and an error message will be
1712 generated. The file is only open during the dump and is closed
1713 otherwise. Statistics file rotation could be executed by a \btool{mv} shell command.
1714
1715 \bwebdoc{Storage:Statistics:Host}
1716 \item [Host = \bbracket{hostname}]
1717 \index[dir]{Host}
1718 \index[dir]{Directive!Host}
1719
1720 The \bdirectivename{Host} directive is used for Graphite backend and specify the
1721 hostname or the \acs{IP} address of the Graphite server. When the directive Type
1722 is set to Graphite, the Host directive is required.
1723
1724 \bwebdoc{Storage:Statistics:Port}
1725 \item [Host = \bbracket{number}]
1726 \index[dir]{Port}
1727 \index[dir]{Directive!Port}
1728
1729 The \bdirectivename{Port} directive is used for Graphite backend and specify the \acs{TCP} port
1730 number of the Graphite server. When the directive Type
1731 is set to Graphite, the \bdirectivename{Port} directive is required.
1732
1733
1734 \bwebdoc{Storage:Statistics:End}
1735 \end{bdescription}
1736
1737
1738 \section{Sample Storage Daemon Configuration File}
1739 \label{blb:SampleConfiguration}
1740 \index[general]{File!Sample Storage Daemon Configuration}
1741 \index[general]{Sample Storage Daemon Configuration File}
1742
1743 A example Storage Daemon configuration file might be the following:
1744
1745 %%\footnotesize
1746 \begin{bVerbatim}
1747 #
1748 # Default Bacula Storage Daemon Configuration file
1749 #
1750 # For Bacula release 1.37.2 (07 July 2005) -- gentoo 1.4.16
1751 #
1752 # You may need to change the name of your tape drive
1753 # on the "Archive Device" directive in the Device
1754 # resource. If you change the Name and/or the
1755 # "Media Type" in the Device resource, please ensure
1756 # that bacula-dir.conf has corresponding changes.
1757 #
1758 Storage { # definition of myself
1759 Name = rufus-sd
1760 Address = rufus
1761 WorkingDirectory = "$HOME/bacula/bin/working"
1762 Pid Directory = "$HOME/bacula/bin/working"
1763 Maximum Concurrent Jobs = 20
1764 }
1765 #
1766 # List Directors who are permitted to contact Storage daemon
1767 #
1768 Director {
1769 Name = rufus-dir
1770 Password = "ZF9Ctf5PQoWCPkmR3s4atCB0usUPg+vWWyIo2VS5ti6k"
1771 }
1772 #
1773 # Restricted Director, used by tray-monitor to get the
1774 # status of the storage daemon
1775 #
1776 Director {
1777 Name = rufus-mon
1778 Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6"
1779 Monitor = yes
1780 }
1781 #
1782 # Devices supported by this Storage daemon
1783 # To connect, the Director's bacula-dir.conf must have the
1784 # same Name and MediaType.
1785 #
1786 Autochanger {
1787 Name = Autochanger
1788 Device = Drive-1
1789 Device = Drive-2
1790 Changer Command = "/opt/bacula/scripts/mtx-changer %c %o %S %a %d"
1791 Changer Device = /dev/sg0
1792 }
1793
1794 Device {
1795 Name = Drive-1 #
1796 Drive Index = 0
1797 Media Type = DLT-8000
1798 Archive Device = /dev/nst0
1799 AutomaticMount = yes; # when device opened, read it
1800 AlwaysOpen = yes;
1801 RemovableMedia = yes;
1802 RandomAccess = no;
1803 AutoChanger = yes
1804 Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'"
1805 }
1806
1807 Device {
1808 Name = Drive-2 #
1809 Drive Index = 1
1810 Media Type = DLT-8000
1811 Archive Device = /dev/nst1
1812 AutomaticMount = yes; # when device opened, read it
1813 AlwaysOpen = yes;
1814 RemovableMedia = yes;
1815 RandomAccess = no;
1816 AutoChanger = yes
1817 Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'"
1818 }
1819
1820 Device {
1821 Name = "HP DLT 80"
1822 Media Type = DLT8000
1823 Archive Device = /dev/nst0
1824 AutomaticMount = yes; # when device opened, read it
1825 AlwaysOpen = yes;
1826 RemovableMedia = yes;
1827 }
1828 #Device {
1829 # Name = SDT-7000 #
1830 # Media Type = DDS-2
1831 # Archive Device = /dev/nst0
1832 # AutomaticMount = yes; # when device opened, read it
1833 # AlwaysOpen = yes;
1834 # RemovableMedia = yes;
1835 #}
1836 #Device {
1837 # Name = Floppy
1838 # Media Type = Floppy
1839 # Archive Device = /mnt/floppy
1840 # RemovableMedia = yes;
1841 # Random Access = Yes;
1842 # AutomaticMount = yes; # when device opened, read it
1843 # AlwaysOpen = no;
1844 #}
1845 #Device {
1846 # Name = FileStorage
1847 # Media Type = File
1848 # Archive Device = /tmp
1849 # LabelMedia = yes; # lets Bacula label unlabeled media
1850 # Random Access = Yes;
1851 # AutomaticMount = yes; # when device opened, read it
1852 # RemovableMedia = no;
1853 # AlwaysOpen = no;
1854 #}
1855 #
1856 # A very old Exabyte with no end of media detection
1857 #
1858 #Device {
1859 # Name = "Exabyte 8mm"
1860 # Media Type = "8mm"
1861 # Archive Device = /dev/nst0
1862 # Hardware end of medium = No;
1863 # AutomaticMount = yes; # when device opened, read it
1864 # AlwaysOpen = Yes;
1865 # RemovableMedia = yes;
1866 #}
1867 #
1868 # Send all messages to the Director,
1869 # mount messages also are sent to the email address
1870 #
1871 Messages {
1872 Name = Standard
1873 director = rufus-dir = all
1874 operator = root = mount
1875 }
1876 \end{bVerbatim}