C Configuration Directives for Archiving

This appendix lists directives used in the SAM-QFS command (.cmd) files that configure archiving file systems and related software operations (for comprehensive descriptions, see the SAM-QFS man pages). Directives are divided into the following sections:

• Archiving Directives

• Staging Directives

• Preview Request Directives

You can configure SAM-QFS command files either from the command line, as described here, or by using the SAM-QFS Manager software. For information on SAM-QFS Manager, see the online help.

Archiving Directives

This section provides usage information for the archiving directives that make up the archiver.cmd file. Archiving directives define the archive sets that control how files are archived, the media used, and the overall behavior of the archiving software.

There are four basic types of archiving directives:

• Global Archiving Directives

• File System Directives

• Copy Parameters

• Volume Serial Number (VSN) Association Directives

Both global and file system directives control how files are archived. But the archiver evaluates the file system-specific directives before evaluating the global directives. So file system directives override global directives when there is a conflict. Similarly, within the file system directives, the first directive listed overrides any subsequent, conflicting directives.

Global Archiving Directives

Global directives control the overall archiver operation and enable you to optimize operations for all configured file systems. Global directives are specified by entering equal sign (=) in the second field or the absence of additional fields. Global directives start the archiver.cmd file and end at the first of the File System Directives.

archivemeta: Controlling Whether Metadata Is Archived

The archivemeta directive controls whether file system metadata is archived. If files are often moved around and there are frequent changes to the directory structures in a file system, archive the file system metadata. But if the directory structures are reasonably stable, you can disable metadata archiving and reduce the actions performed by removable media drives. By default, metadata is not archived.

This directive has the following format:

archivemeta=state

For state, specify either on or off. The default is off.

The archiving process for metadata depends on whether you are using a Version 1 or a Version 2 superblock, as follows:

• For Version 1 file systems, the archiver archives directories, removable media files, segment index inodes, and symbolic links as metadata.

• For Version 2 file systems, the archiver archives directories and segment index inodes as metadata. Removable media files and symbolic links are stored in inodes rather than in data blocks. They are not archived. Symbolic links are archived as data.

archmax: Controlling the Size of Archive Files

The archmax directive specifies the maximum size of an archive (.tar) file. After the target-size value is met, no more user files are added to the archive file. Large user files are written in a single archive file.

To change the defaults, use the following directive:

archmax=media target-size

where media is one of the media types defined in Appendix A and in the mcf man page and where target-size is the maximum size of the archive file. This value is media-dependent. By default, archive files written to optical discs are no larger than 5 megabytes. The default maximum archive file size for tapes is 512 megabytes.

Setting large or small sizes for archive files has advantages and disadvantages. For example, if you are archiving to tape and archmax is set to a large size, the tape drive stops and starts less often. However, when writing large archive files, a premature end-of-tape causes a large amount of tape to be wasted. As a best practice, do not set the archmax directive to be more than 5 percent of the media capacity.

The archmax directive can also be set for an individual archive set.

bufsize: Setting the Archiver Buffer Size

By default, a file being archived is copied to archive media using a memory buffer. You can use the bufsize directive to specify a non-default buffer size and, optionally, to lock the buffer. These actions can improve performance. You can experiment with different buffer-size values. This directive has the following format:

bufsize=media buffer-size [lock]

where:

• media is one of the media types defined in Appendix A and in the mcf man page

• buffer-size is a number in the range [2-1024]. The default is 4. This value is multiplied by the dev_blksize value for the media type, and the resulting buffer size is used. The dev_blksize value is specified in the defaults.conf file. See the defaults.conf man page for details.

• lock indicates whether the archiver can use locked buffers when making archive copies.

  If lock is specified, the archiver sets file locks on the archive buffer in memory for the duration of the sam-arcopy operation. This action avoids the overhead associated with locking and unlocking the buffer for each I/O request and results in a reduction in system CPU time.

  The lock argument must be specified only on large systems with large amounts of memory. Insufficient memory can cause an out-of-memory condition. The lock argument is effective only if direct I/O is enabled for the file being archived. By default, lock is not specified and the file system sets the locks on all direct I/O buffers, including those for archiving.

You can specify a buffer size and a lock for each archive set by using the archive set copy Parameters, -bufsize and -lock. For more information, see "Archive Copy Directives".

drives: Controlling the Number of Drives Used for Archiving

By default, the archiver uses all of the drives in an automated library for archiving. To limit the number of drives used, use the drives directive. This directive has the following format:

drives=auto-lib count

where auto-lib is the family set name of the automated library as defined in the mcf file and count is the number of drives to be used for archiving activities.

You can also use the archive set copy parameters -drivemax, -drivemin, and -drives for this purpose.

examine: Controlling Archive Scans

The examine directive sets the method that the archiver uses to identify files that are ready for archiving:

examine=method

where method is one of the following directives:

• noscan, the default, specifies continuous archiving. After the initial scan, directories are scanned only when the content changes and archiving is required. Directory and inode information is not scanned. This archiving method provides better performance than scan archiving, particularly for file systems with more than 1,000,000 files.

• scan specifies scan archiving. The initial file system scan is a directory scan. Subsequent scans are inode scans.

• scandirs specifies scan archiving on directories only. If the archiver finds a directory with the no_archive attribute set, the directory is not scanned. If you have files that do not change, place them in this type of directory to reduce the amount of time spent on archiving scans.

