Skip Navigation Links | |
Exit Print View | |
Sun QFS and Sun Storage Archive Manager 5.3 Reference Manual Sun QFS and Sun Storage Archive Manager 5.3 Information Library |
1. User Commands (Man Pages Section 1)
2. Maintenance Commands (Man Pages Section 1M)
3. Library Functions (Man Pages Section 3)
4. Library Functions (Man Pages Section 3X)
5. File Formats (Man Pages Section 4)
NAME sam-recycler - Recycles SAM-QFS volumes SYNOPSIS /opt/SUNWsamfs/sbin/sam-recycler [-b] [-c] [-C] [-d] [-E] [-n] [-s] [-t] [-v] [-V] [-x] [-X] [family_set | archive_set] AVAILABILITY SUNWsamfs DESCRIPTION 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: o The maximum data quantity to recycle (-dataquantity) is 1 gigabyte (1G). o The high water mark (-hwm) is 95. o The VSN gain (-mingain) is 60 for volumes <200GB and 90 for volumes >=200GB. o The number of volumes (-vsncount) to recycle is 1. o 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 SAM-QFS servers. The diskvols.conf file for each SAM-QFS server must point to a unique set of disk volume resource specifications (disk archiving target directories). If any of these are shared between different SAM-QFS servers, then running the recycler from one SAM-QFS server will destroy the disk archive data that is being managed by the other SAM-QFS server. OPTIONS The following options determine the volumes to be recycled and the content of the recycler log file. -b Displays 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. -c Displays 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:. -C Suppresses listing of initial catalog(s). -d Displays messages during the volume selection phase of processing. These messages indicate why each volume was, or was not, selected for recycling. -E Specifies that the volume section of the recycler's log file list only volumes that are not 100% free. -n Prevents 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. -s Suppresses the listing of individual volumes in the initial catalog section. -t Recycle tape volumes only. -v Displays 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. -V Suppresses the volume section in the listing. -x Displays 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. -X Inhibits 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. family_set | archive_set 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. OPERATION The recycler splits its work into two phases: volume selection and volume recycling. Phase 1 - Volume Selection 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. Phase 2 - Volume Recycling 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. RECYCLER OUTPUT 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 Name Meaning Status A phrase giving the volume's recycle status, as follows: empty VSN The volume is empty of both expired and current archive images full VSN The volume has no free space, but it does have current archive images. in multiple sets The volume matches multiple archive sets in the /etc/opt/SUNWsamfs/archiver.cmd file. new candidate The volume was chosen for recycling during this recycler run. no-data VSN The volume contains only expired archive images and free space. no_recycle VSN The volume is listed in the no_recycle section of the /etc/opt/SUNWsamfs/recycler.cmd file. archive -n files The volume contains archive images for files now marked as archive -n. old candidate The volume was already marked for recycling before this recycler run. request files The volume contains archive images for removeable media files. partially full The volume contains both current archive images and free space. shelved VSN The volume is not currently located in any library. Archives Count The number of archive copies that are contained on this volume. Archives Bytes The number of bytes of archive copies contained on this volume. Percent Use The 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 Obsolete The 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 Free The 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: SAM-FS 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: SAM-FS 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 RECYCLING HISTORIAN CARTRIDGES 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. RECYCLING BY ARCHIVE SET 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. MESSAGES 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. SEE ALSO chmed(1M), odlabel(1M), recycler.sh(1M). sam-archiverd(1M), tplabel(1M). archiver.cmd(4), mcf(4), recycler.cmd(4).