Pool Resource
The Pool resource defines the set of storage Volumes (tapes or files) to be used by Bacula to write the data. By configuring different Pools, you can determine which set of Volumes (media) receives the backup data. This permits, for example, to store all full backup data on one set of Volumes and all incremental backups on another set of Volumes. Alternatively, you could assign a different set of Volumes to each machine that you backup. This is most easily done by defining multiple Pools.
Another important aspect of a Pool is that it contains the default attributes (Maximum Jobs, Retention Period, Recycle flag, etc.) that will be given to a Volume when it is created. This avoids the need for you to answer a large number of questions when labeling a new Volume. Each of these attributes can later be changed on a Volume by Volume basis using the update command in the console program. Note that you must explicitly specify which Pool Bacula is to use with each Job. Bacula will not automatically search for the correct Pool.
Most often in Bacula installations all backups for all machines (Clients) go to a single set of Volumes. In this case, you will probably only use the Default Pool. If your backup strategy calls for you to mount a different tape each day, you will probably want to define a separate Pool for each day. For more information on this subject, see the Backup Strategies chapter.
To use a Pool, there are three distinct steps. First the Pool must be defined in the Director’s configuration file. Then the Pool must be written to the Catalog database. This is done automatically by the Director each time that it starts, or alternatively can be done using the create command in the console program. Finally, if you change the Pool definition in the Director’s configuration file and restart Bacula, the pool will be updated alternatively you can use the update pool console command to refresh the database image. It is this database image rather than the Director’s resource image that is used for the default Volume attributes. Note, for the pool to be automatically created or updated, it must be explicitly referenced by a Job resource.
Next the physical media must be labeled. The labeling can either be done with the label command in the bconsole program or using the btape program. The preferred method is to use the label command in the bconsole program.
Finally, you must add Volume names (and their attributes) to the Pool. For Volumes to be used by Bacula they must be of the same Media Type as the archive device specified for the job (i.e. if you are going to back up to a LTO device, the Pool must have LTO volumes defined since 8mm volumes cannot be mounted on a LTO drive). The Media Type has particular importance if you are backing up to files. When running a Job, you must explicitly specify which Pool to use. Bacula will then automatically select the next Volume to use from the Pool, but it will ensure that the Media Type of any Volume selected from the Pool is identical to that required by the Storage resource you have specified for the Job.
If you use the label command in the bconsole program to label the Volumes, they will automatically be added to the Pool, so this last step is not normally required.
It is also possible to add Volumes to the database without explicitly labeling the physical volume. This is done with the add bconsole command.
As previously mentioned, each time Bacula starts, it scans all the Pools associated with each Catalog, and if the database record does not already exist, it will be created from the Pool Resource definition. Bacula probably should do an update pool if you change the Pool definition, but currently, you must do this manually using the update pool command in the bconsole program.
The Pool Resource defined in the Director’s configuration file (bacula-dir.conf) may contain the following directives:
Pool Start of the Pool resource. There must be at least one Pool resource defined.
Name = <name> The name of the pool. For most applications, you will use the
default pool name Default. This directive is required.
MaximumVolumes = <number> This directive specifies the maximum number of volumes
(tapes or files) contained in the pool. This directive is optional, if omitted or set
to zero, any number of volumes will be permitted. In general, this directive is useful
for Autochangers where there is a fixed number of Volumes, or for File storage where
you wish to ensure that the backups made to disk files do not become too numerous or
consume too much space.
This directive is only respected in case of volumes automatically created by Bacula. If you add volumes to a pool manually with the label command, it is possible to have more volumes in a pool than specified by Maximum Volumes.
MaximumPoolBytes = <size> This directive specifies the total
maximum size of Volumes in the Pool.
This directive is optional, if omitted or set to zero, any size will be permitted. The current size of the Pool can be displayed with llist pool command. Note that the size displayed is not necessarily the sum of the size of all Volumes; it represents the effective amount of data, which can be much larger than the Volume size in case of Global Endpoint Deduplication Volumes, or smaller than the apparent file size in case of Aligned Volumes.
All types of volumes with any status are counted in the Pool size.
To exclude purged Volumes from the quota, the RecyclePool directive can be used to assign volumes to a Scratch pool once they are no longer containing valid data, or Volumes can be truncated using the ActionOnPurge functionality.
There are cases Bacula can not adhere to the Pool size limitation in a strict manner:
For Backups stored on Aligned or Deduplication Volumes, a single Volume write can represent very large amounts of data, which may lead to temporarily exceeding the configured sizes.
As the Pool Size check is done by the storage Device handler of the Storage Daemon, concurrently writing to a Pool with this setting by different Storage Devices may result in exceeding the set limit. After Volumes have been changed, the then-correct Pool size will be used.
These limitations may be resolved in a later version of Bacula.
PoolType = Backup This directive defines the pool type. It is required and the
only available value is Backup.
Storage = <storage-resource-name> The Storage directive defines the name of the
storage services where you want to backup the FileSet data. For additional details,
see the Storage Resource Chapter chapter.
The Storage resource may also be specified in the Job resource, but the value, if any,
in the Pool resource overrides any value in the Job. This Storage resource definition
is not required by either the Job resource or in the Pool, but it must be specified in
one or the other. If not configuration error will result.
StorageGroupPolicy = <Storage Group Policy Name> Storage Group Policy determines
how Storage resources (from the ’Storage’ directive) are being chosen from the Storage
list. If no StorageGroupPolicy is specified Bacula always tries to use first available
Storage from the provided list.
See StorageGroupPolicy for Job resource for more
information.
UseVolumeOnce = <yes|no> This directive if set to yes specifies that each
volume is to be used only once. This is most useful when the Media is a file and you
want a new file for each backup that is done. The default is no (i.e. use volume
any number of times). This directive will most likely be phased out (deprecated), so
you are recommended to use MaximumVolumeJobs = 1 instead.
The value defined by this directive in the bacula-dir.conf file is the default value used when a Volume is created. Once the volume is created, changing the value in the bacula-dir.conf file will not change what is stored for the Volume. To change the value for an existing Volume you must use the update command in bconsole.
See the notes below under MaximumVolumeJobs concerning using this directive with multiple simultaneous jobs.
MaximumVolumeJobs = <positive-integer> This directive specifies the maximum number
of Jobs that can be written to the Volume. If you specify 0 (the default), there is
no limit. Otherwise, when the number of Jobs backed up to the Volume equals the Volume
will be marked . When the Volume is marked it can no longer be used for appending Jobs,
much like the status. A Volume that is marked or can be recycled if recycling is
enabled, and thus used again. By setting MaximumVolumeJobs to 1, you get the
same effect as setting UseVolumeOnce=yes.
The value defined by this directive in the bacula-dir.conf file is the default
value used when a Volume is created. Once the volume is created, changing the value
in the bacula-dir.conf file will not change what is stored for the Volume. To
change the value for an existing Volume you must use the update command in the
Console.
If you are running multiple simultaneous jobs, this directive may not work correctly because when a drive is reserved for a job, this directive is not taken into account, so multiple jobs may try to start writing to the Volume. At some point, when the Media record is updated, multiple simultaneous jobs may fail since the Volume can no longer be written.
MaximumVolumeFiles = <positive-integer> This directive specifies the maximum
number of files that can be written to the Volume. If you specify 0, (the default),
there is no limit. Otherwise, when the number of files written to the Volume equals the
Volume will be marked . When the Volume is marked it can no longer be used for appending
Jobs, much like the status, but it can be recycled if recycling is enabled and thus
used again. This value is checked and the status is set only at the end of a job that
writes to the particular volume.
The value defined by this directive in the bacula-dir.conf file is the default value used when a Volume is created. Once the volume is created, changing the value in the bacula-dir.conf file will not change what is stored for the Volume. To change the value for an existing Volume you must use the update command in bconsole.
MaximumVolumeBytes = <size> This directive specifies the maximum number of bytes
that can be written to the Volume. If you specify zero (0,the default), there is
no limit except the physical size of the Volume. Otherwise, when the number of bytes
written to the Volume equals the Volume will be marked . When the Volume is marked it
can no longer be used for appending Jobs, but it can be recycled if recycling is
enabled, and thus the Volume can be re-used after recycling. The size specified is
checked just before each block is written to the Volume and if the Volume size would
exceed the specified Maximum Volume Bytes the status will be set and the Job will
request the next available Volume to continue.
This directive is particularly useful for restricting the size of disk volumes, and w ill work correctly even in the case of multiple simultaneous jobs writing to the volume.
The value defined by this directive in the bacula-dir.conf file is the default value used when a Volume is created. Once the volume is created, changing the value in the bacula-dir.conf file will not change what is stored for the Volume. To change the value for an existing Volume you must use the update command in the Console.
VolumeUseDuration = <time-period-specification> The Volume Use Duration directive
defines the time period that the Volume can be written beginning from the time of first
data write to the Volume. If the time-period specified 0 (the default), the Volume
can be written indefinitely. Otherwise, the next time a job runs that wants to access
this Volume, and the time period from the first write to the volume (the first Job
written) exceeds the time-period-specification, the Volume will be marked, which means
that no more Jobs can be appended to the Volume, but it may be recycled if recycling
is enabled. Using the command status dir applies algorithms similar to running
jobs, so during such a command, the Volume status may also be changed. Once the Volume
is recycled, it will be available for use again.
You might use this directive, for example, if you have a Volume used for Incremental backups, and Volumes used for Weekly Full backups. Once the Full backup is done, you will want to use a different Incremental Volume. This can be accomplished by setting the Volume Use Duration for the Incremental Volume to six days. I.e. it will be used for the 6 days following a Full save, then a different Incremental volume will be used. Be careful about setting the duration to short periods such as 23 hours, or you might experience problems of Bacula waiting for a tape over the weekend only to complete the backups Monday morning when an operator mounts a new tape.
The VolumeUseDuration is checked and the Used status is set only at the end of a job that writes to the particular volume, which means that even though the use duration may have expired, the catalog entry will not be updated until the next job that uses this volume is run. This directive is not intended to be used to limit volume sizes and may not work as expected (i.e. will fail jobs) if the use duration expires while multiple simultaneous jobs are writing to the volume.
Note
The value defined by this directive in the bacula-dir.conf file is the default value used when a Volume is created. Once the volume is created, changing the value in the bacula-dir.conf file will not change what is stored for the Volume. To change the value for an existing Volume you must use update volume command.
CatalogFiles = <yes|no> This directive defines whether or not you want the names
of the files that were saved to be put into the catalog. The default is yes. The
advantage of specifying Catalog Files=No is that you will have a significantly
smaller Catalog database. The disadvantage is that you will not be able to produce a
Catalog listing of the files backed up for each Job (this is often called Browsing).
Also, without the File entries in the catalog, you will not be able to use the
bconsole restore command nor any other command that references file entries.
AutoPrune = <yes|no> If AutoPrune is set to yes (default), Bacula will
automatically apply the Volume Retention period when new Volume is needed and no
appendable Volumes exist in the Pool. Volume pruning causes expired Jobs (older than
the Volume Retention period) to be deleted from the Catalog and permits possible
recycling of the Volume.
VolumeRetention = <time-period-specification> The VolumeRetention directive
defines the longest amount of time that Bacula will keep records associated with
the Volume in the Catalog database after the end time of each Job written to the
Volume. When this time period expires, and if AutoPrune is set to yes,
Bacula may prune (remove) Job records that are older than the specified Volume
Retention period if it is necessary to free up a Volume. Note, it is also possible
for all the Job and File records to be pruned before the Volume Retention period if
Job and File Retention periods are configured to a lower value. In that case the
Volume can then be marked Pruned and subsequently recycled prior to expiration of the
Volume Retention period.
Recycling will not occur until it is absolutely necessary to free up a volume (i.e. no other writable volume exists). All File records associated with pruned Jobs are also pruned. The time may be specified as seconds, minutes, hours, days, weeks, months, quarters, or years. The VolumeRetention is applied independently of the JobRetention and the FileRetention periods defined in the Client resource. This means that all the retention periods are applied in turn and that the shorter period is the one that effectively takes precedence. Note, that when the VolumeRetention period has been reached, and it is necessary to obtain a new volume, Bacula will prune both the Job and the File records. And the inverse is also true that if all the Job and File records that refer to a Volume were already pruned, then the Volume may be recycled regardless of its retention period. Pruning may also occur during a status dir command because it uses similar algorithms for finding the next available Volume.
It is important to know that when the VolumeRetention period expires, or all the Job and File records have been pruned that refer to a Volume, Bacula does not automatically recycle a Volume. It attempts to keep the Volume data intact as long as possible before over writing the Volume.
By defining multiple Pools with different Volume Retention periods, you may effectively have a set of tapes that is recycled weekly, another Pool of tapes that is recycled monthly and so on. However, one must keep in mind that if your VolumeRetention period is too short, it may prune the last valid Full backup, and hence until the next Full backup is done, you will not have a complete backup of your system, and in addition, the next Incremental or Differential backup will be promoted to a Full backup. As a consequence, the minimum VolumeRetention period should be at twice the interval of your Full backups. This means that if you do a Full backup once a month, the minimum Volume retention period should be two months.
The default Volume retention period is 365 days, and either the default or the value defined by this directive in the bacula-dir.conf file is the default value used when a Volume is created. Once the volume is created, changing the value in the bacula-dir.conf file will not change what is stored for the Volume. To change the value for an existing Volume you must use the update command in the Console.
To disable the VolumeRetention feature, it is possible to set the directive to 0. When disabled, the pruning will be done only on the JobRetention directive and the “ExpiresIn” information available in the list volume output is not available.
CacheRetention = <time-period-specification> The Cache Retention directive
defines the longest amount of time that bacula will keep Parts associated with the
Volume in the Storage daemon Cache directory after a successful upload to the Cloud.
When this time period expires, and if the cloud prune command is issued, Bacula
may prune (remove) Parts that are older than the specified Cache Retention period.
Note
It is also possible for all the Parts to be removed before the Cache Retention period is reached. In that case the cloud truncate command must be used.
ActionOnPurge = <Truncate> The directive ActionOnPurge = Truncate instructs
Bacula to permit the Volume to be truncated after it has been purged.
Note: The ActionOnPurge is a bit misleading since the volume is not actually truncated when it is purged, but is enabled to be truncated. The actual truncation is done with the truncate command.
To actually truncate a Volume, you must first set the ActionOnPurge to Truncate in the Pool, then you must ensure that any existing Volumes also have this information in them, by doing an update volumes comand. Finally, after the Volume has been purged, you may then truncate it. It is useful to prevent disk based volumes from consuming too much space. See below for more details of how to ensure Volumes are truncated after being purged.
First set the Pool to permit truncation.
Pool {
Name = Default
Action On Purge = Truncate
...
}
Then assuming a Volume has been Purged, you can schedule a truncate operation at the end of your CatalogBackup job like in this example:
Job {
Name = CatalogBackup
...
RunScript {
RunsWhen = After
RunsOnClient = No
Console = "truncate volume allpools storage=File"
}
}
NextPool = <pool-resource-name> This optional directive, used on copy, migration or virtual full jobs, specifies the pool to
which Job data will be written to. This directive is required in such job types/level. For additional details, see the NextPool resource Chapter.
ScratchPool = <pool-resource-name> This directive permits specifying a specific
scratch Pool to be used for the Job. This pool will replace the default scratch pool
named Scratch for volume selection. For more information about scratch pools,
see Scratch Pool section of this manual. This directive
is useful when using multiple storage devices that share the same MediaType or when
you want to dedicate volumes to a particular set of pools.
RecyclePool = <pool-resource-name> This directive defines to which pool the
Volume will be placed (moved) when it is recycled. Without this directive, a Volume
will remain in the same pool when it is recycled. With this directive, it will be
moved automatically to any existing pool during a recycle. This directive is probably
most useful when defined in the Scratch pool, so that volumes will be recycled back
into the Scratch pool. For more, see the Scratch Pool
section.
Although this directive is called RecyclePool, the Volume in question is actually moved from its current pool to the one you specify on this directive when Bacula prunes the Volume and discovers that there are no records left in the catalog and hence marks it as Purged.
Recycle = <yes|no> This directive specifies whether or not Purged Volumes may be
recycled. If it is set to yes (the default) and Bacula needs a volume but
finds none that are appendable, it will search for and recycle (reuse) Purged Volumes
(i.e. volumes with all the Jobs and Files expired and thus deleted from the Catalog).
If the Volume is recycled, all previous data written to that Volume will be overwritten.
If Recycle is set to no, the Volume will not be recycled, and hence, the data
will remain valid. If you want to reuse (re-write) the Volume, and the recycle flag
is no (0 in the catalog), you may manually set the recycle flag (update command)
for a Volume to be reused.
Note
The value defined by this directive in the bacula-dir.conf file is the default value used when a Volume is created. Once the volume is created, changing the value in the bacula-dir.conf file will not change what is stored for the Volume. To change the value for an existing Volume you must use the update command in the Console.
When all Job and File records have been pruned or purged from the catalog for a particular Volume, if that Volume is marked as Full or Used, it will then be marked as Purged. Only Volumes marked as Purged will be considered to be converted to the Recycled state if the Recycle directive is set to yes.
Recycle Oldest Volume = <yes|no> This directive instructs the Director to search
for the oldest used Volume in the Pool when another Volume is requested by the Storage
Daemon and none are available. The catalog is then pruned respecting the retention
periods of all Files and Jobs written to this Volume. If all Jobs are pruned (i.e. the
volume is Purged), then the Volume is recycled and will be used as the next Volume to be
written. This directive respects any Job, File, or Volume retention periods that you may
have specified, and as such it is much better to use this directive than the
PurgeOldestVolume.
This directive can be useful if you have a fixed number of Volumes in the Pool and you want to cycle through them and you have specified the correct retention periods.
However, if you use this directive and have only one Volume in the Pool, you will immediately recycle your Volume if you fill it and Bacula needs another one. Thus your backup will be totally invalid. Please use this directive with care. The default is no.
Recycle Current Volume = <yes|no> If Bacula needs a new Volume, this directive
instructs to Prune the volume respecting the Job and File retention periods. If all Jobs
are pruned (i.e. the volume is Purged), then the Volume is recycled and will be used as
the next Volume to be written. This directive respects any Job, File, or Volume
retention periods that you may have specified, and thus it is much better to use it
rather than the Purge Oldest Volume directive.
This directive can be useful if you have a fixed number of Volumes in the Pool, you want to cycle through them, and you have specified retention periods that prune Volumes before you have cycled through the Volume in the Pool.
However, if you use this directive and have only one Volume in the Pool, you will immediately recycle your Volume if you fill it and Bacula needs another one. Thus your backup will be totally invalid. Please use this directive with care. The default is no.
Purge Oldest Volume = <yes|no> This directive instructs the Director to search
for the oldest used Volume in the Pool when another Volume is requested by the
Storage Daemon and none are available. The catalog is then purged irrespective
of retention periods of all Files and Jobs written to this Volume. The Volume is
then recycled and will be used as the next Volume to be written. This directive
overrides any Job, File, or Volume retention periods that you may have specified.
This directive can be useful if you have a fixed number of Volumes in the Pool and you want to cycle through them and reusing the oldest one when all Volumes are full, but you don’t want to worry about setting proper retention periods. However, by using this option you risk losing valuable data.
Be aware that PurgeOldestVolume disregards all retention periods. If you have only a single Volume defined and you turn this variable on, that Volume will always be immediately overwritten when it fills. So at a minimum, ensure that you have a decent number of Volumes in your Pool before running any jobs. If you want retention periods to apply do not use this directive. To specify a retention period, use the VolumeRetention directive (see above).
We highly recommend against using this directive, because it is sure that some day, Bacula will recycle a Volume that contains current data. The default is no.
FileRetention = <time-period-specification> The File Retention directive
defines the length of time that Bacula will keep File records in the Catalog
database after the End time of the Job corresponding to the File records.
This directive takes precedence over Client directives of the same name. For example, you can decide to increase Retention times for Archive or OffSite Pool.
Note, this affects only records in the catalog database. It does not affect your archive backups.
For more information, see Client documentation about FileRetention
JobRetention = <time-period-specification> The Job Retention directive defines
the length of time that Bacula will keep Job records in the Catalog database
after the Job End time. As with the other retention periods, this affects only
records in the catalog and not data in your archive backup.
This directive takes precedence over Client directives of the same name. For example, you can decide to increase Retention times for Archive or OffSite Pool.
For more information, see Client side documentation JobRetention
CleaningPrefix = <string> This directive defines a prefix string, which if it
matches the beginning of a Volume name during labeling of a Volume, the Volume will
be defined with the VolStatus set to and thus Bacula will never attempt to use
this tape. This is primarily for use with autochangers that accept barcodes where
the convention is that barcodes beginning with CLN are treated as cleaning tapes.
Bacula supports ANSI or IBM tape labels as long as you enable it. In fact, with the proper configuration, you can force Bacula to require ANSI or IBM labels. Bacula can create an ANSI or IBM label, but if Check Labels is enabled (see below), Bacula will look for an existing label, and if it is found, it will keep the label. Consequently, you can label the tapes with programs other than Bacula, and Bacula will recognize and support them. Even though Bacula will recognize and write ANSI and IBM labels, it always writes its own tape labels as well. When using ANSI or IBM tape labeling, you must restrict your Volume names to a maximum of six characters. If you have labeled your Volumes outside of Bacula, then the ANSI/IBM label will be recognized by Bacula only if you have created the HDR1 label with BACULA.DATA in the Filename field (starting with character 5). If Bacula writes the labels, it will use this information to recognize the tape as a Bacula tape. This allows ANSI/IBM labeled tapes to be used at sites with multiple machines and multiple backup pro- grams.
LabelType = ANSI | IBM | Bacula This directive is implemented in the Director
Pool resource and in the SD Device resource. If it is specified in the SD Device
resource, it will take precedence over the value passed from the Director to the
SD. The default is Label Type = Bacula.
LabelFormat = <format> This directive specifies the format of the labels
contained in this pool. The format directive is used as a sort of template to create
new Volume names during automatic Volume labeling.
The should be specified in double quotes, and consists of letters, numbers and the special characters hyphen (-), underscore (_), colon (:), and period (.), which are the legal characters for a Volume name. The should be enclosed in double quotes (“).
In addition, the format may contain a number of variable expansion characters which will be expanded by a complex algorithm allowing you to create Volume names of many different formats. In all cases, the expansion process must resolve to the set of characters noted above that are legal Volume names. Generally, these variable expansion characters begin with a dollar sign ($) or a left bracket ([). If you specify variable expansion characters, you should always enclose the format with double quote characters (”). For more details on variable expansion, see the Variable Expansion chapter.
If no variable expansion characters are found in the string, the Volume name will be formed from the string appended with the a unique number that increases. If you do not remove volumes from the pool, this number should be the number of volumes plus one, but this is not guaranteed. The unique number will be edited as four digits with leading zeros. For example, with a LabelFormat=”Vol-”, the first volumes will be named Vol-0001, Vol-0002, etc.
With the exception of Job specific variables, you can test your LabelFormat by using the var command described in the Bacula Enterprise Console manual.
Label Format=":math:`{Level}_`\ Type\_\ :math:`{Client}_`\ Year-:math:`{Month:p/2/0/r}-`\ Day:p/2/0/r"
Once defined, the name of the volume cannot be changed. When the volume is recycled, the volume can be used by an other Job at an other time, and possibly from an other Pool. In the example above, the volume defined with such name is probably not supposed to be recycled or reused.
In almost all cases, you should enclose the format specification (part after the equal sign) in double quotes.
In order for a Pool to be used during a Backup Job, the Pool must have at least one Volume associated with it. Volumes are created for a Pool using the label or the add commands in the Bacula bconsole program. In addition to adding Volumes to the Pool (i.e. putting the Volume names in the Catalog database), the physical Volume must be labeled with a valid * Bacula* software volume label before will accept the Volume. This will be automatically done if you use the label command. Bacula can automatically label Volumes if instructed to do so, but this feature is not yet fully implemented.
The following is an example of a valid Pool resource definition:
Pool {
Name = Default
Pool Type = Backup
}
The Scratch Pool
In general, you can give your Pools any name you wish, but there is one important restriction: the Pool named Scratch, if it exists behaves like a scratch pool of Volumes in that when Bacula needs a new Volume for writing and it cannot find one, it will look in the Scratch pool, and if it finds an available Volume, it will move it out of the Scratch pool into the Pool currently being used by the job.
See also
Go back to:
Go to:
Go back to the Director Resource Types page.
Go back to the Technical Reference for Director.