• scaninodes specifies scan archiving on inodes only.

interval: Specifying an Archive Interval

The archiver runs periodically to examine the status of all mounted archived-enabled file systems. The timing is controlled by the archive interval, which is the time between scan operations on each file system. To change the archive interval, use the interval directive.

The interval directive initiates full scans only when continuous archiving is not set and no startage, startsize, or startcount Parameters have been specified. If continuous archiving is set (examine=noscan), the interval directive acts as the default startage value. This directive has the following format:

interval=time

For time, specify the amount of time you want between scan operations on a file system. By default, time is interpreted in seconds and has a value of 600, which is 10 minutes. You can specify a different unit of time, such as minutes or hours.

If the archiver receives the samu utility's arrun command, it begins scanning all file systems immediately. If the examine=scan directive is also specified in the archiver.cmd file, a scan is performed after arrun or arscan is issued.

If the hwm_archive mount option is set for the file system, the archive interval can be shortened automatically. This mount option specifies that the archiver commences its scan when the file system is filling up and the high-water mark is crossed. The high=percent mount option sets the high-water mark for the file system.

For more information about specifying the archive interval, see the archiver.cmd and mount_samfs man pages.

logfile: Specifying an Archiver Log File

The archiver can produce a log file that contains information about each file that is archived, re-archived, or unarchived. The log file is a continuous record of archival action. By default, archiver log files are not enabled. To specify a log file, use the logfile directive. This directive has the following format:

logfile=pathname

For pathname, specify the absolute path and name of the log file. The logfile directive can also be set for an individual file system.

Archiver log files are essential for recovering damaged or lost file systems and can be valuable for monitoring and analysis. So you should enable archiver logs and back them up. See the StorageTek Storage Archive Manager and StorageTek QFS Installation and Configuration Guide (SAM-QFS Customer Documentation Library, docs.oracle.com.) for more information.

notify: Renaming the Event Notification Script

The notify directive sets the name of the archiver's event notification script file. This directive has the following format:

notify=filename

For filename, specify the name of the file containing the archiver event notification script or the full path to this file. The default file name is /etc/opt/SUNWsamfs/scripts/archiver.sh.

The archiver executes this script to process various events in a site-specific manner. The script is called with one of the following keywords for the first argument: emerg, alert, crit, err, warning, notice, info, and debug.

Additional arguments are described in the default script. For more information, see the archiver.sh man page.

ovflmin: Controlling Volume Overflow

When volume overflow is enabled, the archiver can create archived files that span multiple volumes. When a file size exceeds the specified minimum size, the archiver writes the remaining portion of this file to another volume of the same type. The portion of the file written to each volume is called a section. The sls command lists the archive copy, showing each section of the file on each volume.

The archiver controls volume overflow through the ovflmin directive. By default, volume overflow is disabled. To enable volume overflow, use the ovflmin directive in the archiver.cmd file. This directive has the following format:

ovflmin = media minimum-file-size

where media is one of the media types defined in Appendix A and in the mcf man page and minimum-file-size is the size of the smallest file that you want to trigger the volume overflow. The ovflmin directive can also be set for an individual archive set.

Use volume overflow with caution after assessing its effects. Disaster recovery and recycling are much more difficult with files that span volumes.Volume overflow files do not generate checksums. For more information on using checksums, see the ssum man page.

scanlist_squash: Controlling Scanlist Consolidation

The scanlist_squash parameter controls scanlist consolidation. The default setting is off. This parameter can be either global or file system-specific.

When this option is enabled, the scan list entries for files in two or more subdirectories with the same parent directory that need to be scanned by sam-arfind at a much later time are consolidated. These directories are combined upwards to the common parent, which results in a deep recursive scan of many subdirectories. This consolidation can cause a severe performance penalty if archiving on a file system that has a large number of changes to many subdirectories.

setarchdone: Controlling the Setting of the archdone Flag

The setarchdone Parameter is a global directive that controls the setting of the archdone flag when the file is examined by sam-arfind. This directive has the following format:

setarchdone=state

where state is either on or off.

When all archive copies for a file have been made, the archdone flag is set for that file to indicate that no further archive action is required. During directory scans, the archdone flag is also set for files that will never be archived. Because evaluating whether a file will ever be archived can affect performance, the setarchdone directive gives you control over this activity. This directive controls the setting of the archdone flag only on files that will never be archived. It does not affect the setting of the archdone flag after archive copies are made.

The default setting for the directive is off if the examine directive is set to scandirs or noscan.

wait: Delaying Archiver Startup

The wait directive causes the archiver to wait for a start signal from samu or SAM-QFS File System Manager. By default, the archiver begins archiving when started by sam-fsd. This directive has the following format:

wait

The wait directive can also be set for an individual file system.

File System Directives

File system directives define archiving behavior for specific file systems:

• fs: Specifying a File System

• copy-number [archive-age]: Specifying Multiple Copies of File System Metadata

• interval, logfile, scanlist as File System Directives

fs: Specifying a File System

Each fs=file-system-name directive introduces a sequence of archiving directives that apply only to the named file system, file-system-name. This directive has the following format:

fs=file-system-name

where file-system-name is the file system name defined in the mcf file.

