keep File records in the Catalog database after the End time of the
Job corresponding to the File records.
When this time period expires, and if
- {\bf AutoPrune} is set to {\bf yes} Bacula will prune (remove) File records
- that are older than the specified File Retention period. Note, this affects
- only records in the catalog database. It does not affect your archive
- backups.
-
- File records may actually be retained for a shorter period than you specify
- on this directive if you specify either a shorter {\bf Job Retention} or a
- shorter {\bf Volume Retention} period. The shortest retention period of the
- three takes precedence. The time may be expressed in seconds, minutes,
- hours, days, weeks, months, quarters, or years. See the
- \ilink{Configuration chapter}{Time} of this manual for
- additional details of time specification.
+ {\bf AutoPrune} is set to {\bf yes} Bacula will prune (remove) File
+ records that are older than the specified File Retention period. Note,
+ this affects only records in the catalog database. It does not affect
+ your archive backups.
+
+ File records may actually be retained for a shorter period than you
+ specify on this directive if you specify either a shorter {\bf Job
+ Retention} or a shorter {\bf Volume Retention} period. The shortest
+ retention period of the three takes precedence. The time may be
+ expressed in seconds, minutes, hours, days, weeks, months, quarters, or
+ years. See the \ilink{Configuration chapter}{Time} of this manual for
+ additional details of time specification.
The default is 60 days.
\item [Volume Retention = \lt{}time-period-specification\gt{}]
\index[dir]{Volume Retention}
\index[dir]{Directive!Volume Retention}
- The Volume Retention directive defines the length of time that {\bf
- 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 {\bf AutoPrune} is set to
- {\bf 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. Recycling will not occur until it is absolutely necessary to
+ The Volume Retention directive defines the longest amount of time that
+ {\bf 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 {\bf AutoPrune} is set to {\bf 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 is reached. In that case the Volume can
+ then be marked Pruned and subsequently recycled prior to expiration of
+ the Volume Retention period.
+
+\smallskip
+ 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 {\bf Volume Retention} is
applied independently of the {\bf Job Retention} and the {\bf File
Retention} periods defined in the Client resource. This means that all
- the retentions periods are applied in turn and that the shorter period
+ the retention periods are applied in turn and that the shorter period
is the one that effectively takes precedence. Note, that when the {\bf
Volume Retention} period has been reached, and it is necessary to obtain
- a new volume, Bacula will prune both the Job and the File records. This
- pruning could also occur during a {\bf status dir} command because it
- uses similar algorithms for finding the next available Volume.
+ 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 are pruned, then the Volume may be pruned and recycled
+ regardless of its retention period. Pruning may also occur during a
+ {\bf status dir} command because it uses similar algorithms for finding
+ the next available Volume.
It is important to know that when the Volume Retention 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.
The above three directives are all you need assuming that you fill
each of your Volumes then wait the Volume Retention period before
-reusing them. If you want Bacula to stop using a Volume and recycle
+reusing them, providing there is some non-pruned Jobs or Files on the
+Volume.
+
+If you want Bacula to stop using a Volume and recycle
it before it is full, you will need to use one or more additional
directives such as:
+
\begin{itemize}
\item Use Volume Once = yes
\item Volume Use Duration = ttt
\item Maximum Volume Jobs = nnn
\item Maximum Volume Bytes = mmm
\end{itemize}
+
Please see below and
the \ilink{Basic Volume Management}{DiskChapter} chapter
of this manual for more complete examples.
Volume Status is {\bf Purged}. At that point, it will choose the oldest
purged volume and recycle it.
-If there are no volumes with Status {\bf Purged}, then
-the recycling occurs in two steps:
+If there are no volumes with Status {\bf Purged}, then the recycling occurs
+in two steps:
+
+\smallskip
The first is that the Catalog for a Volume must be pruned of all Jobs (i.e.
-Purged). Files contained on that Volume, and the second step is the actual
-recycling of the Volume. Only Volumes marked {\bf Full} or {\bf Used} will
-be considerd for pruning. The Volume will be purged if the VolumeRetention
-period has expired. When a Volume is marked as Purged, it means that no
-Catalog records reference that Volume, and the Volume can be recycled.
-Until recycling actually occurs, the Volume data remains intact. If no
-Volumes can be found for recycling for any of the reasons stated above,
-Bacula will request operator intervention (i.e. it will ask you to label a
-new volume).
-
-A key point mentioned above, that can be a source of frustration, is that Bacula
-will only recycle purged Volumes if there is no other appendable Volume
-available, otherwise, it will always write to an appendable Volume before
-recycling even if there are Volume marked as Purged. This preserves your data
-as long as possible. So, if you wish to "force" Bacula to use a purged
-Volume, you must first ensure that no other Volume in the Pool is marked {\bf
-Append}. If necessary, you can manually set a volume to {\bf Full}. The reason
-for this is that Bacula wants to preserve the data on your old tapes (even
-though purged from the catalog) as long as absolutely possible before
-overwriting it. There are also a number of directives such as
+Purged) and Files contained on that Volume.
+
+\smallskip
+The second step is the actual recycling of the Volume. Only Volumes marked
+{\bf Full} or {\bf Used} will be considerd for pruning. The Volume will be
+purged if the VolumeRetention period has expired. When a Volume is marked
+as Purged, it means that no Catalog records reference that Volume, and the
+Volume can be recycled and reused even though the Volume Retention period
+has not expired. Until recycling actually occurs, the Volume data remains
+intact. If no Volumes can be found for recycling for any of the reasons
+stated above, Bacula will request operator intervention (i.e. it will ask
+you to label a new volume).
+
+A key point mentioned above, that can be a source of frustration, is that
+Bacula will only recycle purged Volumes if there is no other appendable
+Volume available, otherwise, it will always write to an appendable Volume
+before recycling even if there are Volume marked as Purged. This preserves
+your data as long as possible. So, if you wish to "force" Bacula to use a
+purged Volume, you must first ensure that no other Volume in the Pool is
+marked {\bf Append}. If necessary, you can manually set a volume to {\bf
+Full}. The reason for this is that Bacula wants to preserve the data on
+your old tapes (even though purged from the catalog) as long as absolutely
+possible before overwriting it. There are also a number of directives such
+as
{\bf Volume Use Duration} that will automatically mark a volume as {\bf
Used} and thus no longer appendable.
something. However, the catalog will grow larger and larger as time goes
on, and eventually it can become unacceptably large.
-Bacula's process for removing entries from the catalog is called Pruning. The
-default is Automatic Pruning, which means that once an entry reaches a certain
-age (e.g. 30 days old) it is removed from the catalog. Note that Job records
-that are required for current restore won't be removed automatically, and File
-records are needed for VirtualFull and Accurate backups. Once a job has been
-pruned, you can still restore it from the backup tape, but one additional step
-is required: scanning the volume with bscan. The alternative to Automatic
-Pruning is Manual Pruning, in which you explicitly tell Bacula to erase the
-catalog entries for a volume. You'd usually do this when you want to reuse a
-Bacula volume, because there's no point in keeping a list of files that USED TO
-BE on a tape. Or, if the catalog is starting to get too big, you could prune
-the oldest jobs to save space. Manual pruning is done with the
+Bacula's process for removing entries from the catalog is called Pruning.
+The default is Automatic Pruning, which means that once a Job record
+reaches a certain age (e.g. 30 days old) and a pruning occurs, it will be
+removed from the catalog. Note that Job records that are required for
+current restore won't be removed automatically, and File records are needed
+for VirtualFull and Accurate backups. Once a job has been pruned, you can
+still restore it from the backup Volume, provided that the Volume has not
+been recycled, but one additional step is required: scanning the volume
+with bscan. The alternative to Automatic Pruning is Manual Pruning, in
+which you explicitly tell Bacula to erase the catalog entries for a volume.
+You'd usually do this when you want to reuse a Bacula volume, because
+there's no point in keeping a list of files that USED TO BE on a volume.
+Or, if the catalog is starting to get too big, you could prune the oldest
+jobs to save space. Manual pruning is done with the
\borgxrlink{prune}{ManualPruning}{console}{command} in the \consoleman{}
(thanks to Bryce Denney for the above explanation).
\index[general]{Pruning Directives }
\index[general]{Directives!Pruning }
-There are three pruning durations. All apply to catalog database records and
-not to the actual data in a Volume. The pruning (or retention) durations are
-for: Volumes (Media records), Jobs (Job records), and Files (File records).
-The durations inter-depend a bit because if Bacula prunes a Volume, it
-automatically removes all the Job records, and all the File records. Also when
-a Job record is pruned, all the File records for that Job are also pruned
-(deleted) from the catalog.
+There are three pruning durations. All apply to catalog database records
+and not to the actual data in a Volume. The pruning (or retention)
+durations are for: Volumes (Media records), Jobs (Job records), and Files
+(File records). The durations inter-depend a bit because if Bacula prunes
+a Volume, it automatically removes all the Job records, and all the File
+records. Also when a Job record is pruned, all the File records for that
+Job are also pruned (deleted) from the catalog.
Having the File records in the database means that you can examine all the
files backed up for a particular Job. They take the most space in the catalog
\index[console]{Volume Retention}
The Volume Retention record defines the length of time that Bacula will
guarantee that the Volume is not reused counting from the time the last
- job stored on the Volume terminated. A key point is that this time
+ job stored on the Volume terminated, providing that all the File records
+ on the Volume have not been pruned. A key point is that this time
period is not even considered as long at the Volume remains appendable.
The Volume Retention period count down begins only when the Append
status has been changed to some othe status (Full, Used, Purged, ...).
+ Note, when all the File records have been removed that are on the
+ Volume, the Volume will marked Purged (i.e. it has no more valid
+ Files stored on it), and the Volume may be recycled even if the Volume
+ Retention period has not expired.
When this time period expires, and if {\bf AutoPrune} is set to {\bf
yes}, and a new Volume is needed, but no appendable Volume is available,
Bacula will prune (remove) Job records that are older than the specified
- Volume Retention period.
+ Volume Retention period even if the Job or File retention has not been
+ reached.
The Volume Retention period takes precedence over any Job Retention
period you have specified in the Client resource. It should also be
with the lowest MediaId is chosen).
\item Try recycling any purged Volumes.
\item Prune volumes applying Volume retention period (Volumes with VolStatus
- Full, Used, or Append are pruned). Note, even if all the File and Job
- records are pruned from a Volume, the Volume will not be marked Purged
- until the Volume retention period expires.
+ Full, Used, or Append are pruned). Note, when all the File and Job
+ records are pruned from a Volume, the Volume may be marked Purged
+ prior to the expiration of the Volume retention period.
\item Search the Pool for a Volume with VolStatus=Purged
\item If a Pool named "Scratch" exists, search for a Volume and if found
move it to the current Pool for the Job and use it. Note, when
\item If we were looking for Volumes in the Autochanger, go back to
step 2 above, but this time, look for any Volume whether or not
it is in the Autochanger.
-\item Attempt to create a new Volume if automatic labeling enabled
- If Python is enabled, a Python NewVolume event is generated before
- the Label Format directve is used. If the maximum number of Volumes
+\item Attempt to create a new Volume if automatic labeling is enabled.
+ However, if the maximum number of Volumes
specified for the pool is reached, a new Volume will not be created.
\item Prune the oldest Volume if RecycleOldestVolume=yes (the Volume with the
oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used,
\end{verbatim}
\normalsize
-all the volumes are marked as recyclable, and the last Volume, {\bf File0007}
-has been purged, so it may be immediately recycled. The other volumes are all
-marked recyclable and when their Volume Retention period (14400 seconds or four
-hours) expires, they will be eligible for pruning, and possibly recycling.
-Even though Volume {\bf File0007} has been purged, all the data on the Volume
-is still recoverable. A purged Volume simply means that there are no entries
-in the Catalog. Even if the Volume Status is changed to {\bf Recycle}, the
-data on the Volume will be recoverable. The data is lost only when the Volume
-is re-labeled and re-written.
+all the volumes are marked as recyclable, and the last Volume, {\bf
+File0007} has been purged, so it may be immediately recycled. The other
+volumes are all marked recyclable and when their Volume Retention period
+(14400 seconds or four hours) expires, they will be eligible for pruning,
+and possibly recycling. Even though Volume {\bf File0007} has been purged,
+all the data on the Volume is still recoverable. A purged Volume simply
+means that there are no entries in the Catalog. Even if the Volume Status
+is changed to {\bf Recycle}, the data on the Volume will be recoverable.
+The data is lost only when the Volume is re-labeled and re-written.
To modify Volume {\bf File0001} so that it cannot be recycled, you use the
{\bf update volume pool=File} command in the console program, or simply {\bf
\index[general]{Making Bacula Use a Single Tape}
Most people will want Bacula to fill a tape and when it is full, a new tape
-will be mounted, and so on. However, as an extreme example, it is possible for
-Bacula to write on a single tape, and every night to rewrite it. To get this
-to work, you must do two things: first, set the VolumeRetention to less than
-your save period (one day), and the second item is to make Bacula mark the
-tape as full after using it once. This is done using {\bf UseVolumeOnce =
-yes}. If this latter record is not used and the tape is not full after the
-first time it is written, Bacula will simply append to the tape and eventually
-request another volume. Using the tape only once, forces the tape to be marked
+will be mounted, and so on. However, as an extreme example, it is possible
+for Bacula to write on a single tape, and every night to rewrite it. To
+get this to work, you must do two things: first, set the VolumeRetention to
+less than your save period (one day), and the second item is to make Bacula
+mark the tape as full after using it once. This is done using {\bf
+UseVolumeOnce = yes}. If this latter record is not used and the tape is
+not full after the first time it is written, Bacula will simply append to
+the tape and eventually request another volume. Using the tape only once,
+forces the tape to be marked
{\bf Full} after each use, and the next time {\bf Bacula} runs, it will
recycle the tape.
projects / bacula / docs / commitdiff