sam-recycler - Recycles Oracle HSM volumes
∕opt∕SUNWsamfs∕sbin∕sam-recycler
[-b]
[-c]
[-C]
[-d]
[-E]
[-n]
[-s]
[-t]
[-v]
[-V]
[-x]
[-X]
[family_set | archive_set]
SUNWsamfs
The sam-recycler command
invokes the recycler.
The recycler removes expired archive copies
and frees up archive volumes.
Often, the recycler is invoked
through root's crontab (1) file at an off-peak time.
However, the recycler can be invoked at any time.
You can specify that only a specific library or archive set be recycled. You can recycle by library only when archiving to tape or magneto optical cartridges in a library. Note that you cannot recycle by library if you are using disk archiving.
If you want to recycle by archive set, you must name the archive sets
to be recycled in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.
You can provide directives to the recycler through lines entered
in the ∕etc∕opt∕SUNWsamfs∕recycler.cmd file and in
the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.
If no directives are present and no
family_set
or
archive_set
is specified on the command line, recycling does not occur.
The following are the default recycler settings:
The maximum data quantity to recycle (-dataquantity) is 1 gigabyte (1G).
The high water mark (-hwm) is 95.
The VSN gain (-mingain) is 60 for volumes 200GB and 90 for volumes =200GB.
The number of volumes (-vsncount) to recycle is 1.
Automatic email is not sent.
NOTE: Extreme care must be taken when configuring the recycler if you are using disk archiving in an environment with multiple Oracle HSM servers. The diskvols.conf file for each Oracle HSM server must point to a unique set of disk volume resource specifications (disk archiving target directories). If any of these are shared between different Oracle HSM servers, then running the recycler from one Oracle HSM server will destroy the disk archive data that is being managed by the other Oracle HSM server.
The following options determine the volumes to be recycled and the content of the recycler log file.
-bDisplays the capacity and remaining space for each volume in base 10 units in the recycler log file. By default, space is displayed in base 2 units.
-cDisplays the extrapolated capacity of each volume.
This is the volume's capacity assuming the compression observed
on the volume so far continues for the rest of the volume.
This option produces an additional line for each volume with the
heading Alpha:.
-CSuppresses listing of initial catalog(s).
-dDisplays messages during the volume selection phase of processing. These messages indicate why each volume was, or was not, selected for recycling.
-ESpecifies that the volume section of the recycler's log file list only volumes that are not 100% free.
-nPrevents any actions from being taken.
This option causes
∕opt∕SUNWsamfs∕sbin∕sam-recycler
to behave as if -recycle_ignore were specified in the
∕etc∕opt∕SUNWsamfs∕archiver.cmd
file for all archive sets.
-sSuppresses the listing of individual volumes in the initial catalog section.
-tRecycle tape volumes only.
-vDisplays information about which files are resident on the volume that is marked for recycling. If no path name can be calculated for the inode, it lists the inode. These files are on volumes that are being drained. Using this option can consume a lot of CPU cycles.
-VSuppresses the volume section in the listing.
-xDisplays messages for expired archive copies.
These are copies that are older than the time the
volume upon which the copies reside was labeled.
Such copies generate an error message when staged.
The data for those copies is irrecoverable.
These archive copies must be unarchived. If any such
copies are discovered, the recycler stops.
This is the default behavior. Also see the -X option.
-XInhibits the messages that indicate the existance of expired
archive copies. Typically, if the recycler detects expired
archive copies, it stops. Use this options if
you want the recycler to continue
in the presence of expired archive copies. Also see
the -x option.
Recycles only the named family_set or archive_set.
This is an optional argument.
If a family_set is specified, the library associated with the family set
is recycled. The family set is the fourth field in a server's mcf file.
If an archive_set is specified, that archive set
is recycled. The archive_set specified must include the copy number,
as stated in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.
For example, arset.1.
If no family_set or archive_set name is specified, the
recycler recycles
according to specifications in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd
and the ∕etc∕opt∕SUNWsamfs∕recycler.cmd files.
It examines each library and archive set specified.
Regardless of a specification, only archive sets and family sets that have a current usage that is less than the high-water mark are recycled.
The recycler splits its work into two phases: volume selection and volume recycling.
The recycler selects volumes for recycling
based on the amount of space used by expired archive
copies as a percentage of total space on a volume. For each library
or archive set being recycled, the volumes
with the highest percentages of expired copies are selected to bring
the media utilization in the library or archive set below
the configured high-water-mark. This assumes that
each volume selected would contribute at
least VSN-minimum-percent-gain
percent of its total space if it were recycled.
If no such volumes
exist, the library or archive set cannot be recycled. Ties in
expired space are resolved by selecting the volumes with the least amount
of unexpired space.
For more information on setting a high water mark, see
the recycler.cmd (4) man page.
A few conditions can prevent a volume from being selected.
A volume cannot be recycled if
it contains data associated with a removable media file created by
the request (1) command.
In addition, it cannot be recycled if
it is listed in the ∕etc∕opt∕SUNWsamfs∕recycler.cmd
file's no_recycle section.
After volumes have been selected, they are recycled.
Volume recycling differs depending upon whether the archive media is a disk volume or whether it is a removable cartridge in a library. Archiving to disk volumes is described first.
When a disk volume is selected for recycling, the volume is not marked for recycling. Additional archive copies can be written to it. Expired archive copies on the disk volume are identified and removed. Valid archive copies are left alone.
When a tape or magneto optical volume is selected for recycling, the system prevents additional archive copies from being written to it. If you are recycling to cartridges in a library, all files with active archive copies in volumes on the cartridges are marked to be re-archived. The archiver moves these copies to other volumes. In subsequent runs, the recycler checks these volumes and post-processes them when all valid archive copies have been relocated.
The recycler
checks to see if there are volumes that were selected for
recycling that have not yet been post-processed. If such volumes
exist, and they are now devoid of active archive copies, the sam-recycler
command invokes the ∕etc∕opt∕SUNWsamfs∕scripts∕recycler.sh (1m),
which post-processes these volumes with arguments including the generic media
type (tp or od),
the VSN, the element address in the library, and the equipment number
of the library in which the volume resides. The script can
relabel the cartridge using either the original VSN or a new VSN; or
it can export the cartridge from the library; or it
can perform another user-defined action.
The ∕etc∕opt∕SUNWsamfs∕scripts∕recycler.sh (1m) script clears the recycling flag
to indicate that recycling has completed on the volume.
The odlabel (1m) and tplabel (1m) commands clear this flag
after the cartridge has been relabeled.
The recycler log is divided into several sections.
The first section
describes each library catalog and archive set.
The header contains the family set name or archive set name and the
vendor, product, and catalog path name. Then, the
capacity and remaining space for each volume appears, in bytes, with
suffixes k, M, G, and T representing
kilobytes, megabytes, gigabytes, and terabytes, respectively.
In this log file, a kilobyte=1024 bytes, a megabyte=1024*1024
bytes, and so on by default. If -b option is specified,
the capacity and remaining space for each volume appears, in base 10 units.
Then, a summary, containing the total capacity and total
space remaining is shown in bytes and as a percentage of space used.
The recycling parameters set in the recycler and archiver command files
are also shown.
The second section is a series of tables, one for each library
and archive set that has associated volumes.
The name of the library or archive set is shown just to the right of
the ----Percent---- label.
A tape volume can be associated with only one physical library. But same as
disk volumes it can belong to multiple archive sets.
Attempts to assign a volume to multiple archive sets are marked
with a in multiple sets label.
The following fields are displayed:
Field NameMeaning
StatusA phrase giving the volume's recycle status, as follows:
empty VSNThe volume is empty of both expired and current archive images
full VSNThe volume has no free space, but it does have current archive images.
in multiple setsThe volume matches multiple archive sets in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.
new candidateThe volume was chosen for recycling during this recycler run.
no-data VSNThe volume contains only expired archive images and free space.
no_recycle VSNThe volume is listed in the no_recycle section of
the ∕etc∕opt∕SUNWsamfs∕recycler.cmd file.
archive -n filesThe volume contains archive images for files now marked as archive -n.
old candidateThe volume was already marked for recycling before this recycler run.
request filesThe volume contains archive images for removeable media files.
partially fullThe volume contains both current archive images and free space.
shelved VSNThe volume is not currently located in any library.
Archives CountThe number of archive copies that are contained on this volume.
Archives BytesThe number of bytes of archive copies contained on this volume.
Percent UseThe percentage of space in use on this volume by current archive copies. It is estimated by summing up the sizes of the archive copies on the medium. Because of compression, this value can overstate the amount of space actually used by these images. This is the amount of data that would need to be moved if the volume were selected for recycling.
Percent ObsoleteThe percentage of space used on this volume for which no archive copies were found. This is the space that can be reclaimed by recycling this cartridge.
The Percent Obsolete value is calculated as follows:
100% - In Use - Free
Because In Use can overstate the actual space used (because of
compression), the sum of In use + Free can exceed 100%, which
renders Percent Obsolete to be a negative value.
Although aesthetically unpleasing,
this does not cause any problems in the operation of the recycler.
Percent FreeThe percentage of free space remaining on this volume. This value comes directly from the library catalog. It gives the percent of the volume's total capacity that is available to hold new archive images.
For media that supports data compression, a best-guess value of
the average compression is calculated from the ratio of the number of
physical tape blocks consumed on the volume (that is, the
difference of capacity - space)
to the logical number of tape blocks written to the volume.
The latter value is kept in the catalog.
This ratio is then used to adjust the In Use value before it
is written to the log file.
The first volume to appear in the log file, for each library or archive set, is the one most in need of recycling.
Here is an example recycler log file:
========== Recycler begins at Thu Feb 5 13:40:20 1998 ===========
3 catalogs:
0 Family: hy Path: ∕tmp∕y
Vendor: Oracle HSM Product: Historian
EA ty capacity space vsn
(no VSNs in this media changer)
Total Capacity: 0 bytes, Total Space Available: 0 bytes
Media utilization 0%, high 0% VSN_min 0%
1 Family: ad40 Path: ∕var∕opt∕SUNWsamfs∕catalog∕ad40
Vendor: ADIC Product: Scalar DLT 448
EA ty capacity space vsn
0 lt 19.2G 0 DLT3
1 lt 17.7G 17.6G DLT4N
5 lt 17.7G 17.6G DLT6
Total Capacity: 54.6G bytes, Total Space Available: 35.2G bytes
Media utilization 35%, high 75% VSN_min 50%
2 Family: arset0.1 Path: ∕etc∕opt∕SUNWsamfs∕archiver.cmd
Vendor: Oracle HSM Product: Archive set
EA ty capacity space vsn
0 lt 0 0 DLT5
1 lt 19.2G 0 DLT3
2 lt 0 0 DLT2
3 lt 17.7G 17.6G DLT4N
4 lt 17.7G 17.6G DLT6
Total Capacity: 54.6G bytes, Total Space Available: 35.2G bytes
Media utilization 35%, high 80% VSN_min 50%
Send mail to root when this archive set needs recycling.
6 VSNs:
---Archives--- -----Percent-----
-----Status----- Count Bytes Use Obsolete Free Library:Type:VSN
shelved VSN 677 648.9M none:lt:DLT0
---Archives--- -----Percent----- arset0.1
-----Status----- Count Bytes Use Obsolete Free Library:Type:VSN
no-data VSN 0 0 0 100 0 ad40:lt:DLT3
empty VSN 0 0 0 0 0 (NULL):lt:DLT2
empty VSN 0 0 0 0 100 ad40:lt:DLT6
full VSN 4 32.1k 0 0 0 (NULL):lt:DLT5
partially full 4 40.8k 0 0 100 ad40:lt:DLT4N
Recycler finished.
========== Recycler ends at Thu Feb 5 13:40:41 1998 ===========
Here is the corresponding archiver.cmd file:
interval = 2m
no_archive .
fs = samfs1
arset0 testdir0
1 1s
2 1s
3 1s
4 1s
no_archive .
fs = samfs2
no_archive .
vsns
arset0.1 lt DLT3 DLT4N DLT6 DLT1
arset0.2 lt DLT3 DLT4N DLT6 DLT1
arset0.3 lt DLT3 DLT4N DLT6 DLT1
arset0.4 lt DLT3 DLT4N DLT6 DLT1
samfs1.1 lt DLT3
samfs2.1 lt DLT4N
endvsns
params
arset0.1 -drives 4 -recycle_hwm 80 -recycle_mingain 50
endparams
Here is the corresponding ∕etc∕opt∕SUNWsamfs∕recycler.cmd file:
logfile = ∕var∕tmp∕recycler.log ad40 75 50 no_recycle mo ^OPT003
The recycler recycles volumes listed in the historian's catalog. The volumes listed in the historian catalog have been exported from a library or have been or are currently in a manually-mounted device.
The ∕etc∕opt∕SUNWsamfs∕scripts∕recycler.sh (1m) script is passed the name hy,
signifying volumes that reside in the historian catalog
so that it can cope with the possibility of the volumes
being recycled residing in an off-site storage facility.
Typically, the ∕etc∕opt∕SUNWsamfs∕scripts∕recycler.sh (1m) script sends email to the
administrator when this occurs to remind the administrator to bring
the off-site volume back on site so that it can be reused.
Volumes do not need to be on site to be drained of archive
copies unless such a volume contains the only available archive
copy of an off-line file.
When the recycler recycles by archive set, it treats each
archive set as a small library that holds just the volumes
assigned to the archive set in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.
The volumes
that are identified as belonging to a recycling archive set are
removed from the recycler's version of the catalog for the library
that physically contains the volume. Thus, only the volumes that
are not part of an archive set remain in the library catalog.
To enable recycling for a given archive set, it must have one of the
recycling options specified in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file. For
more information, see the archiver.cmd (4) man page.
Consider the following message:
Jan 22 10:17:17 jupiter sam-recycler[3400]: Cannot ioctl(F_IDSCF)
Cannot find pathname for filesystem ∕samfs1 inum∕gen 406∕25
The preceding message means that the recycler could not set
the rearchive flag for a file.
When this happens, the recycler typically emits a message containing
the path name, as follows:
Jan 22 10:17:17 jupiter sam-recycler[3400]: Cannot ioctl(F_IDSCF)
∕samfs1∕testfile
However, in the first message, you see text beginning with Cannot find
pathname…. This means that the recycler failed in its attempt to
convert the inode number (in the preceding example message, it
is inode number 406) and generation number (here, 25) into a path
name in the ∕samfs1 file system.
The most likely reason for this to occur is that the file was deleted between the time that the recycler determined it needed to be rearchived and the time the recycler actually issued the system call to set the rearchive flag.
