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.
archivemeta
The 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
path
The 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-specification
The 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.
archmax
The 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.
bufsize
The 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-number
The 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-age
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).
-release
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
, 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.
-norelease
The 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
-norelease
Used 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.
-stage
The 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-age
The 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 ...
drives
The 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.
endparams
The copy parameters directive endparams
delimits the end of the copy parameters section of the archiver.cmd
file. See params
.
endvsnpools
The 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
.
endvsns
The 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.
examine
The 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.
fs
The 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.
interval
If 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.
logfile
The 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.
notify
The 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
.
ovflmin
The 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.
params
The copy parameters directive params
delimit the start of the copy parameters section of the archiver.cmd
file. See endparams
.
scanlist_squash
The 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.
setarchdone
The 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-specification
The 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
vsnpools
The 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
.
vsns
The 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.
wait
The 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.
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, a -startcount
value 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
maximum-size
Limits 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-blocks
Sets 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-size
Limits 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-size
Limits 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
number
Limits 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
.
-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.
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
criterion
Arranges 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
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 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
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
percent.
-recycle_ignore
Prevents 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-address
Directs informational recycler messages to mail-address
.
By default, recycler messages are not sent.
-recycle_mingain
Limits 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_vsncount
Limits 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_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 default is 50
. The parameter is ignored for removable media (see -recycle_hwm
above).
-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
.
-priority
multiplier
ranking
Changes 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.
drives
The 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.
bufsize
The 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.
logfile
The 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:
all
Logs all staging events.
start
Logs the time when the archiver starts staging the file.
finish
Logs the time when the archiver finishes staging a file.
cancel
Logs cancellations of staging operations.
error
Logs 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 -
maxactive
The maxactive
directive lets you specify the number of stage requests that can be active at any one time.
copysel
The 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_priority
The 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_priority
The 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_priority
The 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_priority
The 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_priority
The 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_priority
The 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
.