Oracle® Hierarchical Storage Manager and StorageTek QFS Software Installation and Configuration Guide Release 6.0 E78137-01 |
|
Previous |
Next |
This appendix lists directives that configure Oracle Hierarchical Storage Manager file systems and related software operations. 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 kinds of 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.
This section provides usage information for the archiving directives that make up the archiver.cmd
file. Archiving directives define the archive sets that control copying of files, the media used, and the overall behavior of the archiving software.
There are four basic types of archiving 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 directives control the overall archiver operation and enable you to optimize operations for all configured file systems. Global directives consist of either a solitary keyword or a keyword followed by an equal sign (=
) and additional data fields. Global directives start the archiver.cmd
file and end at the first of the File System Directives.
archivemeta
: Controlling Whether Metadata Is ArchivedThe 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 FilesThe 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 SizeBy 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 in some situations. 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 ArchivingBy 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=
media-library
count
where media-library
is the family set name of the automated library as defined in the mcf
file and count
is the number of drives allowed for archiving use.
You can also use the archive set copy parameters -drivemax
, -drivemin
, and -drives
for this purpose. For more information, see "Archive Copy Directives".
examine
: Controlling Archive ScansThe 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 an initial scan, directories are scanned only when 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. After the initial scan of file-system directories, inodes are always scanned.
scandirs
specifies scan archiving. Directories are always scanned. Inode information is not scanned.
The archiver does not scan directories that have the no_archive
attribute set. So you can reduce scanning time by setting this attribute on directories that contain files that do not change.
scaninodes
specifies scan archiving. Inodes are always scanned. Directory information is not scanned.
interval
: Specifying an Archive IntervalPeriodically, the archiver checks the status of all mounted, archive-enabled file systems. The timing is controlled by the archive interval, 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. The archiver commences its scan when the file system utilization passes the high-water mark. 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 FileThe 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. For more information, see the Oracle Hierarchical Storage Manager and StorageTek QFS Installation and Configuration Guide.
notify
: Renaming the Event Notification ScriptThe 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 OverflowWhen 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 should 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 ConsolidationThe scanlist_squash
parameter controls scanlist consolidation. The default setting is off
. This parameter can be either global or file system-specific.
When on
, this directive consolidates scan lists for the subdirectories in a directory tree, so that the archiver scans recursively from the common parent directory down. If many files and subdirectories have changed within a file system, scan-list consolidation can significantly reduce archiving performance.
setarchdone
: Controlling the Setting of the archdone
FlagThe setarchdone
global directive controls whether the archdone
flag is sete on files that will never be archived. This directive has the following format:
setarchdone=
state
where state
is either on
or off
. The default is off
if the examine
directive is set to scandirs
or noscan
.
The archdone
flag tells the archiving process to ignore the flagged file. Normally, when all specified copies of a file have been created, the archiving process sets the archdone
flag so that subsequent archiving operations skip the file until and unless it is later modified.
But when the setarchdone
is set on
, the archiving process identifies and flags unarchived files that meet no archiving criteria will thus never be archived. While this can reduce future archiving overhead, the evaluation of files increases overhead immediately and may adversely affect performance.
wait
: Delaying Archiver StartupThe wait
directive causes the archiver to wait for a start signal from the samcmd
command, the samu
interface, or the Oracle HSM Manager. This directive has the following format:
wait
By default, the archiver starts automatically when the sam-fsd
initialization command runs.
The wait
directive can also be set for an individual file system.
File system directives define archiving behavior for specific file systems:
fs
: Specifying a File SystemEach 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 MetadataFile system metadata includes path names in the file system. 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). If directories change frequently, specifying multiple metadata copies may cause the file system to mount metadata tape volumes too frequently. So, by default, Oracle HSM 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 Assignmentsfs = samma1
1 4h
2 12h
interval
, logfile
, scanlist
as File System DirectivesSeveral 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:
archive-set-name
: the Archive Set Assignment DirectiveThe 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 Oracle HSM special archive sets no_archive
and all
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
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
.
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 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
. 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 Oracle HSM 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 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.
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 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 allfiles.1 -startage 10m -startsize 10M -drives 10 -archmax 1G allfiles.2 -startage 1h -startsize 1G -drives 2 -archmax 10G -reserve setendparams
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_mingain
percentage
]
[
-recycle_vsncount
count
]
[
-recycle_minobs
percentage
]
[
-unarchage
time_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 re-archived 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, 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
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: all -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.402823466x1038 to 3.402823466x1038) 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
, re-archive
, reqrelease
, size
, stage_loaded
, and stage_overflow
.
See the archiver
and archiver.cmd
man pages for more information on priorities.
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, 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.
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
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, 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.
-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 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 Oracle HSM 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.
stager.cmd
FileIn 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 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
drives
: Specifying the Number of Drives for StagingBy 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 SizeBy 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, Oracle HSM 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 FileYou can request that the Oracle HSM 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, 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 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 RequestsThe 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 StagingThe 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
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 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:
The following are purely global directives:
vsn_priority
: Adjusting Volume PrioritiesThe 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 +pmedia-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 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 QueueThe 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
.
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
hlwm_priority
: Adjusting Priorities as the Disk Cache Empties
hwm_priority
: Adjusting Priorities When the Disk Cache is Nearly FullThe 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 EmptyThe 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 FillsThe 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 EmptiesThe 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
.
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:
# 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