General directives and archive set association directives that occur after an fs= directive apply only to the specified file system.

copy-number [archive-age]: Specifying Multiple Copies of File System Metadata

File system metadata includes path names in the file system. If you have frequent changes to directories, the new path names cause the creation of new archive copies and result in frequent loading of the volumes specified for metadata. If more than one copy of the metadata is required, place copy definitions in the archiver.cmd file immediately after the fs= directive.

copy-number [archive-age]

where time is expressed as one or more combinations of an integer and a unit of time. Units include s (seconds), m (minutes), h (hours), d (days), w (weeks), and y (years). By default, SAM-QFS makes only a single copy of the metadata.

In the example, copy 1 of the metadata for the fs=samma1 file system is made after 4 hours (4h) and copy 2 is made after twelve hours (12h):

# General Directives
archivemeta = off
examine = noscan
# Archive Set Assignments
fs = samma1
1 4h
2 12h

interval, logfile, scanlist as File System Directives

Several directives can be specified both as global directives for all file systems and as directives specific to only one file system. These directives are described in the following sections:

• interval: Specifying an Archive Interval

• logfile: Specifying an Archiver Log File

• scanlist_squash: Controlling Scanlist Consolidation

• wait: Delaying Archiver Startup

archive-set-name: the Archive Set Assignment Directive

The archive set assignment directive specifies which files will be archived together. You can specify files very narrowly, using the wide range of selection criteria described below. But avoid doing so unless absolutely necessary. In general, you should configure the smallest of number of the most inclusive archive sets possible. Archive sets have exclusive use of a set of archival media. So large numbers of archive sets each defined by excessively restrictive assignment criteria cause poor media utilization, high system overhead, and reduced performance. In extreme cases, jobs may fail due to lack of usable media, even though ample capacity remains in the library.

Each archive set assignment directive has the following format:

archive-set-name path [-access interval [-nftv]] [-after date-time] [-minsize size] [-maxsize size] [-user username] [-group groupname] [-name regex]

where:

• archive-set-name is the administrator-defined name for the archive set.

  Names can contain up to 29 characters in any combination of upper and/or lower case letters [A-Za-z], numerals [0-9], and underscore characters (_), as long as the first character is a letter. You cannot include any other characters, including spaces, and you cannot use the names of the SAM-QFS special archive sets no_archive and allsets for your own archive sets.

• path specifies the path relative to the mount point of the subdirectory where archiving starts within the file system. All files in the starting directory and its subdirectories are archived. To include all of the files in a file system, use the dot (.) character. A leading slash (/) is not allowed in the path.

• -access rearchives files that have not been accessed for the amount of time specified by interval, where interval is an integer followed by one of following units: s (seconds), m (minutes), h (hours), d (days), w (weeks), and y (years).

  This parameter lets you schedule rearchiving of less used files from higher to lower cost media. The software validates the access and modification times for files to ensure that they are greater than or equal to the file creation time and less than or equal to the time at which the file is examined. The -nftv (no file time validation) parameter disables this validation.

• -after archives only files that have been created or modified after date-time, where date-time is an expression of the form YYYY-MM-DD [hh:mm:ss] [Z] and where YYYY, MM, DD, hh, mm, and ss are integers representing the year, month, day, hour, minutes, and seconds, respectively. The optional Z parameter sets the time zone to Coordinated Universal Time (UTC). The defaults are 00:00:00 and local time.

• -minsize and -maxsize archive only those files that are over or under the specified size, where size is an integer followed by one of the following units: b (bytes), k (kilobytes), M (megabytes), G (gigabytes), T (terabytes), P (petabytes), E (exabytes).

• -user username and -group groupname archive only files that belong to the specified user and/or group.

• -name archives all files that have path and file names matching the pattern defined by the regular expression regex.

Archive Copy Directives

By default, the archiver writes a single archive copy for files in the archive set when the archive age of the file is four minutes. To change the default behavior, use archive copy directives. Archive copy directives must appear immediately after the archive set assignment directive to which they pertain.

The archive copy directives begin with a copy-number value of 1, 2, 3, or 4. The digit is followed by one or more arguments that specify archive characteristics for that copy. Each archive copy directive has the following format:

