This appendix lists directives and parameters used in Oracle Hierarchical Storage Manager configuration files. Each directive is a single text line composed of one or more comma-delimited fields. Related directives are stored together in Oracle HSM command (.cmd) files.
The remainder of this appendix provides an overview the three main configuration files and their associated directives:
See the Oracle HSM man pages for additional information.
Note that you can configure Oracle HSM command files from the command line, as described here, or by using the Oracle HSM Manager software. For information on Oracle HSM Manager, see the online help.
Archiving directives and parameters define the archive sets that control copying of files, the media used, and the overall behavior of the archiving software. They are grouped together in a configuration file, /etc/opt/SUNWsamfs/archiver.cmd.
There are three groups of archiving-related directives and parameters, each of which has its own section in the archiver.cmd file:
Archiving directives configure archiving operations.
Copy parameters configure the archiving operations for a specific copy of the archive set.
Volume Serial Number (VSN) association directives assign media to each specified copy operation.
Volume Serial Number (VSN) association directives are contained in their own section at the end of the archiver.cmd file, immediately following the copy parameters section.
When both a global directive and a more granular, more context-specific directive or parameter are in scope for the same file system or copy, the more granular rule overrides the more general.
If duplicate directives are entered, the value of the first instance that the archiver encounters overrides all subsequent values set for the same directive.
archiver.cmd FileAn archiver.cmd file consists of five sections:
Global directives specify archiver behavior for all configured Oracle HSM file systems.
Archive set definitions identify files that are archived as a group, by file system and starting directory, specify the number of copies, and control how long files are retained in the disk cache following archiving.
Copy parameters specify how each specified copy is made, either by archive set or for all archive sets, using the special directive allsets.
The optional volume serial number (VSN) pools section organizes archival media into sets of media that can be assigned to a copy operation by name, as a group. Pool members are defined with a space-delimited list of regular expressions that match volume labels.
The VSN directives section assigns media to copy operations, using a space-delimited list of pool names and/or regular expressions that match volume labels.
# /etc/opt/SUNWsamfs/archiver.cmd
#-----------------------------------------------------------------------
# Global Directives
archivemeta = off
examine = noscan
setarchdone = off
scanlist_squash = off
#-----------------------------------------------------------------------
# Archive Set Definitions
fs = hsmqfs
logfile = /var/adm/hsmqfs.archive.log
datafiles .
1 -norelease 15m
2 -norelease 15m
3 -norelease 30m
4 -norelease 30m
fs = dskvolqfs
logfile = /var/adm/dskvolqfs.archive.log
no_archive .
#-----------------------------------------------------------------------
# Copy Parameter Directives
params
allsets -sort path -offline_copy stageahead
allsets.1 -startage 6h -startsize 6G -startcount 500000
allsets.2 -startage 24h -startsize 20G -startcount 500000 -drives 5
allsets.3 -rearch_stage_copy 1
allsets.4 -rearch_stage_copy 1
endparams
#-----------------------------------------------------------------------
# VSN Pool Directives
dkarcpool dk DISKVOL[2-4][0-9]
tparcpool tp VOL[9-9][0-9][0-9]
crarcpool cr CLD0000[0-9][0-9][0-9
#-----------------------------------------------------------------------
# VSN Directives
vsns
datafiles.1 dk ARQFS1 DISKVOL[0-1][0-9] DISKVOL20 dkarcpool
datafiles.2 tp VOL[0-5][0-9][0-9]
datafiles.3 tparcpool
datafiles.4 crarcpool
endvsns
:wq
The archiving directives are listed alphabetically below.
archivemetaThe archivemeta directive controls whether file system metadata is archived.
The exact effects of the archivemeta directive depend on whether you are using a Version 1 or a Version 2 superblock:
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.
By default, metadata is not archived.
Global.
The archivemeta directive is entered in the global directives section at the start of the archiver.cmd file.
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.
archive-set-name pathThe combination of an archive set name and a path constitutes an archive set assignment directive that defines a group of files that should be archived together.
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 an administrator-defined name for the archive set.
path specifies the path to the top-most subdirectory that contains set members relative to the root directory of the file system (see the Options section for descriptions of the optional arguments).
The archive set assignment directive, archive-set-name path, specifies the path to a group of files that should be archived together and, optionally, additional characteristics of files that belong in the group.
Per file system.
Archive set assignment directives are entered in the archive set definitions section of the archiver.cmd file following a file system directive of the form fs = file-system-name .
archive-set-name is an administrator-defined name for the archive set. It must start with an upper or lower case letter and can contain up to 28 additional characters in any combination of upper and lower case letters [A-Za-z], numerals [0-9], and underscores (_). But do not use the reserved names no_archive and all.
path specifies the path to a starting subdirectory. All files in the starting directory and its subdirectories are archived as a group. To include all of the files in a file system, use the dot (.) character. The path must not include the root directory character, the leading slash (/).
-access (optional) re-archives 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.
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.
In the example, we do not have any strong need to selectively group files within the file system. So, to maximize performance and media utilization while minimizing overhead, we define a single archive set, allfiles. This archive set includes all files in path that starts in the file system root directory:
fs = hsmqfs1 logfile = /var/adm/hsmqfs1.archiver.log allfiles . ...
archive-set-name.copy-number media-specificationThe volume serial number association directive, archive-set-name.copy-number assigns archival media volumes to archive sets, either directly by VSN or by named media pool.
archive-set-name.copy-number media-type volume-specification archive-set-name.copy-number -pool vsn-pool-name
where:
archive-set-name is the name that an archive set assignment directive assigns 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]. See the archive set copy directive.
media-type is one of the two-character, Oracle HSM media type identifiers listed in Appendix A and in the mcf man page. See the archive set assignment directive.
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 the VSN pools and VSN pool definition directives.
archmaxThe archmax directive sets a maximum size for the files that are written to archival media.
archmax = media maximum-size
where:
media is one of the media types defined in Appendix A and on the mcf man page.
maximum-size is the maximum size of the archive file for a given media type.
The archmax directive sets a maximum size for tape archive (.tar) files. When maximum-size is reached, the archiver stops adding copies of data files to the archive file. Archiving continues with a new archive file.
Maximum sizes depend on the media in use. By default, the maximum archive file size for Oracle StorageTek T10000 and all LTO magnetic tape media is 22 gigabytes. For disk archives and optical media, the default is one gigabyte.
Global, per archive set, or per copy.
An archmax directive can be entered in the global directives section at the start of the archiver.cmd file or in the archive set definitions section, following an fs = file-system-name file system directive or as part of an archive set copy directive.
The defaults are optimal for general use.
Setting larger or smaller sizes for archive files may have both advantages and disadvantages. For example, if you are archiving to tape and set archmax to a large size, the tape drive stops and starts less often. But, when a large archive file does not quite fit into the space remaining on a volume, a lot of media capacity is wasted. To avoid problems, do not set the archmax directive to be more than 5 percent of the media capacity.
bufsizeThe bufsize directive changes the size of the archiving buffer, optionally, locks the buffer.
bufsize=media number-blocks [lock]
where:
media is one of the media types defined in Appendix A and in the mcf man page
number-blocks is a number in the range [2-1024]. The default is 4.
lock indicates whether the archiver can use locked buffers when making archive copies.
The bufsize directive lets you set a non-default size for the memory buffer that caches archival data for writing. It also lets you lock the buffer.
Buffering improves overall I/O performance by insuring that writes are made efficiently. To set the buffer size, the archiver multiples the number-blocks parameter by the dev_blksize that is specified for the media in the defaults.conf file. See the defaults.conf (4) man page for details.
If lock is specified, the archiver sets file locks on the archive buffer in memory for the duration of the copying 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.
By default, the archiver sets the buffer for 4 blocks and lets the file system lock the buffer as needed.
Global.
The bufsize directive is entered in the global directives section at the start of the archiver.cmd file. But the -bufsize and -lock copy parameters can be used to provide similar functionality on a per-copy basis.
For general use, the default buffering is usually optimal, so be careful when making changes.
If direct I/O is enabled and if large amounts of memory are available, using the bufsize directive with the lock argument can significantly reduce CPU overhead by eliminating the need to lock and unlock the buffer for each I/O request. Note, however, that -lock can cause an out-of-memory condition on systems that lack adequate memory. For information on enabling direct I/O, see the setfa (1), sam_setfa (3), and mount_samfs (1m) man pages.
copy-numberThe copy-number or archive set copy directive, tells the archiver to make an archival copy of the files specified by the immediately preceding archive set assignment directive, archive-set-name path.
copy-number [archive-age] [-release [attribute]] [-norelease] [-stage [attribute]] [unarchive-age]
where:
The archive set copy directive appears immediately after the corresponding archive set assignment directive.
copy-number is 1, 2, 3, or 4 (see the Options section for definitions of the optional arguments).
The archive set copy directive tells the archiver to make a copy of the corresponding archive set and, optionally, sets conditions for when the copy is made and how it is archived. Archive set copy directives begin with a copy-number, 1, 2, 3, or 4. The digit is followed by one or more arguments that specify archive characteristics for that copy.
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.
Per archive set.
The archive set copy directive immediately follows an archive set assignment directive in the archive set definitions section of the archiver.cmd file.
archive-ageThe 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).
-releaseThe optional -release parameter clears the Oracle HSM 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, where:
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.
-noreleaseThe optional -norelease parameter keeps the Oracle HSM releaser software from freeing the disk space used by archived files until all copies marked with -norelease have been made.
-release -noreleaseUsed together, -release -norelease require that the Oracle HSM software free the disk space used by files immediately after all copies that are flagged -release -norelease are made. Oracle HSM does not wait for the releaser process to run.
-stageThe optional -stage parameter is -a, -c copy-number, -n, -w, or -d, where:
-a 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-ageThe 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 = samqfs1
logfile = /var/adm/samqfs1.archive.log
allfiles .
1 -norelease 5m
2 -norelease 1h 7y6m
copy-number[archive-age]A copy-number and, optionally, an archive-age that directly follow an fs directive constitute a metadata copy directive. The metadata copy directive tells the archiver to make an extra copy of the file system metadata.
copy-number [archive-age]
where:
The directive immediately follows the fs directive that identifies the file system.
copy-number is the ordinal number of the extra copy (1 for the first, 2 for the second, etc.)
archive-age is an optional time that must elapse before the copy is made, expressed as one or more combinations of an integer and a unit. Units include s (seconds), m (minutes), h (hours), d (days), w (weeks), and y (years).
Each copy-number directive tells the archiver to make an extra copy of the file system metadata.
By default, Oracle HSM makes only a single copy.
Per file system.
The copy-number directive immediately follows the fs = file-system-name directive that identifies the file system.
Accept the default. Be cautious about specifying extra copies of file system metadata. If directories change frequently, specifying multiple metadata copies can cause excessive numbers of tape mount.
In the example, copy 1 of the metadata for the hsmqfs1 file system is made after 4 hours (4h) and copy 2 is made after twelve hours and 30 minutes(12h30m):
# General Directives archivemeta = off examine = noscan # Archive Set Assignments fs = hsmqfs1 1 4h 2 12h30m logfile = /var/adm/hsmqfs1.archiver.log allfiles . 1 -norelease 15m 2 -norelease 15m ...
drivesThe drives directive limits the number of drives that the archiver can use in a specified robotic library.
drives = media-library count
where:
media-library is the family set name of the automated library as defined in the mcf file.
count is the number of drives that the archiver can use.
The drives directive lets you control how many drives the archiver uses, so that some can be reserved for staging or other uses. By default, the archiver uses all of the drives in an automated library for archiving.
You can also use the archive set copy parameters -drivemax, -drivemin, and -drives for this purpose.
Global or per copy.
A drives directive can be entered in the global directives section at the start of the archiver.cmd file or in the archive set definitions section, as part of an archive set copy directive. The related copy parameters drivemax and drivemin provide similar per-copy functionality.
endparamsThe copy parameters directive endparams delimits the end of the copy parameters section of the archiver.cmd file. See params.
endvsnpoolsThe vsnpools directive marks the end of the section of the archiver.cmd file that defines groups of media that will be used for the same purposes. See vsnpools.
endvsnsThe endvsns directive marks the end of the media-assignment section of the archiver.cmd file.
vsn-association-directives
endvsns
where vsn-association-directives is one or more volume serial number association directives.
examineThe examine directive tells the archiver how to identify files that are ready for archiving.
examine = method
where method is one of the following directives:
noscan
scan
scandirs
scaninodes
The examine directive can specify one of four ways of detecting files that require archiving:
noscan, the default, specifies continuous archiving. After an initial scan, the archiver scans directories only when their contents change, requiring archiving. The archiver does not directory and inode information. This archiving method performs better than scan archiving, particularly for file systems with more than 1,000,000 files.
scan specifies legacy scan archiving. The archiver scans directories once and always scans inodes thereafter.
scandirs specifies scan archiving. The archiver always scans directories that do not have the no_archive attribute set, but never scans inodes.
scaninodes specifies scan archiving. The archiver always scans inodes, but never scans directories.
fsThe fs directive limits the scope of a set of archiving and copy parameters to the file system specified in the directive.
fs = file-system-name
where file-system-name is a the name of a file system defined in the mcf file.
The fs directive identifies a file system and marks the start of a list of archiver directives and parameters that apply to that file system only.
intervalIf a file system has not been configured for continuous archiving (the default), the interval directive defines the amount of time that the archiver waits after checking for unarchived files before it checks again.
interval = elapsed-time
where elapsed-time is the number of seconds that must elapse between one file system scan and the next.
If the examine directive is not set to noscan (continuous archiving) and if copy parameters do not set a start time for archiving, the interval directive supplies a default start time. When the number of seconds specified by the interval directive have elapsed since the archiver last scanned the file system, it scans again, using the method specified by the examine directive (scan, scandirs, or scaninodes).
The default is 600 seconds (10 minutes).
arrun and arscan commands issued via samcmd or the samu utility override the interval directive and start the specified action immediately.
The hwm_archive mount option can also override the interval directive and force archiving whenever the file system utilization passes the high-water mark for a given file system.
For more information about specifying the archive interval, see the archiver.cmd and mount_samfs man pages.
logfileThe logfile directive defines the path and name of the archiver log file.
The logfile directive tells the archiver to log every file that is archived, re-archived, or unarchived. The log file is thus a continuous record of archival action.
By default, the archiver does not maintain log files.
Global or per file system.
A logfile directive can be entered in the global directives section at the start of the archiver.cmd file or in the archive set definitions section, following a file system directive of the form fs = file-system-name.
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, rotate them, and back them up frequently. For more information, see the Oracle Hierarchical Storage Manager and StorageTek QFS Installation and Configuration Guide.
notifyThe notify directive identifies a script file that the archiver should use when notifying the administrator of events, notices, and alarm conditions.
The archiver executes the specified script when it encounters one of the alarm conditions that you have specified. These could include emerg, alert, crit, err, warning, notice, info, debug, or others.
You can either edit the default script to meet your notification requirements or you can substitute an alternative. For full information, see the archiver.sh (1m) man page.
The default path and file name to the notification script is /etc/opt/SUNWsamfs/scripts/archiver.sh.
ovflminThe ovflmin directive enables or disables the Oracle HSM volume overflow feature.
ovflmin = media minimum-file-size
where:
media is one of the media types defined in Appendix A and in the mcf man page.
minimum-file-size is the size of the smallest file that will be written to more than one archival volume.
When volume overflow is enabled, for a given media type, the archiver can create large archive files that span multiple volumes. When the size of an archive file exceeds the specified minimum, the archiver writes the remaining portion of the file to another volume of the same media type. The portion of the file written to each volume is called a section.
Volume overflow files do not generate checksums. For more information on using checksums, see the ssum man page.
By default, volume overflow is disabled.
Global or per file system.
The ovflmin directive can be entered in the global directives section at the start of the archiver.cmd file or in the archive set definitions section, as part of an archive set copy directive.
paramsThe copy parameters directive params delimit the start of the copy parameters section of the archiver.cmd file. See endparams.
scanlist_squashThe scanlist_squash directive enables or disables recursive searches for unarchived files.
The scanlist_squash directive tells the archiver if it should look for unarchived files by scanning from each parent directory down through the subdirectories in the directory tree.
The default value is off.
Global or per archive set.
The scanlist_squash directive can be entered in the global directives section at the start of the archiver.cmd file or in the archive set definitions section, as part of an archive set copy directive.
setarchdoneThe setarchdone global directive sets the archdone flag on files that will never be archived.
The setarchdone directive tells the archiver to set the archdone flag to on on all unarchived files that meet no archiving criteria will never be archived.
Normally, once the archiver has created all specified copies of an unarchived file, it sets an archdone flag on the file on. The flag tells subsequent archiving operations that the file has been archived and should thus be skipped until it is again modified. A file that meets none of the specified archiving criteria will never be archived, so the archiver never sets its archdone flag on.
When the setarchdone directive is on, the archiving process finds files that will never be archived and sets their archdone flags on. Such files will never be archived. While this can reduce future archiving overhead, the evaluation of files increases overhead immediately and may adversely affect performance.
The default is off if the examine directive is set to scandirs or noscan, on if the examine directive is set to scan or scaninodes.
vsn-pool-name media-type volume-specificationThe volume serial number (VSN) pool directive defines a named collection of archival media volumes that a volume serial number (VSN) association directive can specify as a unit.
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, Oracle HSM 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.
Media usage.
The VSN pools directives are entered in the archiver.cmd file following a vsnpools directive and before either an endvsnpools directive or the end of the file.
The example below specifies three pools, one for file system hsmqfs1, one for file system hsmqfs2, and a 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 hsmqfs1_pool li ^VOL7[0-9][0-9] hsmqfs2_pool li ^VOL8[0-9][0-9] scratch li ^VOL9[0-5] endvsnpools
vsnpoolsThe vsnpools directive marks the start of the section of the archiver.cmd file that defines groups of media that will be used for the same purposes. See endvsnpools.
vsnsThe vsns directive marks the start of the media-assignment section of the archiver.cmd file.
vsns
vsn-association-directives
where vsn-association-directives is one or more volume serial number association directives.
waitThe wait directive delays the start of archiving until an administrator issues a start signal.
The wait directive delays the start of archiving until an administrator issues a start signal using the samcmd command, the samu interface, or the Oracle HSM graphical user interface. Once the administrator gives the signal, archiving proceeds as specified by the remaining directives and parameters in the archiver.cmd file.
By default, the archiver starts automatically when the sam-fsd initialization command runs.
Global or per file system.
The wait directive can be entered in the global directives section at the start of the archiver.cmd file or in the archive set definitions section, following an fs = file-system-name directive.
All copy parameters take the same basic form:
archive-set-name[.copy-number] [options]Copy parameters define how the copies specified by an archive set are created.
archive-set-name[.copy-number] [options]
where:
archive-set-name is either the special directive allsets or the name of an archive set defined in the archive set definitions section of the archiver.cmd file.
The optional . operator followed by a copy-number limits the application of the specified copy parameters to the archive copy specified by copy-number in the archive set definitions. copy-number is an integer in the range 1-4.
options is one or more of the copy parameter options listed below.
The special allsets directive applies the specified copy parameters to all defined archive sets. It lets you simplify management and minimize configuration conflicts by applying a consistent, core set of copy options across all of your archive sets. Always set the allsets copy parameter first, so that its provisions are not overridden by later parameters.
RLimits application of the parameters to re-archived copies.
-startage timeSpecifies 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 countSpecifies the minimum number of files in an archive request. Archiving begins when the number of files awaiting archiving reaches this threshold.
By default, a -startcount value is not set.
-startsize sizeSpecifies 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 maximum-sizeLimits the size of an archive file to no more than maximum-size, where maximum-size is media-dependent.
The defaults are as follows:
for magnetic tape media, 512 megabytes.
for optical disc media, 5 megabytes.
-bufsize= media-type number-blocksSets the size of the write buffer that holds the archive file to number-blocks*dev_blksize, where:
number-blocks is the number of tape blocks buffered, an integer in the range 2-32.
dev_blksize is the block size specified for the media type in the defaults.conf file.
The default is 4.
-drivemax maximum-sizeLimits the amount of data archived using a single drive to no more than maximum-size megabytes, where maximum-size is an integer.
When multiple drives are specified using the -drives parameter, limiting the amount of data written to any one drive can help to balance workloads and improve overall drive utilization.
By default, maximum-size is not specified.
-drivemin minimum-sizeLimits the amount of data archived using one drive to at least minimum-size megabytes, where minimum-size is an integer.
Use the -drivemin option to optimize drive utilization. Set minimum-size large enough for the transfer time to significantly exceed the time required to load, position, and unload media and large enough to insure that multiple drives are only used when actually needed.
The default is the value of -archmax (if specified) or the value listed for the media type in the defaults.conf file.
-drives numberLimits the number of drives used for archiving to at most number, where number is an integer.
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.
The default is 1.
-fillvsnsForces 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.
-lockMandates 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 methodSpecifies how archive copies are made when files have already been released from the disk cache.
Files can be released from the disk cache once a single archive copy is made. In such cases, any additional copies specified must be made from the archive copy. Use the -offline_copy method option to balance the amount of extra space that you can afford to provide in the disk cache against the number of extra drives that you can afford to make available for use in copying archival media. Each method has advantages in some circumstances:
direct
The direct method copies files directly from the volume that holds the first copy to another volume.
This approach requires two drives.
This approach may require additional buffer space. So increase the value set by the stage_n_window mount option when using this method.
stageahead
The stageahead method stages the next file needed for the current archive copy into the disk cache while writing the current file out to archival media.
This approach requires two drives.
stageall
The stageall method stages all files needed for the current archive copy into the disk cache before writing any files out to archival media.
This approach requires only one drive.
This approach requires more space in the disk cache.
none
none stages files to the disk cache as needed before copying them out to archival media.
none is the default method.
-sort criterionArranges files by criterion before archiving them. The sorting criterion can be one of the following:
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.
By default, the archiver sorts by path.
-rsort criterionSorts files by criterion like -sort, but in reverse order.
-recycle_dataquantity sizeLimits 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 needs 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 (one gigabyte).
-recycle_hwm percentSets 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 percent.
-recycle_ignorePrevents actual recycling of any media in the archive set, while allowing recycling processes to run normally. Use the -recycle_ignore option to test recycling policies non-destructively before committing them to production use.
-recycle_mailaddr mail-addressDirects informational recycler messages to mail-address.
By default, recycler messages are not sent.
-recycle_mingainLimits selection of volumes for recycling to those which would increase their free space by at least the specified percentage.
The default value is 50 percent.
-recycle_vsncountLimits the number of volumes that the recycler schedules for rearchiving to count.
The actual number of volumes selected for recycling may also depend on the -recycle_dataquantity option.
The default is 1 percent. The option is ignored for disk media.
-recycle_minobsSets 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 default is 50. The parameter is ignored for removable media (see -recycle_hwm above).
-unarchageSets 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.
-tapenonstopWrites 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, Oracle HSM 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 keywordReserves 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.
fsIncludes the file system name in the reserve name: arset.1 -reserve fs.
setIncludes the archive set name from the archive set assignment directive in the reserve name: all -reserve set.
dirIncludes the first 31 characters of the directory path specified in the archive set assignment directive in the reserve name.
userIncludes the user name associated with the archive file: arset.1 -reserve user.
groupIncludes the group name associated with the archive file: arset.1 -reserve group.
-priority multiplier rankingChanges the archiving priority of files when used with the sort priority parameter listed above.
See the archiver and archiver.cmd man pages for a full explanation of priorities.
Exercise caution when using the -reserve keyword option. 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.
Staging directives configure archiving operations. They may apply globally, to all file systems or they may apply to a specific file system or archive set, depending on the directive.
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.
stager.cmd FileThe directives in the stager.cmd file override the default behaviors. You can configure the stager to stage files immediately, to never stage files, to partially stage files, 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.
If you are using the Oracle HSM 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
Staging directives are listed alphabetically below. For additional information about stager directives, see the stager.cmd man page.
drivesThe drives directive specifies the number of drives that the stager can use when copying back files from archival media to the disk cache.
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.
The drives directive sets limits to the number of drives that the stager can use.
By default, count is the number of drives listed for the library in the mcf file, so the stager uses all available drives unless otherwise directed.
bufsizeThe bufsize directive changes the size of the archiving buffer, optionally, locks the buffer.
bufsize=media number-blocks [lock]
where:
media is one of the media types defined in Appendix A and in the mcf man page
number-blocks is a number in the range [2-8192].
lock indicates whether the archiver can use locked buffers when making archive copies.
The bufsize directive lets you set a non-default size for the memory buffer where the stager caches file data that it reads from archival media before writing to disk cache. It also lets you lock the buffer.
Buffering improves overall I/O performance by insuring that writes are made efficiently. To set the buffer size, the archiver multiples the number-blocks parameter by the dev_blksize that is specified for the source media in the defaults.conf file. See the defaults.conf (4) man page for details.
If lock is specified, the archiver sets file locks on the archive buffer in memory for the duration of the copying operation.
By default, the stager sets the buffer for 16 blocks and lets the file system lock the buffer as needed.
For general use, the default buffering is usually optimal, so be careful when making changes.
If you do set a new buffer size, specify a number of blocks that is consistent with the amount of memory installed in the system. The higher the number specified for number-blocks, the more memory the stager uses.
If direct I/O is enabled and if large amounts of memory are available, using the bufsize directive with the lock argument can significantly reduce CPU overhead by eliminating the need to lock and unlock the buffer for each I/O request. Note, however, that -lock can cause an out-of-memory condition on systems that lack adequate memory. For information on enabling direct I/O, see the setfa (1), sam_setfa (3), and mount_samfs (1m) man pages.
logfileThe logfile directive defines the path and name of the stager log file.
logfile = path-and-name [event-list]
where:
path-and-name is the absolute path and name of the file.
event-list is an optional, space-delimited list of event types.
The logfile directive tells the stager to log every file that is staged. The log file typically contains the name of the file, the date and time, and the volume serial number (VSN) of the source media. The optional event list can specify one or more of the following event types for inclusion in the log:
allLogs all staging events.
startLogs the time when the archiver starts staging the file.
finishLogs the time when the archiver finishes staging a file.
cancelLogs cancellations of staging operations.
errorLogs staging errors.
By default, the archiver does not maintain log files. If logging is specified without an event list, finish, cancel, and error events are logged by default.
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, Oracle HSM 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 first example shows a logfile directive that creates a stage log in the /var/adm/ directory:
logfile=/var/adm/stage.log
The second example shows part of a typical stager log:
S 2016/11/09 14:06:27 dk disk01 e.76d 2557.1759 1743132 /hsmfs/dat0/3f 1 root other root 0 - F 2016/11/09 14:06:27 dk disk01 e.76d 2557.1759 1743132 /hsmfs/dat0/b9 1 root other root 0 - S 2016/11/09 14:06:27 dk disk02 4.a68 1218.1387 519464 /hsmfs/dat1/a0 1 root other root 0 - S 2016/11/09 14:06:43 dk disk01 13.ba5 3179.41 750880 /hsmfs/dat0/cl 1 root other root 0 - F 2016/11/09 14:06:43 dk disk01 13.ba5 3179.41 750880 /hsmfs/dat0/cf 1 root other root 0 -
maxactiveThe maxactive directive lets you specify the number of stage requests that can be active at any one time.
copyselThe copy selection directive, copysel, lets you specify the order in which the stager selects the archive set copy that it will use when staging a requested file to the disk cache.
copysel=selection-order
where selection-order is a colon-delimited list of copy numbers in first-to-last order.
The copysel directive lets you override the stager's usual selection order.
Normally, the stager first looks at the first copy of the corresponding archive set. If it finds usable file, the stager copies it back to the disk cache. If not, it moves on to the next copy, until it either finds a usable copy of the file or exhausts all available copies. For more information, see the stager.cmd (4) man page.
So, by default, the copy selection order 1:2:3:4.
When an Oracle HSM 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 Oracle HSM library-control daemon (sam-amld) reads these directives when it starts and uses them until it stops. You cannot change queue priorities dynamically.
There are three 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.
This section lists the global and file system-specific preview directives and concludes with a sample preview.cmd file.
preview.cmd fileThe 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:
# /etc/opt/SUNWsamfs/preview.cmd # 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
The following are purely global directives:
age_priorityThe age_priority directive changes the relative priority given to the amount of time that a request spends in the queue.
age_priority=weighting-factor
where weighting-factor is a real number greater, less than, or equal to 1.0.
The age_priority directive adjusts the priorities of files so that you can you keep older requests from being indefinitely superseded by newer, higher-priority, requests or, conversely, keep newer, higher priority requests from being blocked by older requests. The directive specifies a multiplier that changes the relative weighting of the time spent in the queue.
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.
hlwm_priorityThe hlwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when the disk cache is emptying.
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 default is 0.0.
hwm_priorityThe hwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when file system 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 default is 0.0.
lhwm_priorityThe hlwm_priority directive adjusts the relative weight given to archiving requests versus staging requests 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:
The default is 0.0.
lwm_priorityThe lwm_priority directive adjusts the relative weight given to archiving requests versus staging requests when the file system 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 default is 0.0.
vsn_priorityThe vsn_priority directive increases the priority of volumes (VSNs) that are flagged as high-priority volumes by a specified value.
vsn_priority =value
where value is a real number.
The vsn_priority directive increases the priority of previously identified volumes by a specified amount. Priority flags are set using the chmed (1m) command:
chmed +p media-type.volume-serial-number
where:
media-type is one of the two-character, Oracle HSM media types listed in Appendix A and on the mcf man page.
volume-serial-number is the alphanumeric string that uniquely identifies the high-priority volume in the library.
The default priority value for a volume is 1000.0.