--- /dev/null
+%%
+%%
+
+\chapter{Automatic Volume Recycling}
+\label{RecyclingChapter}
+\index[general]{Recycling!Automatic Volume }
+\index[general]{Automatic Volume Recycling }
+
+By default, once Bacula starts writing a Volume, it can append to the
+volume, but it will not overwrite the existing data thus destroying it.
+However when Bacula {\bf recycles} a Volume, the Volume becomes available
+for being reused, and Bacula can at some later time overwrite the previous
+contents of that Volume. Thus all previous data will be lost. If the
+Volume is a tape, the tape will be rewritten from the beginning. If the
+Volume is a disk file, the file will be truncated before being rewritten.
+
+You may not want Bacula to automatically recycle (reuse) tapes. This would
+require a large number of tapes though, and in such a case, it is possible
+to manually recycle tapes. For more on manual recycling, see the section
+entitled \ilink{ Manually Recycling Volumes}{manualrecycling} below in this
+chapter.
+
+Most people prefer to have a Pool of tapes that are used for daily backups and
+recycled once a week, another Pool of tapes that are used for Full backups
+once a week and recycled monthly, and finally a Pool of tapes that are used
+once a month and recycled after a year or two. With a scheme like this, the
+number of tapes in your pool or pools remains constant.
+
+By properly defining your Volume Pools with appropriate Retention periods,
+Bacula can manage the recycling (such as defined above) automatically.
+
+Automatic recycling of Volumes is controlled by four records in the {\bf
+Pool} resource definition in the Director's configuration file. These four
+records are:
+
+\begin{itemize}
+\item AutoPrune = yes
+\item VolumeRetention = \lt{}time\gt{}
+\item Recycle = yes
+\item RecyclePool = \lt{}APool\gt{} (\textit{This require bacula 2.1.4 or greater})
+\end{itemize}
+
+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
+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.
+
+Automatic recycling of Volumes is performed by Bacula only when it wants a
+new Volume and no appendable Volumes are available in the Pool. It will then
+search the Pool for any Volumes with the {\bf Recycle} flag set and the
+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:
+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
+{\bf Volume Use Duration} that will automatically mark a volume as {\bf
+Used} and thus no longer appendable.
+
+\label{AutoPruning}
+\section{Automatic Pruning}
+\index[general]{Automatic Pruning}
+\index[general]{Pruning!Automatic}
+
+As Bacula writes files to tape, it keeps a list of files, jobs, and volumes
+in a database called the catalog. Among other things, the database helps
+Bacula to decide which files to back up in an incremental or differential
+backup, and helps you locate files on past backups when you want to restore
+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. 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 \ilink{ prune command}{ManualPruning} in
+the console. (thanks to Bryce Denney for the above explanation).
+
+\section{Pruning Directives}
+\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.
+
+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
+(probably 90-95\% of the total). When the File records are pruned, the Job
+records can remain, and you can still examine what Jobs ran, but not the
+details of the Files backed up. In addition, without the File records, you
+cannot use the Console restore command to restore the files.
+
+When a Job record is pruned, the Volume (Media record) for that Job can still
+remain in the database, and if you do a "list volumes", you will see the
+volume information, but the Job records (and its File records) will no longer
+be available.
+
+In each case, pruning removes information about where older files are, but it
+also prevents the catalog from growing to be too large. You choose the
+retention periods in function of how many files you are backing up and the
+time periods you want to keep those records online, and the size of the
+database. You can always re-insert the records (with 98\% of the original data)
+by using "bscan" to scan in a whole Volume or any part of the volume that
+you want.
+
+By setting {\bf AutoPrune} to {\bf yes} you will permit {\bf Bacula} to
+automatically prune all Volumes in the Pool when a Job needs another Volume.
+Volume pruning means removing records from the catalog. It does not shrink the
+size of the Volume or affect the Volume data until the Volume gets
+overwritten. When a Job requests another volume and there are no Volumes with
+Volume Status {\bf Append} available, Bacula will begin volume pruning. This
+means that all Jobs that are older than the {\bf VolumeRetention} period will
+be pruned from every Volume that has Volume Status {\bf Full} or {\bf Used}
+and has Recycle set to {\bf yes}. Pruning consists of deleting the
+corresponding Job, File, and JobMedia records from the catalog database. No
+change to the physical data on the Volume occurs during the pruning process.
+When all files are pruned from a Volume (i.e. no records in the catalog), the
+Volume will be marked as {\bf Purged} implying that no Jobs remain on the
+volume. The Pool records that control the pruning are described below.
+
+\begin{description}
+
+\item [AutoPrune = \lt{}yes|no\gt{}]
+ \index[console]{AutoPrune }
+ If AutoPrune is set to {\bf yes} (default), Bacula
+ will automatically apply the Volume retention period when running a Job and
+ it needs a new Volume but no appendable volumes are available. At that point,
+ Bacula will prune all Volumes that can be pruned (i.e. AutoPrune set) in an
+ attempt to find a usable volume. If during the autoprune, all files are
+ pruned from the Volume, it will be marked with VolStatus {\bf Purged}. The
+ default is {\bf yes}. Note, that although the File and Job records may be
+ pruned from the catalog, a Volume will be marked Purged (and hence
+ ready for recycling) if the Volume status is Append, Full, Used, or Error.
+ If the Volume has another status, such as Archive, Read-Only, Disabled,
+ Busy, or Cleaning, the Volume status will not be changed to Purged.
+
+\item [Volume Retention = \lt{}time-period-specification\gt{}]
+ \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
+ 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, ...).
+
+ 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.
+
+ The Volume Retention period takes precedence over any Job Retention
+ period you have specified in the Client resource. It should also be
+ noted, that the Volume Retention period is obtained by reading the
+ Catalog Database Media record rather than the Pool resource record.
+ This means that if you change the VolumeRetention in the Pool resource
+ record, you must ensure that the corresponding change is made in the
+ catalog by using the {\bf update pool} command. Doing so will insure
+ that any new Volumes will be created with the changed Volume Retention
+ period. Any existing Volumes will have their own copy of the Volume
+ Retention period that can only be changed on a Volume by Volume basis
+ using the {\bf update volume} command.
+
+ When all file catalog entries are removed from the volume, its VolStatus is
+ set to {\bf Purged}. The files remain physically on the Volume until the
+ volume is overwritten.
+
+ Retention periods are specified in seconds, minutes, hours, days, weeks,
+ months, quarters, or years on the record. See the
+ \ilink{Configuration chapter}{Time} of this manual for
+ additional details of time specification.
+
+The default is 1 year.
+% TODO: if that is the format, should it be in quotes? decide on a style
+
+\item [Recycle = \lt{}yes|no\gt{}]
+ \index[fd]{Recycle }
+ This statement tells Bacula whether or not the particular Volume can be
+ recycled (i.e. rewritten). If Recycle is set to {\bf no} (the
+ default), then even if Bacula prunes all the Jobs on the volume and it
+ is marked {\bf Purged}, it will not consider the tape for recycling. If
+ Recycle is set to {\bf yes} and all Jobs have been pruned, the volume
+ status will be set to {\bf Purged} and the volume may then be reused
+ when another volume is needed. If the volume is reused, it is relabeled
+ with the same Volume Name, however all previous data will be lost.
+ \end{description}
+
+ It is also possible to "force" pruning of all Volumes in the Pool
+ associated with a Job by adding {\bf Prune Files = yes} to the Job resource.
+
+\label{Recycling}
+\label{RecyclingAlgorithm}
+\section{Recycling Algorithm}
+\index[general]{Algorithm!Recycling }
+\index[general]{Recycling Algorithm }
+
+After all Volumes of a Pool have been pruned (as mentioned above, this happens
+when a Job needs a new Volume and no appendable Volumes are available), Bacula
+will look for the oldest Volume that is Purged (all Jobs and Files expired),
+and if the {\bf Recycle} flag is on (Recycle=yes) for that Volume, Bacula will
+relabel it and write new data on it.
+
+As mentioned above, there are two key points for getting a Volume
+to be recycled. First, the Volume must no longer be marked Append (there
+are a number of directives to automatically make this change), and second
+since the last write on the Volume, one or more of the Retention periods
+must have expired so that there are no more catalog backup job records
+that reference that Volume. Once both those conditions are satisfied,
+the volume can be marked Purged and hence recycled.
+
+The full algorithm that Bacula uses when it needs a new Volume is:
+\index[general]{New Volume Algorithm}
+\index[general]{Algorithm!New Volume}
+
+The algorithm described below assumes that AutoPrune is enabled,
+that Recycling is turned on, and that you have defined
+appropriate Retention periods, or used the defaults for all these
+items.
+
+\begin{itemize}
+\item If the request is for an Autochanger device, look only
+ for Volumes in the Autochanger (i.e. with InChanger set and that have
+ the correct Storage device).
+\item Search the Pool for a Volume with VolStatus=Append (if there is more
+ than one, the Volume with the oldest date last written is chosen. If
+ two have the same date then the one with the lowest MediaId is chosen).
+\item Search the Pool for a Volume with VolStatus=Recycle and the InChanger
+ flag is set true (if there is more than one, the Volume with the oldest
+ date last written is chosen. If two have the same date then the one
+ 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.
+\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
+ the Scratch Volume is moved into the current Pool, the basic
+ Pool defaults are applied as if it is a newly labeled Volume
+ (equivalent to an {\bf update volume from pool} command).
+\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
+ 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,
+ or Append is chosen). This record ensures that all retention periods are
+ properly respected.
+\item Purge the oldest Volume if PurgeOldestVolume=yes (the Volume with the
+ oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used,
+ or Append is chosen). We strongly recommend against the use of {\bf
+ PurgeOldestVolume} as it can quite easily lead to loss of current backup
+ data.
+\item Give up and ask operator.
+\end{itemize}
+
+The above occurs when Bacula has finished writing a Volume or when no Volume
+is present in the drive.
+
+On the other hand, if you have inserted a different Volume after the last job,
+and Bacula recognizes the Volume as valid, it will request authorization from
+the Director to use this Volume. In this case, if you have set {\bf Recycle
+Current Volume = yes} and the Volume is marked as Used or Full, Bacula will
+prune the volume and if all jobs were removed during the pruning (respecting
+the retention periods), the Volume will be recycled and used.
+
+The recycling algorithm in this case is:
+\begin{itemize}
+\item If the VolStatus is {\bf Append} or {\bf Recycle}
+ is set, the volume will be used.
+\item If {\bf Recycle Current Volume} is set and the volume is marked {\bf
+ Full} or {\bf Used}, Bacula will prune the volume (applying the retention
+ period). If all Jobs are pruned from the volume, it will be recycled.
+\end{itemize}
+
+This permits users to manually change the Volume every day and load tapes in
+an order different from what is in the catalog, and if the volume does not
+contain a current copy of your backup data, it will be used.
+
+A few points from Alan Brown to keep in mind:
+
+\begin{enumerate}
+\item If a pool doesn't have maximum volumes defined then Bacula will prefer to
+ demand new volumes over forcibly purging older volumes.
+
+\item If volumes become free through pruning and the Volume retention period has
+ expired, then they get marked as "purged" and are immediately available for
+ recycling - these will be used in preference to creating new volumes.
+
+\item If the Job, File, and Volume retention periods are different, then
+ it's common to see a tape with no files or jobs listed in the database,
+ but which is still not marked as "purged".
+\end{enumerate}
+
+
+\section{Recycle Status}
+\index[general]{Status!Recycle }
+\index[general]{Recycle Status }
+
+Each Volume inherits the Recycle status (yes or no) from the Pool resource
+record when the Media record is created (normally when the Volume is labeled).
+This Recycle status is stored in the Media record of the Catalog. Using
+the Console program, you may subsequently change the Recycle status for each
+Volume. For example in the following output from {\bf list volumes}:
+
+\footnotesize
+\begin{verbatim}
++----------+-------+--------+---------+------------+--------+-----+
+| VolumeNa | Media | VolSta | VolByte | LastWritte | VolRet | Rec |
++----------+-------+--------+---------+------------+--------+-----+
+| File0001 | File | Full | 4190055 | 2002-05-25 | 14400 | 1 |
+| File0002 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0003 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0004 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0005 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0006 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0007 | File | Purged | 1896466 | 2002-05-26 | 14400 | 1 |
++----------+-------+--------+---------+------------+--------+-----+
+\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.
+
+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
+update} and Bacula will prompt you for the information.
+
+\footnotesize
+\begin{verbatim}
++----------+------+-------+---------+-------------+-------+-----+
+| VolumeNa | Media| VolSta| VolByte | LastWritten | VolRet| Rec |
++----------+------+-------+---------+-------------+-------+-----+
+| File0001 | File | Full | 4190055 | 2002-05-25 | 14400 | 0 |
+| File0002 | File | Full | 1897236 | 2002-05-26 | 14400 | 1 |
+| File0003 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0004 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0005 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0006 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 |
+| File0007 | File | Purged| 1896466 | 2002-05-26 | 14400 | 1 |
++----------+------+-------+---------+-------------+-------+-----+
+\end{verbatim}
+\normalsize
+
+In this case, {\bf File0001} will never be automatically recycled. The same
+effect can be achieved by setting the Volume Status to Read-Only.
+
+As you have noted, the Volume Status (VolStatus) column in the
+catalog database contains the current status of the Volume, which
+is normally maintained automatically by Bacula. To give you an
+idea of some of the values it can take during the life cycle of
+a Volume, here is a picture created by Arno Lehmann:
+
+\footnotesize
+\begin{verbatim}
+A typical volume life cycle is like this:
+
+ because job count or size limit exceeded
+ Append ----------------------------------------> Used
+ ^ |
+ | First Job writes to Retention time passed |
+ | the volume and recycling takes |
+ | place |
+ | v
+ Recycled <-------------------------------------- Purged
+ Volume is selected for reuse
+
+\end{verbatim}
+\normalsize
+
+
+\section{Making Bacula Use a Single Tape}
+\label{singletape}
+\index[general]{Tape!Making Bacula Use a Single}
+\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
+{\bf Full} after each use, and the next time {\bf Bacula} runs, it will
+recycle the tape.
+
+An example Pool resource that does this is:
+
+\footnotesize
+\begin{verbatim}
+Pool {
+ Name = DDS-4
+ Use Volume Once = yes
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 12h # expire after 12 hours
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+\section{Daily, Weekly, Monthly Tape Usage Example}
+\label{usageexample}
+\index[general]{Daily, Weekly, Monthly Tape Usage Example }
+\index[general]{Example!Daily Weekly Monthly Tape Usage }
+
+This example is meant to show you how one could define a fixed set of volumes
+that Bacula will rotate through on a regular schedule. There are an infinite
+number of such schemes, all of which have various advantages and
+disadvantages.
+
+We start with the following assumptions:
+
+\begin{itemize}
+\item A single tape has more than enough capacity to do a full save.
+\item There are ten tapes that are used on a daily basis for incremental
+ backups. They are prelabeled Daily1 ... Daily10.
+\item There are four tapes that are used on a weekly basis for full backups.
+ They are labeled Week1 ... Week4.
+\item There are 12 tapes that are used on a monthly basis for full backups.
+ They are numbered Month1 ... Month12
+\item A full backup is done every Saturday evening (tape inserted Friday
+ evening before leaving work).
+\item No backups are done over the weekend (this is easy to change).
+\item The first Friday of each month, a Monthly tape is used for the Full
+ backup.
+\item Incremental backups are done Monday - Friday (actually Tue-Fri
+ mornings).
+% TODO: why this "actually"? does this need to be explained?
+ \end{itemize}
+
+We start the system by doing a Full save to one of the weekly volumes or one
+of the monthly volumes. The next morning, we remove the tape and insert a
+Daily tape. Friday evening, we remove the Daily tape and insert the next tape
+in the Weekly series. Monday, we remove the Weekly tape and re-insert the
+Daily tape. On the first Friday of the next month, we insert the next Monthly
+tape in the series rather than a Weekly tape, then continue. When a Daily tape
+finally fills up, {\bf Bacula} will request the next one in the series, and
+the next day when you notice the email message, you will mount it and {\bf
+Bacula} will finish the unfinished incremental backup.
+
+What does this give? Well, at any point, you will have the last complete
+Full save plus several Incremental saves. For any given file you want to
+recover (or your whole system), you will have a copy of that file every day
+for at least the last 14 days. For older versions, you will have at least three
+and probably four Friday full saves of that file, and going back further, you
+will have a copy of that file made on the beginning of the month for at least
+a year.
+
+So you have copies of any file (or your whole system) for at least a year, but
+as you go back in time, the time between copies increases from daily to weekly
+to monthly.
+
+What would the Bacula configuration look like to implement such a scheme?
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "NightlySave"
+ Run = Level=Full Pool=Monthly 1st sat at 03:05
+ Run = Level=Full Pool=Weekly 2nd-5th sat at 03:05
+ Run = Level=Incremental Pool=Daily tue-fri at 03:05
+}
+Job {
+ Name = "NightlySave"
+ Type = Backup
+ Level = Full
+ Client = LocalMachine
+ FileSet = "File Set"
+ Messages = Standard
+ Storage = DDS-4
+ Pool = Daily
+ Schedule = "NightlySave"
+}
+# Definition of file storage device
+Storage {
+ Name = DDS-4
+ Address = localhost
+ SDPort = 9103
+ Password = XXXXXXXXXXXXX
+ Device = FileStorage
+ Media Type = 8mm
+}
+FileSet {
+ Name = "File Set"
+ Include = signature=MD5 {
+ fffffffffffffffff
+ }
+ Exclude = { *.o }
+}
+Pool {
+ Name = Daily
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 10d # recycle in 10 days
+ Maximum Volumes = 10
+ Recycle = yes
+}
+Pool {
+ Name = Weekly
+ Use Volume Once = yes
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 30d # recycle in 30 days (default)
+ Recycle = yes
+}
+Pool {
+ Name = Monthly
+ Use Volume Once = yes
+ Pool Type = Backup
+ AutoPrune = yes
+ VolumeRetention = 365d # recycle in 1 year
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+\section{ Automatic Pruning and Recycling Example}
+\label{PruningExample}
+\index[general]{Automatic Pruning and Recycling Example }
+\index[general]{Example!Automatic Pruning and Recycling }
+
+Perhaps the best way to understand the various resource records that come into
+play during automatic pruning and recycling is to run a Job that goes through
+the whole cycle. If you add the following resources to your Director's
+configuration file:
+
+\footnotesize
+\begin{verbatim}
+Schedule {
+ Name = "30 minute cycle"
+ Run = Level=Full Pool=File Messages=Standard Storage=File
+ hourly at 0:05
+ Run = Level=Full Pool=File Messages=Standard Storage=File
+ hourly at 0:35
+}
+Job {
+ Name = "Filetest"
+ Type = Backup
+ Level = Full
+ Client=XXXXXXXXXX
+ FileSet="Test Files"
+ Messages = Standard
+ Storage = File
+ Pool = File
+ Schedule = "30 minute cycle"
+}
+# Definition of file storage device
+Storage {
+ Name = File
+ Address = XXXXXXXXXXX
+ SDPort = 9103
+ Password = XXXXXXXXXXXXX
+ Device = FileStorage
+ Media Type = File
+}
+FileSet {
+ Name = "Test Files"
+ Include = signature=MD5 {
+ fffffffffffffffff
+ }
+ Exclude = { *.o }
+}
+Pool {
+ Name = File
+ Use Volume Once = yes
+ Pool Type = Backup
+ LabelFormat = "File"
+ AutoPrune = yes
+ VolumeRetention = 4h
+ Maximum Volumes = 12
+ Recycle = yes
+}
+\end{verbatim}
+\normalsize
+
+Where you will need to replace the {\bf ffffffffff}'s by the appropriate files
+to be saved for your configuration. For the FileSet Include, choose a
+directory that has one or two megabytes maximum since there will probably be
+approximately eight copies of the directory that {\bf Bacula} will cycle through.
+
+In addition, you will need to add the following to your Storage daemon's
+configuration file:
+
+\footnotesize
+\begin{verbatim}
+Device {
+ Name = FileStorage
+ Media Type = File
+ Archive Device = /tmp
+ LabelMedia = yes;
+ Random Access = Yes;
+ AutomaticMount = yes;
+ RemovableMedia = no;
+ AlwaysOpen = no;
+}
+\end{verbatim}
+\normalsize
+
+With the above resources, Bacula will start a Job every half hour that saves a
+copy of the directory you chose to /tmp/File0001 ... /tmp/File0012. After 4
+hours, Bacula will start recycling the backup Volumes (/tmp/File0001 ...). You
+should see this happening in the output produced. Bacula will automatically
+create the Volumes (Files) the first time it uses them.
+
+To turn it off, either delete all the resources you've added, or simply
+comment out the {\bf Schedule} record in the {\bf Job} resource.
+
+\section{Manually Recycling Volumes}
+\label{manualrecycling}
+\index[general]{Volumes!Manually Recycling }
+\index[general]{Manually Recycling Volumes }
+
+Although automatic recycling of Volumes is implemented in version 1.20 and
+later (see the
+\ilink{Automatic Recycling of Volumes}{RecyclingChapter} chapter of
+this manual), you may want to manually force reuse (recycling) of a Volume.
+
+Assuming that you want to keep the Volume name, but you simply want to write
+new data on the tape, the steps to take are:
+
+\begin{itemize}
+\item Use the {\bf update volume} command in the Console to ensure that the
+ {\bf Recycle} field is set to {\bf 1}
+\item Use the {\bf purge jobs volume} command in the Console to mark the
+ Volume as {\bf Purged}. Check by using {\bf list volumes}.
+\end{itemize}
+
+Once the Volume is marked Purged, it will be recycled the next time a Volume
+is needed.
+
+If you wish to reuse the tape by giving it a new name, follow the following
+steps:
+
+\begin{itemize}
+\item Use the {\bf purge jobs volume} command in the Console to mark the
+ Volume as {\bf Purged}. Check by using {\bf list volumes}.
+\item In Bacula version 1.30 or greater, use the Console {\bf relabel}
+ command to relabel the Volume.
+\end{itemize}
+
+Please note that the relabel command applies only to tape Volumes.
+
+For Bacula versions prior to 1.30 or to manually relabel the Volume, use the
+instructions below:
+
+\begin{itemize}
+\item Use the {\bf delete volume} command in the Console to delete the Volume
+ from the Catalog.
+\item If a different tape is mounted, use the {\bf unmount} command,
+ remove the tape, and insert the tape to be renamed.
+\item Write an EOF mark in the tape using the following commands:
+
+\footnotesize
+\begin{verbatim}
+ mt -f /dev/nst0 rewind
+ mt -f /dev/nst0 weof
+\end{verbatim}
+\normalsize
+
+where you replace {\bf /dev/nst0} with the appropriate device name on your
+system.
+\item Use the {\bf label} command to write a new label to the tape and to
+ enter it in the catalog.
+\end{itemize}
+
+Please be aware that the {\bf delete} command can be dangerous. Once it is
+done, to recover the File records, you must either restore your database as it
+was before the {\bf delete} command, or use the {\bf bscan} utility program to
+scan the tape and recreate the database entries.