copy-number [archive-age] [-release [attribute] [-norelease][-stage[attribute] [unarchive-age]

where:

• The optional archive-age parameter is the time that a new or modified file must spend in the disk cache before it becomes eligible for archiving. Specify archive-age as one or more combinations of an integer and a unit of time, where units include s (seconds), m (minutes), h (hours), d (days), w (weeks), and y (years). The default is 4m (4 minutes).

• The optional -release parameter clears the SAM-QFS releaser software to free the disk space used by files as soon as an archive copy has been made. The optional release attribute is -a, -n, or -d. The -a (associative staging) attribute requires that the software stage all files that have been released from the archive set when any one of them is accessed. The -n attribute requires that the software read directly from the archive media and never stage files.The -d attribute resets the default staging behavior.

• The optional -norelease parameter does not clear the SAM-QFS releaser software to free the disk space used by files until all copies marked with -norelease have been made.

• -release -norelease, used together, require that the SAM-QFS software free the disk space used by files immediately after all copies that are flagged -release -norelease are made. SAM-QFS does not wait for the releaser process to run.

• The optional -stage parameter The optional release attribute is -a, -c copy-number, -f, -I, -i input_file, -w, -n, -p, -V, -x, -r, -d, where:

  -a (associative staging) requires staging of all files from the archive set when any one of them is accessed.

  -c copy-number requires that the software stage from the specified copy number.

  -n requires that the software read directly from the archive media and never stage files.

  -w requires that the software wait for each file to be successfully staged before proceeding (not valid with -d or -n).

  -d resets the default staging behavior.

• unarchive-age parameter specifies the amount of time that an archival copy of a file spends in the archive before it is unarchived to free space on the media for reuse. Time is expressed as one or more combinations of an integer and a unit of time, where units include s (seconds), m (minutes), h (hours), d (days), w (weeks), and y (years).

The example below contains two copy directives for archive set allsamma1. The first directive does not release copy 1 until it reaches an archive age of five minutes (5m). The second directive does not release copy 2 until it reaches an archive age of one hour (1h) and unarchives copy 2 once it reaches the unarchive age of seven years and six months (7y6m):

# Archive Set Assignments
fs = samma1
logfile = /var/adm/samma1.archive.log
allsamma1 .
    1 -norelease 5m
    2 -norelease 1h 7y6m 

Copy Parameters

Copy parameters define how the copies specified by an archive set are created.The archive set copy parameters section of the archiver.cmd file begins with the params directive and ends with the endparams directive:

params
allsets -sort path -offline_copy stageahead
allsets.1 -startage 10m -startsize 10M -drives 10 -archmax 1G
allsets.2 -startage 1h -startsize 1G -drives 2 -archmax 10G -reserve set
endparams

Each copy parameter takes the following form:

archive-set-name[.copy-number][R] [-startage time] [-startcount count] [-startsize size] [-archmax maximum-size] [-bufsize=buffer-size] [-drivemax maximum-size] [-drivemin minimum-size] [-drives number] [-fillvsns] [-lock] [-offline_copy method] [-sort criterion] [-rsort criterion] [-recycle_dataquantity size] [-recycle_hwm percent] [-recycle_ignore] [-recycle_mailaddr mail-address] [-recycle_mingainpercentage] [-recycle_vsncountcount ] [-recycle_minobs percentage] [-unarchagetime_ref] [-tapenonstop] [-reserve keyword ] [-priority multiplier ranking] 

where:

• archive-set-name is the name of an archive set defined by an archive set assignment directive in the File System Directives or the special directive allsets, which applies the specified copy parameters to all defined archive sets. Set parameters for allsets first, before specifying parameters for individual archive sets. Otherwise, the parameters for individual archive sets will override the allsets specification, defeating its purpose.

• .copy-number limits the application of the specified copy parameters to the archive copy specified by copy-number, where copy-number is an integer in the range [1-4], and the optional R limits application of the parameters to rearchived copies.

• -startage time specifies interval between the moment when the first file is added to an archive request and the moment when archiving actually begins. Specify time as one or more combinations of an integer and a unit of time, where units include s (seconds), m (minutes), h (hours), d (days), w (weeks), and y (years). The default is 2h (two hours).

• -startcount count specifies the minimum number of files in an archive request. Archiving begins when the number of files awaiting archiving reaches this threshold. By default, count is not set.

• -startsize size specifies the minimum size, in bytes, of an archive request. Archiving begins when the total size of the files awaiting archiving reaches this threshold. By default, size is not set.

• -archmax limits the size of an archive file to no more than maximum-size, where maximum-size is media-dependent. The default maximum archive file size for magnetic tape is 512 megabytes. Archive files written to optical discs are no larger than 5 megabytes.

  See "archmax: Controlling the Size of Archive Files" for a description of the global archiving directive of the same name.

• -bufsize= buffer-size sets the size of the buffer that holds the holds the archive file as it is being written out to archival media to buffer-size*dev_blksize, where buffer-size is an integer in the range [2-32] and dev_blksize is the block size specified for the media type in the defaults.conf file. The default is 4.

• -drivemax limits the amount of data archived using one drive to no more than maximum-size megabytes, where maximum-size is an integer. By default, maximum-size is not specified.

  When multiple drives are specified using the -drives parameter, limiting the amount of data written to any one drive can improve drives can help to balance workloads and improve overall drive utilization.

• -drivemin minimum-size limits the amount of data archived using one drive to at least minimum-size megabytes, where minimum-size is an integer. The default is the value of -archmax (if specified) or the value listed for the media type in the defaults.conf file.

  Setting a lower limit on the amount of data written to a drive can improves drive utilization and efficiency. Set minimum-size large enough that the transfer time significantly exceeds the time required to load, position, and unload media. When -drivemin is specified, multiple drives are only used when data transfers are large enough.

• -drives number limits the number of drives used for archiving to at most number, where number is an integer. The default is 1.

  Setting a higher maximum number of drives can improve performance when archive sets contain large files or large numbers of files. If the available drives operate at different speeds, specifying multiple drives can also balance these variations and increase archiving efficiency.

• -fillvsns forces the archiving process to use smaller archive files that fill archival media volumes more completely.

  By default, the archiver selects a volume with enough space to hold the all files in an archive copy. This results in larger archive files that may not fit into the remaining capacity on many cartridges. As a result, media is under-utilized overall. The -fillvsns parameter addresses this issue, but at the cost of more media mounts, positioning operations, and unmounts, all of which reduce archiving and staging performance.

• -lock mandates the use of locked buffers when making archive copies using direct I/O. Locked buffers prevent paging of the buffer and improve direct I/O performance.

  The -lock parameter can cause an out-of-memory condition if specified on systems that have limited memory available. By default, locked buffers are not mandated, and the file system retains control over the archiving buffer.

• -offline_copy method specifies how archive copies are made when files have already been released from the disk cache. The specified method can be direct, stageahead, stageall, or none.

  Files can be released as soon as a single archive copy is made, so the remaining copies must be made from an offline copy. A specified -offline_copy method lets you tailor the copy process to suit the number of drives that can be made available and the amount of space available in the disk cache.

  direct copies files directly from the offline volume to the archive volume, using two drives. To insure adequate buffer space, increase the value set by the stage_n_window mount option when using this method.

  stageahead stages the next archive file while writing an archive file to its destination.

  stageall stages all files to disk cache before archiving, using one drive. Make sure that the disk cache is large to hold the files when using this method.

  none (the default) stages files to the disk cache as needed before copying to the archive volume.

• -sort sorts files by criterion before archiving them, where criterion is age, priority, size, or none.

  age specifies sorting by modification time, from oldest to most recent.

  path (the default) specifies sorting by full path name and thus keeps files that reside in the same directories together on the archive media.

  priority specifies sorting by archiving priority, from highest to lowest.

  size sorts files by file size, from smallest to largest.

  none specifies no sorting and archives files in the order in which they are encountered in the file system.

• -rsort criterion sorts files by criterion like -sort, but in reverse order.

• -recycle_dataquantity size limits the amount of data that the recycler will schedule for rearchiving to size bytes, where size is an integer.

  The recycler schedules rearchiving when it need to drain archival volumes of valid archive files. Note that the actual number of volumes selected for recycling may also depend on the -recycle_vsncount parameter. The default is 1073741824 (1 gigabyte).

• -recycle_hwm percent sets the maximum percent media utilization (the high water mark or hwm) that initiates recycling of removable media. The parameter is ignored for disk media (see -recycle_minobs below). The default is 95.

• -recycle_ignore prevents actual recycling of any media in the archive set, while allowing recycling processes to run normally. Used for testing.

• -recycle_mailaddr mail-address directs informational recycler messages to mail-address. Mail is not sent by default.

• -recycle_mingain limits selection of volumes for recycling to those which would increase their free space by at least the specified percentage. The default is 50.

• -recycle_vsncount limits the number of volumes that recycler schedules for rearchiving to count. Note that the actual number of volumes selected for recycling may also be dependant on the -recycle_dataquantity parameter. The parameter is ignored for disk media. The default is 1.

• -recycle_minobs sets the percentage of obsolete files in a disk-resident archive file that triggers rearchiving of the valid files and eventual deletion of the original tar file. The parameter is ignored for removable media (see -recycle_hwm above). The default is 50.

• -unarchage sets the reference time for computing the unarchive age to time_ref, where time_ref is either access for the file access time (the default) or modify for the modification time.

• -tapenonstop writes a single tape mark and an end-of-file (EOF) label at the end of the archive file without closing the removable media file. This speeds transfer of multiple archive files, but the tape cartridge cannot be unloaded until the entire archive set has been written to tape. By default, SAM-QFS software closes the tape file by writing two additional tape marks after the end-of-file label at the end of the archive file.

• -reserve keyword reserves a removable media volume for the exclusive use of a specified archive set. When a volume is first used to hold files from the archive set, the software assigns the volume a unique reserve name based on one or more specified keywords: fs, set, and/or one of the following: dir (directory), user, or group.

  fs includes the file system name in the reserve name: arset.1 -reserve fs.

  set includes the archive set name from the archive set assignment directive in the reserve name: allsets -reserve set.

  dir includes the first 31 characters of the directory path specified in the archive set assignment directive in the reserve name.

  user includes the user name associated with the archive file: arset.1 -reserve user.

  group includes the group name associated with the archive file: arset.1 -reserve group.

  Reserving volumes by set can be advantageous in some situations. But be aware that it is inherently less efficient than allowing the software to select the media. When volumes are reserved, the system must mount, unmount, and position cartridges more often, increasing overhead and reducing performance. Highly restrictive reservation schemes under-utilize available media and, in extreme cases, may cause archiving failures due to lack of available media.

• -priority multiplier ranking changes the archiving priority of files when used with the sort priority parameter listed above. The ranking is a real number in the range [(-3.400000000E+38)-3.400000000E+38] (-3.402823466x10³⁸ to 3.402823466x10³⁸) and multiplier is the archive characteristic for which you are changing the relative ranking, selected from the following list: age, archive_immediate, archive_overflow, archive_loaded, copies, copy1, copy2, copy3, copy4, offline, queuewait, rearchive, reqrelease, size, stage_loaded, and stage_overflow.

  See the archiver and archiver.cmd man pages for more information on priorities.

Volume Serial Number (VSN) Pools Directives

The VSN pools section of the archiver.cmd file defines named collections of archival media volumes that can be specified as a unit in Volume Serial Number (VSN) Association Directives.

The section starts with a vsnpools directive and ends either with an endvsnpools directive or with the end of the archiver.cmd file. The syntax of a VSN pool definition is as follows:

vsn-pool-name media-type volume-specification

where:

• vsn-pool-name is the name that you assign to the pool.

• media-type is one of the two-character, SAM-QFS media type identifiers listed in Appendix A and in the mcf man page.

• volume-specification is a space-separated list of one or more regular expressions that match volume serial numbers. See the Solaris regcmp man page for details on regular expression syntax.

The example defines four VSN pools: users_pool, data_pool, proj_pool, and scratch_pool. A scratch pool is a set of volumes used when specific volumes in a VSN association are exhausted or when another VSN pool is exhausted. If one of the three specific pools is out of volumes, the archiver selects the scratch pool VSNs.

vsnpools
users_pool li ^VOL2[0-9][0-9]
data_pool li ^VOL3.*
scratch_pool li ^VOL4[0-9][0-9]
proj_pool li ^VOL[56].*
endvsnpools

Volume Serial Number (VSN) Association Directives

The VSN associations section of the archiver.cmd file assigns archival media volumes to archive sets. This section starts with a vsns directive and ends with an endvsns directive.

Volumes assignment directives take the following form:

archive-set-name.copy-number [media-type volume-specification] [-pool vsn-pool-name]

where:.

• archive-set-name is the name that an archive set assignment directive assigned to the archive set that you are associating with the specified volumes.

• copy-number is the number that an archive copy directive assigned to the copy that you are associating with the specified volumes. It is an integer in the range [1-4].

• media-type is one of the two-character, SAM-QFS media type identifiers listed in Appendix A and in the mcf man page.

• volume-specification is a space-separated list of one or more regular expressions that match volume serial numbers. See the Solaris regcmp man page for details on regular expression syntax.

• -pool vsn-pool-name is a previously specified, named collection of archival media volumes that can be specified as a unit. See Volume Serial Number (VSN) Pools Directives.

The example illustrates various ways in which media can be associated with two lines of VSN specifications.

vsns
archiveset.1 lt VSN001 VSN002 VSN003 VSN004 VSN005
archiveset.2 lt VSN0[6-9] VSN10
archiveset.3 -pool data_pool
endvsns

Staging Directives

Staging is the process of copying file data from nearline or offline storage back to online storage.

The stager starts when the samd daemon runs. The stager has the following default behavior:

• The stager attempts to use all the drives in the library.

• The stage buffer size is determined by the media type, and the stage buffer is not locked.

• No log file is written.

• Up to 1000 stage requests can be active at any one time.

You can customize the stager's operations for your site by inserting directives into the /etc/opt/SUNWsamfs/stager.cmd file.

When an application requires an offline file, its archive copy is staged to disk cache unless the file was archived with the -n (never stage) option. To make the file available to an application immediately, the read operation tracks along directly behind the staging operation so that the access can begin before the entire file is staged.

Stage errors include media errors, unavailability of media, unavailability of an automated library, and others. If a stage error is returned, the SAM-QFS software attempts to find the next available copy of the file, if one exists and if there is a device available to read the archive copy's media.

The stager.cmd File

In the stager.cmd file, specify directives to override the default behaviors. You can configure the stager to stage files immediately, to never stage files, to staging partially, and to specify other staging actions. For example, specifying the never-stage attribute benefits applications that access small records from large files because the data is accessed directly from the archive media without staging the file online.

This section describes the stager directives. For additional information about stager directives, see the stager.cmd man page. If you are using the SAM-QFS File System Manager software, you can control staging from the File System Summary or File System Details page. You can browse the file system and see the status of individual files, use filters to view certain files, and select specific files to stage. You can select which copy to stage from or let the system choose the copy.

The example shows a stager.cmd file after all possible directives have been set.

drives=dog 1
bufsize=od 8 lock
logfile=/var/adm/stage.log
maxactive=500

drives: Specifying the Number of Drives for Staging

By default, the stager uses all available drives when staging files. If the stager keeps all the drives busy, it can interfere with the archiver's activities. The drives directive specifies the number of drives available to the stager. This directive has the following format:

drives=library count

where:

• library is the family set name of the library as it appears in the mcf file.

• count is the maximum number of drives used. By default, this is the number of drives configured in the mcf file for this library.

The example specifies that only one drive from the dog family set's library is used for staging files:

drives = dog 1

bufsize: Setting the Stage Buffer Size

By default, a file being staged is read into memory in a buffer before being restored from the archive media to disk cache. Use the bufsize directive to specify a buffer size and, optionally, to lock the buffer. These actions can improve performance. You can experiment with various buffer-size values. The directive has the following format:

bufsize= media-type buffer-size [lock]

where:

• media-type is one of the two-character, SAM-QFS media type identifiers listed in Appendix A and in the mcf man page.

• buffer-size is an integer in the range [2-8192]. This value is multiplied by the media-type_blksize value specified in the defaults.conf file. The higher the number specified for buffer-size, the more memory is used. The default is 16.

• lock mandates the use of locked buffers for the duration of each staging operation. This avoids overhead associated with locking and unlocking the staging buffer for each I/O request and improves performance. The lock parameter can cause an out-of-memory condition if specified on systems that have limited memory available. By default, locked buffers are not mandated, and the file system retains control over the archiving buffer.

  The lock argument is effective only if direct I/O is enabled for the staged file. For more information about enabling direct I/O, see the setfa, sam_setfa, and mount_samfs man pages.

logfile: Specifying a Staging Log File

You can request that the SAM-QFS software collect file-staging event information and write it to a log file. By default, no log file is written. The logfile directive specifies a log file to which the stager can write logging information. The stager writes one or more lines to the log file for each file staged. This line includes information such as the name of the file, the date and time of the stage, and the volume serial number (VSN). The directive has the following format:

logfile=filename [event-list]

where filename is the full path name for the log file and event-list is a space-delimited list of the event types that are to be logged:

• all logs all staging events.

• start logs when staging begins for a file.

• finish (default) logs when staging ends for a file.

• cancel (default) logs when the operator cancels a stage.

• error (default) logs staging errors.

The following directive creates a stage log in the /var/adm/ directory:

logfile=/var/adm/stage.log

Stager log entries take the following form:

status date time media-type volume position.offset inode filesize filename copy user group requestor equipment-number validation

where:

• status is S for starting, C for canceled, E for error, F for finished.

• date is the date in the form yyyy/mm/dd, where yyyy is a four-digit number representing the year, mm is a two-digit number representing the month, and dd is a two-digit number representing the day of the month.

• time is the time in the form hh:mm:ss format, where hh, mm, and ss are a two-digit numbers representing the hour, minute, and seconds, respectively.

• media-type is one of the two-character, SAM-QFS media type identifiers listed in Appendix A and in the mcf man page.

• volume is the volume serial number (VSN) of the media that holds the file being staged.

• position.offset is a pair of hexadecimal numbers separated by a dot that represent position of the start of the archive (tar) file on the volume and the offset of the staged file relative to the start of the archive file.

• inode is the inode number and generation number of the staged file, separated by a dot.

• filesize is the size of the staged file.

• filename is the name of the staged file.

• copy is the archive copy number of the copy that contains the staged file.

• user is the user that owns the file.

• group is the group that owns the file.

• requestor is the group that requested the file.

• equipment-number is the equipment ordinal number defined in the mcf file for the drive from which the file was staged.

• validation indicates whether the staged file is being validated (V) or not validated (-).

The example shows part of a typical stager log:

S 2014/02/16 14:06:27 dk disk01 e.76d 2557.1759 1743132 /sam1/testdir0/filebu 1 root other root 0 -
F 2014/02/16 14:06:27 dk disk01 e.76d 2557.1759 1743132 /sam1/testdir0/filebu 1 root other root 0 -
S 2014/02/16 14:06:27 dk disk02 4.a68 1218.1387 519464 /sam1/testdir1/fileaq 1 root other root 0 -
S 2014/02/16 14:06:43 dk disk01 13.ba5 3179.41 750880 /sam1/testdir0/filecl 1 root other root 0 -
F 2014/02/16 14:06:43 dk disk01 13.ba5 3179.41 750880 /sam1/testdir0/filecl 1 root other root 0 -

maxactive: Specifying the Number of Stage Requests

The maxactive directive enables you to specify the number of stage requests that can be active at any one time. The directive has the following format:

maxactive=number

where number is an integer in the range [1-500000]. The default is 4000.

The example specifies that no more than 500 stage requests can be in the queue simultaneously:

maxactive=500

copysel: Specifying the Copy Selection Order During Staging

The staging directive copysel sets the stager copy selection sequence per file system.

copysel=selection-order

where selection-order is a colon-delimited list of copy numbers in first-to-last order. The default selection order is 1:2:3:4.

For more information, see the stager.cmd man page. The example shows a stager.cmd file that sets non-default copy-selection orders for file systems samfs1 and samfs2:

logfile = /var/opt/SUNWsamfs/log/stager
drives = hp30 1
fs = samfs1
copysel = 4:3:2:1
fs = samfs2
copysel = 3:1:4:2

Preview Request Directives

When a SAM-QFS process requests a removable media volume that is not currently loaded into a drive, the request is added to the preview queue. Queued requests are satisfied in first-in-first-out (FIFO) order by default. But you can override the default behavior by editing the file /etc/opt/SUNWsamfs/preview.cmd. The SAM-QFS library-control daemon (sam-amld) reads these directives when it starts uses them until it stops. You cannot change queue priorities dynamically.

There are two types of directives:

• Global directives are placed at the top of the file and apply to all file systems.

• File-system directives take the form fs=directive and are specific to individual file systems

The following sections describe how to edit the preview.cmd file to control the preview queue:

• Global Directives

• Global and/or File System-Specific Directives

• Sample preview.cmd File

Global Directives

The following are purely global directives:

• vsn_priority: Adjusting Volume Priorities

• age_priority: Adjusting Priorities for Time Spent Waiting in the Queue

vsn_priority: Adjusting Volume Priorities

The vsn_priority directive increases the priority of volumes (VSNs) that are flagged as high-priority volumes by a specified value. The directive takes the following form:

vsn_priority=value

where value is a real number. The default is 1000.0.

You set the high priority flag on volumes using the command

chmed +p media-type.volume-serial-number

where media-type is one of the two-character, SAM-QFS media types listed in Appendix A and on the mcf man page and where volume-serial-number is the alphanumeric string that uniquely identifies the high-priority volume in the library. See the chmed man page for full information.

age_priority: Adjusting Priorities for Time Spent Waiting in the Queue

The age_priority directive changes the relative priority given to the amount of time that a request spends in the queue so that, for example, you can you keep older requests from being indefinitely superseded by newer, higher-priority, requests. The directive specifies a multiplier that changes the relative weighting of the time spent in the queue. It takes the following form:

age_priority=weighting-factor

where weighting-factor is a real number greater, less than, or equal to 1.0 and where:

• Values greater than 1.0 increase the weight given to time spent in the queue when calculating the aggregate priority.

• Values less than 1.0 reduce the weight given to time spent in the queue when calculating the total priority.

• Values equal to 1.0 do not change the relative weight given to time spent in the queue.

The default is 1.0.

Global and/or File System-Specific Directives

The following directives can be applied either globally or on a per-file system basis:

• hwm_priority: Adjusting Priorities When the Disk Cache is Nearly Full

• lwm_priority: Adjusting Priorities When the Disk Cache is Nearly Empty

• lhwm_priority: Adjusting Priorities as the Disk Cache Fills

• hlwm_priority: Adjusting Priorities as the Disk Cache Empties

hwm_priority: Adjusting Priorities When the Disk Cache is Nearly Full

The hwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when file system utilization exceeds the high water mark (hwm), the point where the releaser process starts and begins reclaiming the disk space occupied by files that have copies on archival media. In this situation, increasing the relative weight given to archiving lets the releasing process free more space for staged archive copies and new files. The directive takes the following form:

hwm_priority=weighting-factor

where weighting-factor is a real number. The default is 0.0.

lwm_priority: Adjusting Priorities When the Disk Cache is Nearly Empty

The lwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when file system utilization drops below the low water mark (lwm), the point where the releaser process stops. In this situation, reducing the relative weight given to archiving and thereby raising the priority of staging requests places more files in the disk cache, reduces demand for media mounts, and increases file system performance. The directive takes the following form:

lwm_priority=weighting-factor

where weighting-factor is a real number. The default is 0.0.

lhwm_priority: Adjusting Priorities as the Disk Cache Fills

The hlwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when the disk cache is filling up, and cache utilization is between the low and high water marks (lwm and hwm). In this situation, increasing the relative weight given to archiving lets the releasing process free more space for staged archive copies and new files. The directive takes the following form:

lhwm_priority=weighting-factor

where weighting-factor is a real number. The default is 0.0.

hlwm_priority: Adjusting Priorities as the Disk Cache Empties

The hlwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when the disk cache is emptying, and cache utilization is between the high and low water marks (hwm and lwm). In this situation, reducing the relative weight given to archiving and thereby raising the priority of staging requests places more files in the disk cache, reduces demand for media mounts, and increases file system performance. The directive takes the following form:

hlwm_priority=weighting-factor

where weighting-factor is a real number. The default is 0.0.

Sample preview.cmd File

The aggregate priority for any given media mount request is determined using the values set by all weighting factors, according to the following formula:

priority = vsn_priority + wm_priority + (age_priority * time-waiting-in-queue)

where wm_priority is the water mark priority currently in effect (hwm_priority, lwm_priority, hlwm_priority, or lhwm_priority) and time-waiting-in-queue is the number of seconds that the volume request has been queued. For a full explanation of priority calculation, see the PRIORITY CALCULATION section of the preview.cmd man page.

Under special conditions—when access to data is critically important or when removable media drives are in short supply—the directives in the preview.cmd file let you better match file-system activity to operational requirements and available resources. The integrity of stored data is unaffected by the settings in the preview.cmd file, so you can freely experiment until you find the proper balance between archiving and staging requests.

You may need to adjust the default priority calculation for either or both of the following reasons:

• to insure that staging requests are processed before archive requests, so that files are available when users and applications access them.

• to insure that archive requests gain top priority when a file system is about to fill up

The sample preview.cmd file below addresses the conditions highlighted above:

# Use default weighting value for vsn_priority:
vsn_priority=1000.0
age_priority = 1.0
# Insure that staging requests are processed before archive requests:
lwm_priority = -200.0
lhwm_priority = -200.0
hlwm_priority = -200.0
# Insure that archive requests gain top priority when a file system is about to fill up:
hwm_priority = 500.0

Negative weighting values for lwm_priority, lhwm_priority, and hlwm_priority insure that stage requests have priority over archive requests whenever space is available in the disk cache, so that data is always accessible when requested. If several requests are sitting in the queue for 100 seconds and the file system is below the low water mark, then:

• An archiving mount request for a priority volume has the aggregate priority 1000+(-200)+(1x100)=900

• A staging mount request for a priority volume has the aggregate priority 1000+0+(1x100)=1100

• A staging mount request for a non-priority volume has the aggregate priority 0+0+(1x100)=100

But when the disk cache is near capacity, archiving requests need to take priority. If too few files are archived as the file system fills, there is no space available for staging archived files or ingesting new ones. If several requests are sitting in the queue for 100 seconds and the file system is above the high water mark, then:

• An archiving mount request for a priority volume has the aggregate priority 1000+500+(1x100)=1600

• A staging mount request for a priority volume has the aggregate priority 1000+0+(1x100)=1100

• A staging mount request for a non-priority volume has the aggregate priority 0+0+(1x100)=100