C H A P T E R 4

Archiving

Archiving is the process of copying a file from a Sun StorEdge SAM-FS file system to a volume that resides on a removable media cartridge or on a disk partition of another file system. Throughout this chapter, the term archive media is used to refer to the various cartridges or disk slices to which archive volumes are written. The Sun StorEdge SAM-FS archiving capabilities include many features, such as those that you can use to specify that files be archived immediately, to specify that files never be archived, and to perform other tasks.

This chapter describes the archiver's theory of operations, provides general guidelines for developing archive policies for your site, and explains how to implement policies by creating an `archiver.cmd` file.

The following topics are presented:

- Archiver - Theory of Operations

- The archiver.cmd File

- The archiver.cmd Directives

- Disk Archiving

- Archiver Examples

- Archiver Guidelines

- Troubleshooting the Archiver

##

Archiver - Theory of Operations

The archiver automatically writes Sun StorEdge SAM-FS files to archive media. Operator intervention is not required to archive and stage the files. Files are archived to a volume on the archive media, and each volume is identified by a unique identifier called a volume serial name (VSN). Archive media can contain one or more volumes. To identify an individual volume, the media type and VSN must be specified.

The archiver starts automatically when a Sun StorEdge SAM-FS file system is mounted. You can customize the archiver's operations for your site by inserting archiving directives into the following file:

`/etc/opt/SUNWsamfs/archiver.cmd`

The `archiver.cmd` file does not need to be present for archiving to occur. In the absence of this file, the archiver uses the following defaults:

- All files are archived to available volumes.

- The archive age for all files is 4 minutes. The archive age is the amount of time since a file's last modification.

- The archive interval is 10 minutes. The archive interval is the amount of time that elapses between complete archiving processes.

The following sections describe the concept of an archive set and explain the operations performed during the archiving process.

### Archive Sets

An archive set identifies a group of files to be archived. Archive sets can be defined across any group of file systems. Files in an archive set share common criteria that pertain to the size, ownership, group, or directory location. The archive sets control the destination of the archive copy, how long to keep the copy archived, and how long to wait before archiving the data. All files in an archive set are copied to the volumes associated with that archive set. A file in the file system can be a member of one and only one archive set.

As files are created and modified, the archiver copies them to archive media. Archive files are compatible with the standard UNIX `tar`(1) format. This ensures data compatibility with the Sun Solaris operating system (OS) and other UNIX systems. This format includes the file access data (inode information) and the path to the file. If a complete loss of your Sun StorEdge SAM-FS environment occurs, the `tar`(1) format allows file recovery using standard UNIX tools and commands. The archiving process also copies the data necessary for Sun StorEdge SAM-FS file system operations. This data consists of directories, symbolic links, the index of segmented files, and archive media information.

In the remainder of this section, the term files refers to both file data and metadata. The terms file data and metadata are used only when a distinction is required. The term file system refers to a mounted Sun StorEdge SAM-FS file system.

Archive set names are determined by the administrator and are virtually unlimited with the following exceptions:

- There are two reserved archive set names: `no_archive` and `allsets`.

The `no_archive` archive set is defined by default. Files selected to be in this archive set are never archived. Files in a temporary directory, such as `/sam1/tmp`, for example, might be included in the `no_archive` archive set.

The `allsets` archive set is used to define parameters that apply to all archive sets.

- Archive sets named for each Sun StorEdge SAM-FS file system are reserved for control structure information. Sun StorEdge SAM-FS file systems provide a default archive set for each file system. For each file system, both the metadata and data files are archived. The file system archive set encompasses the directory and link information and any files that are not included in another archive set. The default archive sets are given the names of their associated file systems and cannot be changed. For example, `samfs1` would be the archive set name for a file system configured and named as `samfs1`.

- Archive set names are limited to 29 characters. The characters are limited to the 26 uppercase and lowercase letters, the digits 0 through 9, and the underscore character (_).

### Archiving Operations

By default, the archiver makes one copy of each archive set, but you can request up to four archive copies for each archive set. An archive set and a copy number become a synonym for a collection of volumes. The archive copies provide duplication of files on separate volumes.

To ensure that files are complete before archiving, the archiver waits a specified period of time after the file is modified before archiving it. As mentioned previously, this period of time is called the archive age.

The data in a file must be modified before the file is considered to be a candidate for archiving or rearchiving. A file is not archived if it is only accessed. For example, issuing a `touch`(1) or an `mv`(1) command on a file does not cause it to be archived or rearchived. Issuing an `mv`(1) command alters the file name but not the file data, and this can have ramifications in a disaster recovery situation if you are restoring from `tar`(1) files. For more information on disaster recovery, see the Sun QFS, Sun SAM-FS, and Sun SAM-QFS Disaster Recovery Guide.

Files are selected for archiving based on their archive age. The archive age can be defined for each archive copy.

Users can change the default time references on their files to values far in the past or future by using the `touch`(1) command. This can cause unexpected archiving results, however. To avoid such problems, the archiver adjusts the references so that they are always in the following range:

creation_time < time_ref < time_now

The following sections describe the steps taken by the archiver from the initial file scan to the file copy process.

#### Step 1: Identifying Files to Archive

There is a separate `sam-arfind` process for each mounted file system. The `sam-arfind` process monitors each file system to determine the files that need archiving. The file system notifies its `sam-arfind` process whenever a file is changed in a manner that would affect its archival state. Examples of such changes are file modification, rearchiving, unarchiving, and renaming. When notified, the `sam-arfind` process examines the file to determine the archive action required.

The `sam-arfind` process determines the archive set to which the file belongs by using the file properties descriptions. The characteristics used for determining a file's archive set include the following:

- The directory path portion of the file's name and, optionally, the complete file name using a regular expression

- The user name of the file's owner

- The group name of the file's owner

- A minimum file size

- A maximum file size

If the archive age of the file for one or more copies has been met or exceeded, `sam-arfind` adds the file to one or more archive requests for the archive set. The archive request is the collection of files that all belong to the same archive set. Separate archive requests are used for files being rearchived. This allows scheduling to be controlled independently for files not yet archived and for those being rearchived. The archive request is a file that resides in the following directory:

`/var/opt/SUNWsamfs/archiver/file_sys/ArchReq`

The files in this directory are binary files, and you can display them by using the `showqueue`(1M) command.

The archive request is sometimes referred to as an ArchReq.

If the archive age of the file for one or more copies has not been met, the directory in which the file resides and the time at which the archive age is reached is added to a scan list. Directories are scanned as the scan list times are reached. Files that have reached their archive age are added to archive requests.

If a file is offline, the `sam-arfind` process selects the volumes to be used as the source for the archive copy. If the file copy is being rearchived, the `sam-arfind` process selects the volume containing the archive copy that is being rearchived.

If a file is segmented, only those segments that have changed are selected for archival. The index of a segmented file contains no user data, so it is treated as a member of the file system archive set and is archived separately.

The archive priority is computed from file property characteristics and from file property multipliers associated with the archive set. Essentially, the computation is as follows:

archive_priority = the sum of (file_property_value * property_multiplier)

Most file_property_value numbers are 1 or 0, as the property is `TRUE` or `FALSE`. For instance, the value of the property copy 1 is 1 if archive copy 1 is being made. The values of copy 2, copy 3, and copy 4 are, therefore, 0.

Others, such as archive age and file size, can have values other than 0 or 1.

The property_multiplier values are determined from the `-priority` parameters for the archive set. Various aspects of a file, such as age or size, can be given values so that your site can alter the archive request's priority. For more information on the `-priority` parameter, see the `archiver.cmd`(4) man page.

The archive_priority and the property multipliers are floating-point numbers. The default value for all property multipliers is 0.0. The archive request is set to the highest file priority in the archive request.

There are two methods by which files are marked for archiving: continuous archiving and scanning. With continuous archiving, the archiver works with the file system to determine which files need to be archived. With scanning, the archiver periodically peruses the file systems and selects files for archiving. The following sections describe these methods.

##### Continuous Archiving

Continuous archiving is the default archiving method (`examine=noscan`). With continuous archiving, you can specify scheduling start conditions for an archive set by using the `-startage`, `-startcount`, and `-startsize` parameters. These conditions allow you to optimize archive timeliness versus archive work done.

- Example 1. If it takes an hour to create files that should be archived together, you can set the `-startage` parameter to 1 hour (`-startage 1h`) to ensure that all files are created before scheduling the Archive Request.

- Example 2. You can specify a `-startsize` of 150 gigabytes (`-startsize 150g`) to direct the archiver to wait until 150 gigabytes of data are ready to be archived.

- Example 3. If you know that 3000 files will be generated for archival, then specify `-startcount 3000` to ensure that the files get archived together.

When any of the scheduling start conditions are reached, the `sam-arfind` process sends each archive request to the archiver daemon, `sam-archiverd`, to be scheduled for file copying to archive media.

##### Scanned Archiving

As an alternative to continuous archiving, you can specify `examine=scan` to direct `sam-arfind` to examine files for archival using scanning. Files needing archival are placed into archive requests. The `sam-arfind` process scans each file system periodically to determine which files need archiving. The first scan that `sam-arfind` performs is a directory scan. During this scan, `sam-arfind` descends recursively through the directory tree. Each file is examined, and the file status flag `archdone` is set if the file does not need archiving. During successive scans, the `.inodes` file is scanned. Only those inodes with the `archdone` flag not set are examined.

When the file system scanning has been completed, the `sam-arfind` process sends each archive request to the archiver daemon, `sam-archiverd`, to be scheduled for file copying to archive media. The `sam-arfind` process then sleeps for the duration specified by the `interval=`time directive. At the end of the interval, the `sam-arfind` process resumes scanning.

#### Step 2: Composing Archive Requests

When archive requests are received by the `sam-archiverd` daemon, they are composed. This step describes the composition process.

All the files in an archive request might not be archived at one time. This can be caused by the capacity of the archive media or by the controls specified in the archiver command file. Composing is the process of selecting the files to be archived from the archive request at one time. When the archive copy operation has been completed for an archive request, the archive request is recomposed if files remain to be archived.

The `sam-archiverd` daemon orders the files in the archive requests according to certain default and site-specific criteria. The default operation is to archive all the files in an archive request to the same archive volumes in the order that they were found during the file system scan. The site-specific criteria allow you to control the order in which files are archived and how they can be distributed on volumes. These criteria are called archive set parameters, and the order in which they are evaluated is as follows: `-reserve`, `-join`, `-sort`, `-rsort` (performs a reverse sort), and `-drives`. For more information on these parameters, see the `archiver.cmd`(4) man page.

If the archive request belongs to an archive set that has `-reserve` owner specified, the `sam-archiverd` daemon orders the files in the archive request according to the file's directory path, user name, or group name. This action is controlled by the `-reserve` parameter for the archive set. The files belonging to the first owner are selected for archiving. The remaining files are archived later.

If the archive request belongs to an archive set that has the `-join` method specified, the `sam-archiverd` daemon groups the files together according to the `-join` method specified. If a `-sort` or `-rsort` method is also specified, then the `sam-archiverd` daemon sorts the files within each group according to the `-sort` or `-rsort` method. The archive request is joined and sorted.

Each group of joined files is treated as if it were a single file for the remainder of the composing and scheduling processes.

If the archive request belongs to an archive set that has a `-sort` or `-rsort` method specified, the `sam-archiverd` daemon sorts the files according to the sort method specified on the `-sort` or `-rsort` parameter. Depending on the sort method, the `sam-archiverd` daemon tends to keep files together based on the sort method, age, size, or directory location. By default, the archive requests are not sorted, so the files are archived in the order in which they are encountered during the file system scan.

The `sam-archiverd` daemon determines whether the files are online or offline. If both online and offline files are in the archive request, the online files are selected for archiving first.

If the archive request was not required to be joined or sorted by a sort method, the offline files are ordered by the volume upon which the archive copies reside. This ensures that all files (within each archive set) on the same volume are staged at the same time in the order in which they were stored on the media. When more than one archive copy of an offline file is being made, the offline file is not released until all required copies are made. All the files to be staged from the same volume as the first file are selected for archiving.

Note that using the `-join`, `-sort`, or `-rsort` parameters can have a negative effect on performance when archiving offline files. This is due to the possiblity that the order of the files to be archived does not match the order of the volumes needed for the offline files. It is recommended that you use the `-join`, `-sort`, or `-rsort` parameters only for the first archive copy to be made. Other copies will most likely maintain the order of the first copy if enough archive media is available when the copies are started.

The archive requests are entered in the `sam-archiverd` daemon's scheduling queue.

#### Step 3: Scheduling Archive Requests

The scheduler in the `sam-archiverd` daemon executes on demand when the following conditions exist:

- An archive request is entered in the scheduling queue.

- The archiving for an archive request has been completed.

- A change in media status is received from the catalog server.

- A message is received that changes the state of the archiver.

The archive requests in the scheduling queue are ordered by priority. Each time the scheduler executes, all archive requests are examined to determine if they can be assigned to a `sam-arcopy` process to have the files copied to archive media.

There must be drives available to use for making file copies. There must be volumes available that can be used by the archive set and have sufficient space to hold the files in the archive request.

##### Drives

If the archive set has the `-drives` parameter specified, the `sam-archiverd` daemon divides the selected files in the archive request among multiple drives. If the number of drives available at this time is less than that specified by the `-drives` parameter, the smaller number is used.

If the total size of files in the archive request is less than the `-drivemin` value, only one drive is used. The `-drivemin` value is either the value specified by the `-drivemin` parameter or it is the `archmax` value.

The `archmax` value is specified by the `-archmax` parameter or the value defined for the media. For more information on the `-archmax` parameter and the `archmax=` directive, see the `archiver.cmd`(4) man page.

If the total size of files in the archive request is more than the `-drivemin` value, then the following value is computed: drive_count = total_size / drivemin. If drive_count is less than the number of drives specified by the `-drives` parameter, then drive_count becomes the number of drives to use.

Drives can take differing amounts of time to archive files. You can use the `-drivemax` parameter to obtain better drive utilization. The `-drivemax` parameter requires you to specify the maximum number of bytes to be written to a drive before rescheduling that drive for more data.

##### Volumes

There must be a volume, or volumes, with enough space to hold at least some of the files in the archive request. The volume that has most recently been used for the archive set is used if there is enough space. Also, the volume must not be in use by the archiver.

If a volume usable for the archive set is presently busy, another is selected. This is true unless the `-fillvsns` parameter is specified. In this case, the archive request is not schedulable.

If an archive request is too big for one volume, the files that can fit on the volume are selected to be archived to the volume. If the archive request contains files that are too big to fit on one volume, and volume overflow for the archive request is not selected, the files cannot be archived. An appropriate message for this condition is sent to the log.

You can specify volume overflow for the archive set (by using the `-ovflmin` parameter) or for the media (by using the `ovflmin=` directive). For more information on the `-ovflmin` parameter and the `ovflmin=` directive, see the `archiver.cmd`(4) man page. This specification, `ovflmin`, determines the minimum size for files to overflow media. An `ovflmin` specified for the archive set takes precedence over a media-defined `ovflmin`. If the size of the files is less than `ovflmin`, the files cannot be archived. An appropriate message for this condition is sent to the log.

If the size of the files is more than `ovflmin`, then additional volumes are assigned as required. The additional volumes are selected in order of decreasing size in order to minimize the number of volumes required for the file.

If no usable volumes can be found for the archive request, the archive request waits.

Certain properties, such as whether or not the file is online or offline, are used in conjunction with the archive priority (computed in Step 1) when determining the scheduling priority for a particular archive request. For more information on customizing the property multiplier, see the `-priority` parameters described on the `archiver.cmd`(4) man page.

For each archive request, the `sam-archiverd` daemon computes the scheduling priority by adding the archive priority to multipliers associated with various system resource properties. These properties are associated with the number of seconds that the archive request has been queued, whether or not the first volume to be used in the archiving process is loaded into a drive, and so on.

Using the adjusted priorities, the `sam-archiverd` daemon assigns each ready archive request to be copied.

#### Step 4: Archiving the Files in an Archive Request

When an archive request is ready to be archived, the `sam-archiverd` daemon steps through each archive request to mark the archive file (tarball) boundaries so that each archive file's size is less than the `-archmax` target_size specification. If a single file is larger than target_size, it becomes the only file in an archive file.

For each archive request and each drive to be used, the `sam-archiverd` daemon assigns the archive request to a `sam-arcopy` process to copy the files to the archive media. If a single file is larger than target_size, it becomes the only file in an archive file. The archive information is entered into the inode.

If archive logging is enabled, an archive log entry is created.

If the file was staged, the disk space is released. This process continues until all files in the list have been archived.

A variety of errors and file status changes can prevent a file from being successfully copied. This can include read errors from the cache disk and write errors to the volumes. Status changes include modification since selection, file open for write, and file removed.

When the `sam-arcopy` process exits, the `sam-archiverd` daemon examines the archive request. If any files have not been archived, the archive request is recomposed.

#### Sample Default Output

CODE EXAMPLE 4-1 shows sample output is from running the `archiver`(1M) `-l command`.

CODE EXAMPLE 4-1 Output from the `archiver` (1M) `-l` Command
    # archiver
    Archive media:
    default:mo
    media:mo archmax:5000000
    media:lt archmax:50000000
    Archive devices:
    device:mo20 drives_available:1 archive_drives:1
    device:lt30 drives_available:1 archive_drives:1
    Archive file selections:
    Filesystem samfs1:
    samfs1  Metadata
        copy:1  arch_age:240
    big  path:. minsize:512000
        copy:1  arch_age:240
    all  path:
        copy:1  arch_age:30
    Archive sets:
    all
        copy:1 media:mo
    big
        copy:1 media:lt
    samfs1
        copy:1 media:mo

### Archiver Daemons

The `sam-archiverd` daemon schedules the archiving activity. The `sam-arfind` process assigns files to be archived to archive sets. The `sam-arcopy` process copies the files to be archived to the selected volumes.

``The `sam-archiverd` ``daemon is started by `sam-fsd` when Sun StorEdge SAM-FS activity begins. The `sam-archiver` daemon executes the `archiver`(1M) command to read the `archiver.cmd` file and builds the tables necessary to control archiving. It starts a `sam-arfind` process for each mounted file system; likewise, if a file system is unmounted, the associated `sam-arfind` process is stopped. The `sam-archiverd` process then monitors `sam-arfind` and processes signals from an operator or other processes.

### Archive Log Files and Event Logging

The `sam-arfind` and `sam-arcopy` processes produce a log file that contains information about each archived or automatically unarchived file. The log file is a continuous record of archival action. You can use the log file to locate earlier copies of files for traditional backup purposes.

This file is not produced by default. You can use the `logfile=` directive in the `archiver.cmd` file to specify that a log file be created and to specify the name of the log file. You determine the name of this file. For more information on the log file, see the The archiver.cmd Directives in this chapter and see the `archiver.cmd`(4) man page.

The archiver logs warnings and informational messages in the log file using the `syslog` facility and `archiver.sh`.

CODE EXAMPLE 4-2 shows sample lines from an archiver log file with definitions for each field.

CODE EXAMPLE 4-2 Archiver Log File Lines
    A 2001/03/23 18:42:06 mo 0004A arset0.1 9a089.1329 samfs1 118.51162514 t0/fdn f 0 56
    A 2001/03/23 18:42:10 mo 0004A arset0.1 9aac2.1 samfs1 189.53 1515016 t0/fae f 0 56
    A 2001/03/23 18:42:10 mo 0004A arset0.1 9aac2.b92 samfs1 125.53 867101 t0/fai f 0 56
    A 2001/03/23 19:13:09 lt SLOT22 arset0.2 798.1 samfs1 71531.14 1841087 t0/fhh f 0 51
    A 2001/03/23 19:13:10 lt SLOT22 arset0.2 798.e0e samfs1 71532.12 543390 t0/fhg f 0 51
    A 2003/10/23 13:30:24 dk DISK01/d8/d16/f216 arset4.1 810d8.1 qfs2 119571.301 1136048 t1/fileem f 0 0
    A 2003/10/23 13:30:25 dk DISK01/d8/d16/f216 arset4.1 810d8.8ad qfs2 119573.295 1849474 t1/fileud f 0 0
    A 2003/10/23 13:30:25 dk DISK01/d8/d16/f216 arset4.1 810d8.16cb qfs2 119576.301 644930 t1/fileen f 0 0
    A 2003/10/23 13:30:25 dk DISK01/d8/d16/f216 arset4.1 810d8.1bb8 qfs2 119577.301 1322899 t1/fileeo f 0 0

Reading left to right, the fields in the previous listing have the content shown in TABLE 4-1.

TABLE 4-1 Archiver Log File Fields
Field | Content
--- | ---
1 | Archive activity, as follows: `A` for archived. `R` for rearchived. `U` for unarchived.
2 | Date of archive action in yyyy`/`mm`/`dd format.
3 | Time of archive activity in hh`:`mm`:`ss format.
4 | Archive media type. For information on media types, see the `mcf`(4) man page.
5 | VSN. For removable media cartridges, this is the volume serial name. For disk archives, this is the disk volume name and archive `tar`(1) file path.
6 | Archive set and copy number.
7 | Physical position of start of archive file on media (`tar`(1) file) and file offset within the archive file in hexadecimal.
8 | File system name.
9 | Inode number and generation number. The generation number is an additional number used in addition to the inode number for uniqueness since inode numbers get re-used.
10 | Length of file if file is written on only 1 volume. Length of section if file is written on multiple volumes.
11 | Path and name of file relative to the file system's mount point.
12 | Type of file, as follows: `d` for directory. `f` for regular file. `l` for symbolic link. `R` for removable media file. `I` for segment index. `S` for data segment.
13 | Section of an overflowed file or segment. If the file is an overflowed file, the value is nonzero. The value is zero for all other file types.
14 | Equipment Ordinal of the drive upon which the file was archived.

##

The `archiver.cmd` File

The `archiver.cmd` file controls the archiver's behavior. By default, the archiver runs whenever `sam-fsd` is started and a Sun StorEdge SAM-FS file system is mounted. The default actions that the archiver takes are as follows:

- Archive all files to all available volumes.

- The archive age for all files is four minutes.

- The archive interval is 10 minutes.

It is likely that you will customize the actions of the archiver to meet the archiving requirements of your site. These actions are controlled by directives located in the archiver command file (`archiver.cmd`).

### To Create or Modify an `archiver.cmd` File and Propagate Your Changes

1. Decide whether you want to edit the `archiver.cmd` file or if you want to edit a temporary `archiver.cmd` file. (Optional)

Perform this step if you have an `/etc/opt/SUNWsamfs/archiver.cmd` file and your system is already archiving files. Consider copying your `archiver.cmd` file to temporary location where you can edit and test it before putting it into production.

2. Use `vi`(1) or another editor to edit your `archiver.cmd` file or the temporary file.

Add the directives you need in order to control archiving at your site. For information on the directives you can include in this file, see The archiver.cmd Directives and Disk Archiving.

3. Save and close the `archiver.cmd` file or the temporary file.

4. Use the `archiver`(1M) `-lv` command to verify the correctness of the file.

Whenever you make changes to the `archiver.cmd` file, you should check for syntax errors using the `archiver`(1M) command. Specifying the `archiver`(1M) command as follows evaluates an `archiver.cmd` file against the current Sun StorEdge SAM-FS system:

    # archiver -lv

The preceding command lists all options and writes a listing of the `archiver.cmd` file, volumes, file system content, and errors to the standard output file (`stdout`). Errors prevent the archiver from running.

By default, the `archiver`(1M) command evaluates file `/etc/opt/SUNWsamfs/archiver.cmd` for errors. If you are working with a temporary `archiver.cmd` file prior to putting it into production, you can use the `-c` option on the `archiver`(1M) command and supply this temporary file's name.

5. Repeat Step 2, Step 3, and Step 4 until your file is free from errors.

You must correct all errors before you move onto the next step. The archiver does not archive any files if it finds errors in the `archiver.cmd` file.

6. Move the temporary file to `/etc/opt/SUNWsamfs/archiver.cmd`. (Optional)

Perform this step only if you are working with a temporary file.

7. Save and close the `archiver.cmd` file.

8. Use the `samd`(1M) `config` command to propagate the file changes and restart the system.

    # samd config

### The `archiver.cmd` File

The `archiver.cmd` file consists of the following types of directives:

- General directives

- Archive set assignment directives

- Archive set directives

- VSN pool directives

- VSN association directives

The directives consist of lines of text read from the `archiver.cmd` file. Each directive line contains one or more fields separated by spaces or tabs. Any text that appears after the pound sign character (#) is treated as a comment and is not examined. Lines can be continued onto the next line by ending the line with a backslash (\).

Certain directives in the `archiver.cmd` file require you to specify a unit of time or a unit in bytes. To specify these units, use one of the following letters in The archiver.cmd File Directive Units as a suffix to the number that signifies the unit.

TABLE 4-2 The `archiver.cmd` File Directive Units
Unit Suffixes | Significance
--- | ---
Time Suffixes:
`s` | Seconds.
`m` | Minutes. 60 seconds.
`h` | Hours. 3,600 seconds.
`d` | Days. 86,400 seconds.
`w` | Weeks. 604,800 seconds.
`y` | Years. 31,536,000 seconds.
Size Suffixes:
`b` | Bytes.
`k` | Kilobytes. 2**10, or 1,024, bytes.
`M` | Megabytes. 2**20, or 1,048,576, bytes.
`G` | Gigabytes. 2**30, or 1,073,741,824, bytes.
`T` | Terabytes. 2**40, or 1,099,511,627,776, bytes.
P | Petabytes. 2**50, or 1,125,899,906,842,624 bytes.
E | Exabytes. 2**60, or 1,152,921,504,606,846,976 bytes.

### An `archiver.cmd` File Example

CODE EXAMPLE 4-3 shows a sample `archiver.cmd` file. The comments at the right indicate the various types of directives.

CODE EXAMPLE 4-3 `archiver.cmd` File Example ``

    interval = 30m                    # General directives
    logfile = /var/opt/SUNWsamfs/archiver/archiver.log
    fs = samfs1                       # Archive Set Assignments
    no_archive tmp
    work work
        1 1h
        2 3h
    images images -minsize 100m
        1 1d
        2 1w
    samfs1_all  .
        1 1h
        2 1h
    fs = samfs2                       # Archive Set Assignments
    no_archive tmp
    system . -group sysadmin
        1 30m
        2 1h
    samfs2_all  .
        1 10m
        2 2h
    params                            # Archive Set Directives
    allsets -drives 2
    images.1 -join path -sort size
    endparams
    vsns                              # VSN Associations
    samfs1.1   mo      optic-2A
    samfs1.2   lt      TAPE01
    work.1     mo      optic-[3-9][A-Z]
    work.2     lt      .*
    images.1   lt      TAPE2[0-9]
    images.2   lt      TAPE3[0-9]
    samfs1_all.1       mo.*
    samfs1_all.2       lt.*
    samfs2.1   mo      optic-2A
    samfs2.2   lt      TAPE01
    system.1   mo      optic08a optic08b
    system.2   lt      ^TAPE4[0-1]
    samfs2_all.1       mo.*
    samfs2_all.2       lt.*
    endvsns

##

``The `archiver.cmd` Directives

The following sections explain the `archiver.cmd` directives. They are as follows:

- Global Archiving Directives

- File System Directives

- Archive Set Assignment Directive

- Archive Copy Directives

- Archive Set Copy Parameters

- VSN Association Directives

- VSN Pools Directives

### Global Archiving Directives

Global directives control the overall archiver operation. These global directives in an `archiver.cmd` file can be identified either by the equal sign (=) in the second field or by the absence of additional fields. These directives allow you to optimize archiver operations for your site's configuration.

Global directives must be specified prior to any `fs=` directives in your `archiver.cmd` file. The `fs=` directives are those that pertain to specific file systems. The archiver issues a message if it detects a global directive after an `fs=` directive.

#### The `archivemeta` Directive: Controlling Whether Metadata is Archived

The `archivemeta` directive controls whether or not file system metadata is archived. If files are often moved around and there are typically many changes to the directory structures in your file system, you would want to archive your metadata. If, however, the directory structures are very stable, you can disable metadata archiving and reduce the actions performed by your removable media drives as cartridges are loaded and unloaded to archive metadata. By default, metadata is archived.

This directive has the following format:

    archivemeta = state

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

Metadata archiving differs depending 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, removable media files and symbolic links are stored in inodes rather than in data blocks. They are not archived. Only directories and segment index inodes are archived as metadata. Symbolic links are archived as data.

#### The `archmax` Directive: Controlling the Size of Archive Files

The `archmax` directive specifies the maximum size of an archive file. User files are combined to form the archive file. No more user files are added to the archive file after the target_size is met. Large user files are written in a single archive file.

To change the defaults, use the following directive:

    archmax=media target_size

TABLE 4-3 Arguments for the `archmax` Directive
Argument | Meaning
--- | ---
media | The media type. For the list of valid media types, see the `mcf`(4) man page.
target_size | Specifies the maximum size of the archive file. The maximum size of an archive file is media-dependent. By default, archive files written to optical disks are no larger than 5 megabytes. The default maximum archive file size for tapes is 512 megabytes.

There are advantages and disadvantages to setting large or small sizes for archive files. 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, there is the possibility that when an end-of-tape is reached prematurely, a large amount of tape can be wasted. As a rule, `archmax` should not be set to more than 5 percent of the media capacity. For example, you can use the following `archmax` directive for a 20 gigabyte tape:

    archmax=sg 1G

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

#### The `bufsize` Directive: Setting the Archiver Buffer Size

By default, a file being archived is copied to archive media using a memory buffer. You can use the `bufsize` directive to specify a nondefault buffer size and, optionally, to lock the buffer. These actions can improve performance, and you can experiment with different buffer_size values.

This directive has the following format:

    bufsize=media buffer_size [ lock ]

TABLE 4-4 Arguments for the `bufsize` Directive
Argument | Meaning
--- | ---
media | The media type. For the list of valid media types, see the `mcf`(4) man page.
buffer_size | Specify a number from 2 through 32. 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` can be specified in the `defaults.conf` file. For more information on this file, see the `defaults.conf`(4) man page.
`lock` | The `lock` argument indicates whether or not the archiver should 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`(1M) operation. This avoids the overhead of locking and unlocking the buffer for each I/O request and can result in a reduction in system CPU time. The `lock` argument should 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. For more information on enabling direct I/O, see the `setfa`(1) man page, the `sam_setfa`(3) library routine man page, or the `-O forcedirectio` option on the `mount_samfs`(1M) man page.

For example, this directive can be specified in the `archiver.cmd` file in a line like the following:

`bufsize=od 7 lock`

You can specify a buffer size and a lock on an archive set basis by using the `-bufsize` and `-lock` archive set copy parameters. For more information, see Archive Set Copy Parameters.

#### The `drives` Directive: Controlling the Number of Drives Used for Archiving

By default, the archiver uses all of the drives in an automated library for archiving. To limit the number of drives in an automated library used by the archiver, use the `drives` directive.

This directive has the following format:

    drives=auto_lib count

TABLE 4-5 Arguments for the `drives` Directive
Argument | Meaning
--- | ---
auto_lib | The Family Set name of the automated library as defined in the `mcf` file.
count | The number of drives to be used for archiving activities.

Also see the `-drivemax`, `-drivemin`, and `-drives` archive set copy parameters described in Specifying the Number of Drives for an Archive Request: -drivemax, -drivemin, and -drives.

#### The `examine` Directive: Controlling Archive Scans

New files and files that have changed are candidates for archiving. The archiver finds such files by implementing one of the following methods:

- Continuous archiving. When continuous archiving is implemented, the archiver works with the file system to detect file changes immediately after they occur.

- Scan-based archiving. With scan-based archiving, the archiver scans the file system periodically looking for files that need to be archived.

The `examine` directive controls whether the archiver performs continuous or scan-based archiving, as follows:

    examine=method

Specify one of the keywords shown in TABLE 4-6 for method.

TABLE 4-6 Values for the `examine` Directive's method argument
method Value | Meaning
--- | ---
`noscan` | Specifies continuous archiving. After the initial scan, directories are scanned only when the content changes and archiving is required. Directory and inode information is not scanned. This archiving method provides better performance than scan-based archiving, particularly for file systems with more than 1,000,000 files. Default.
`scan` | Specifies scan-based archiving. The initial file system scan is a directory scan. Subsequent scans are inode scans.
`scandirs` | Specifies scan-based archiving on directories only. When specified, if the archiver finds a directory with the `no_archive` attribute set, that directory is not scanned. Files that do not change can be placed in such a directory, and this can dramatically reduce the amount of time spent on archiving scans.
`scaninodes` | Specifies scan-based archiving on inodes only.

#### The `interval` Directive: Specifying an Archive Interval

The archiver executes periodically to examine the status of all mounted Sun StorEdge SAM-FS file systems. The timing is controlled by the archive interval. The archive interval is the time between scan operations on each file system. To change the time, use the `interval` directive.

Note - The `interval` directive is effective only if the `examine=scan` directive is also specified in the `archiver.cmd` file.

This directive has the following format:

    interval=time

For time, specify the time, in seconds, between scan operations on a file system. By default, time is interpreted in seconds. By default, `interval=600`, which is 10 minutes. You can specify a unit of time, such as minutes, hours, and so on. For information on specifying a unit of time, see The archiver.cmd File Directive Units.

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

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

For more information on specifying the archive interval, see the `archiver.cmd`(4) man page. For more information on setting mount options, see the `mount_samfs`(1M) man page.

#### The `logfile` Directive: Specifying An Archiver Log File

The archiver can produce a log file that contains information about each file that is archived, rearchived, or automatically unarchived. The log file is a continuous record of archival action. 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. By default, this file is not produced.

Example. Assume that you want to back up the archiver log file every day by copying the previous day's log file to an alternate location. This can be accomplished if you make sure that the copy is performed when the archiver log file is closed. In other words, you must not perform the copy operation while the archiver log file is open for a write operation.

To Back Up an Archiver Log File

The steps you need to take are as follows:

1. Use the `mv`(1) command to move the archiver log file within UFS.

This gives any `sam-arfind`(1M) or `sam-arcopy`(1M) operations time to finish writing to the archiver log file.

2. Use the `mv`(1) command to move the previous day's archiver log file to the Sun StorEdge SAM-FS file system.

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

#### The `notify` Directive: Renaming the Event Notification Script

The `notify` directive sets the name of the archiver's event notification script file to filename. 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 as follows:

`/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 a keyword for the first argument. The keywords are as follows: `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, and `debug.`

Additional arguments are described in the default script. For more information, see the `archiver.sh`(1M) man page.

#### The `ovflmin` Directive: Controlling Volume Overflow

Volume overflow is the process of allowing archived files to span multiple volumes. Volume overflow is enabled when you use the `ovflmin` directive in the `archiver.cmd` file. When a file size exceeds the `ovflmin` directive's minimum_file_size argument, the archiver writes another portion of this file to another available volume of the same type, if necessary. The portion of the file written to each volume is called a section.

Note - Before using volume overflow, make sure that you understand the concept. Use volume overflow with caution only after thoroughly assessing the effect on your site. Disaster recovery and recycling are much more difficult with files that span volumes.

The archiver controls volume overflow through the `ovflmin` directive. The `ovflmin` directive specifies the minimum size file that is allowed to overflow a volume. By default, volume overflow is disabled.

This directive has the following format:

    ovflmin = media minimum_file_size

TABLE 4-7 Arguments for the `ovflmin` Directive
Argument | Meaning
--- | ---
media | The media type. For a list of valid media types, see the `mcf`(4) man page.
minimum_file_size | Specify the minimum size of the file to overflow

Example 1. Assume that many files exist with a length that is a significant fraction (say 25 percent) of an `mo` media cartridge. These files partially fill the volumes and leave unused space on each volume. To get better packing of the volumes, set `ovflmin` for `mo` media to a size slightly smaller than the size of the smallest file. The following directive sets it to 150 megabytes:

    ovflmin=mo 150m

Note that enabling volume overflow in this example also causes two volumes to be loaded for archiving and staging the file.

The `ovflmin` directive can also be set for an individual archive set.

Example 2. The `sls`(1) command lists the archive copy showing each section of the file on each VSN. CODE EXAMPLE 4-4 shows the archiver log file and the `sls -D` command output for a large file named `file50` that spans multiple volumes.

CODE EXAMPLE 4-4 Archiver Log File Example
    A  97/01/13  16:03:29  lt  DLT000  big.1  7eed4.1  samfs1  13.7  477609472  00 big/file50  0  0
    A  97/01/13  16:03:29  lt  DLT001  big.1  7fb80.0  samfs1  13.7  516407296  01 big/file50  0  1
    A  97/01/13  16:03:29  lt  DLT005  big.1  7eb05.0  samfs1  13.7  505983404  02 big/file50  0  2

CODE EXAMPLE 4-4 shows that `file50` spans three volumes with VSNs of `DLT000`, `DLT001`, and `DLT005`. The position on the volume and the size of each section is indicated in the seventh and tenth fields respectively, and matches the `sls` `-D` output also shown. For a complete description of the archiver log entry, see the `archiver`(1M) man page.

CODE EXAMPLE 4-5 shows the `sls -D` command and output.

CODE EXAMPLE 4-5 `sls` (1M) `-D` Command and Output
    # sls -D file50
    file50:
      mode: -rw-rw----  links:   1  owner: gmm    group: sam
      length: 1500000172  admin id:      7  inode: 1407.5
      offline;   archdone;  stage -n
      copy1: ---- Jan 13 15:55            lt
        section 0:  477609472     7eed4.1    DLT000
        section 1:  516407296     7fb80.0    DLT001
        section 2:  505983404     7eb05.0    DLT005
      access:      Jan 13 17:08  modification: Jan 10 18:03
      changed:     Jan 10 18:12  attributes:   Jan 13 16:34
      creation:    Jan 10 18:03  residence:    Jan 13 17:08

Volume overflow files do not generate checksums. For more information on using checksums, see the `ssum`(1) man page.

Note - When you use the volume overflow feature, be aware that it is difficult to retrieve volume overflow data in the event of a disaster. For information on how to retrieve such a file, see the examples in the Sun QFS, Sun SAM-FS, and Sun SAM-QFS Disaster Recovery Guide. For more information, see the `request`(1) man page.

#### The `wait` Directive: Delaying Archiver Startup

The `wait` directive causes the archiver to wait for a start signal from `samu`(1M) or SAM-QFS Manager. When this signal is received, typical archiver operations are begun. By default, the archiver begins archiving when started by `sam-fsd`(1M). To delay archiving, use the `wait` directive. This directive has the following format:

    wait

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

### File System Directives

You can use the `fs=` directive to include directives specific to a particular file system in the `archiver.cmd` file after the general directives. After an `fs=` directive is encountered, the archiver assumes that all subsequent directives specify actions to be taken only for individual file systems.

#### The `fs` Directive: Specifying the File System

By default, archiving controls apply to all file systems. However, you can confine some controls to an individual file system. To specify an individual file system, use the `fs` directive. This directive has the following format:

    fs=fsname

For fsname, specify the file system name as defined in the `mcf` file.

The general directives and archive set association directives that occur after these directives apply only to the specified file system until another `fs=` directive is encountered. For instance, you can use this directive to specify a different log file for each file system.

#### Other File System Directives

Several directives can be specified both as global directives for all file systems and as directives that are specific to one file system. Their effects are the same regardless of where they are specified. These directives are as follows:

- The `interval` directive. For more information on this directive, see The interval Directive: Specifying an Archive Interval.

- The `logfile` directive. For more information on this directive, see The logfile Directive: Specifying An Archiver Log File.

- The `wait` directive. For more information on this directive, see The wait Directive: Delaying Archiver Startup.

### Archive Set Assignment Directive

By default, files are archived as part of the archive set named for the file system. In SAM-QFS Manager, an archive policy defines archive sets. However, you can specify archive sets to include files that share similar characteristics. If a file does not match one of the specified archive sets, it is archived as part of the default archive set named for the file system.

#### Assigning Archive Sets

The archive set membership directives assign files with similar characteristics to archive sets. The syntax of these directives is patterned after the `find`(1) command. Each archive set assignment directive has the following format:

    archive_set_name path [search_criteria1 search_criteria2 ... ] [file_attributes]

TABLE 4-8 Arguments for the Archive Set Assignment Directive
Argument | Meaning
--- | ---
archive_set_name | A site-defined name for the archive set. Must be the first field in the archive set assignment directive. An archive set name is usually indicative of the characteristics of the files belonging to the archive set. Archive set names are restricted to the letters in the alphabet, numbers, and the underscore character (_). No other special characters or spaces are allowed. The first character in the archive set name must be a letter. To prevent archiving for various files, specify `no_archive` as the archive_set_name.
path | A path relative to the mount point of the file system. This allows an archive set membership directive to apply to multiple Sun StorEdge SAM-FS file systems. If the path is to include all of the files in a file system, use a period (.) for the path field. A leading slash (/) is not allowed in the path. Files in the directory specified by path, and its subdirectories, are considered for inclusion in this archive set.
search_criteria1 search_criteria2 | Zero, one, or more search_criteria arguments can be specified. Search criteria can be specified to restrict the archive set according to file size, file ownership, and other factors. For information on possible search_criteria arguments, see the following sections.
file_attributes | Zero, one, or more file_attributes can be specified. These file attributes are set for files as the `sam-arfind` process scans a file system during archiving.

Example 1. CODE EXAMPLE 4-6 shows typical archive set membership directives.

CODE EXAMPLE 4-6 Archive Set Membership Directives
    hmk_files    net/home/hmk     -user hmk
    datafiles    xray_group/data  -size 1M
    system       .

Example 2. You can suppress the archiver by including files in an archive set named `no_archive`. CODE EXAMPLE 4-7 shows lines that prevent archiving of files in a `tmp` directory, at any level, and regardless of the directory in which the `tmp` directory resides within the file system.

CODE EXAMPLE 4-7 Archiving Directives that Prevent Archiving
    fs = samfs1
    no_archive tmp
    no_archive . -name .*/tmp/

The following sections describe the search_criteria that you can specify.

#### File Size search_criteria: `-access`

You can use the `-access` age characteristic to specify that the age of a file be used to determine archive set membership. When you use this search_criteria, files with access times older than age are rearchived to different media. For age, specify an integer number followed by one of the suffixes shown in TABLE 4-9.

TABLE 4-9 `-access` age Sufixes
Letter | Meaning
--- | ---
s | Seconds
m | Minutes
h | Hours
d | Days
w | Weeks
]y | Years

For example, you can use this directive to specify that files that have not been accessed in a long time be rearchived to cheaper media.

#### File Size search_criteria: `-minsize` and -`maxsize`

The size of a file can be used to determine archive set membership using the `-minsize` size and `-maxsize` size characteristics. For size, specify an integer followed by one of the letters shown in TABLE 4-10.

TABLE 4-10 `-minsize` and `-maxsize` size Suffixes
Letter | Meaning
--- | ---
`b` | Bytes
`k` | Kilobytes
`M` | Megabytes
`G` | Gigabytes
`T` | Terabytes
P | Petabytes
E | Exabytes

Example. The lines in this example specify that all files of at least 500 kilobytes, but less than 100 megabytes, belong to the archive set `big_files`. Files bigger than 100 megabytes belong to the archive set `huge_files`. CODE EXAMPLE 4-8 shows the lines.

CODE EXAMPLE 4-8 Using the `-minsize` and `-maxsize` Directive Examples
    big_files  .  -minsize 500k  -maxsize 100M
    huge_files .  -minsize 100M

#### Owner and Group search_criteria: `-user` and `-group`

The ownership and group affiliation can be used to determine archive set membership using the `-user` name and `-group` name characteristics. CODE EXAMPLE 4-9 shows examples of these directives.

CODE EXAMPLE 4-9 Using the -user and -group Directive Examples
    adm_set    .   -user sysadmin
    mktng_set  .   -group marketing

All files belonging to user `sysadmin` belong to archive set `adm_set`, and all files with the group name of `marketing` are in the archive set `mktng_set`.

#### File Name search_criteria Using Pattern Matching: `-name` regex

The names of files that are to be included in an archive set can be specified by using regular expressions. The `-name` regex specification as a search_criteria specifies that any complete path matching the regular expression regex is a member of the archive set.

The regex argument follows the conventions as outlined in the `regexp`(5) man page. Note that regular expressions do not follow the same conventions as UNIX wildcards.

Internally, all files beneath the selected directory are listed (with their specified paths relative to the mount point of the file system) and passed along for pattern matching. This allows you to create patterns in the `-name` regex field to match both file names and path names.

##### Examples

1. The following directive restricts files in the archive set `images` to those files ending with `.gif`:

    images  . -name \.gif$

2. The following directive selects files that start with the characters `GEO`:

    satellite  . -name /GEO

3. You can use regular expressions with the `no_archive` archive set. The following specification prevents any file ending with `.o` from being archived:

    no_archive  . -name \.o$

4. Assume that your `archiver.cmd` file contains the lines shown in CODE EXAMPLE 4-10.

CODE EXAMPLE 4-10 Regular Expression Example
    # File selections.
    fs = samfs1
         1 1s
         2 1s
    no_archive share/marketing -name fred\.

With this `archiver.cmd` file, the archiver does not archive `fred.*` in the user directories or subdirectories. Archiving occurs for files as follows:

- CODE EXAMPLE 4-11 shows the files not archived if you specify the directives shown in CODE EXAMPLE 4-10.

CODE EXAMPLE 4-11 Files not Archived (Assuming Directives Shown in CODE EXAMPLE 4-10 )
    /sam1/share/marketing/fred.anything
    /sam1/share/marketing/first_user/fred.anything
    /sam1/share/marketing/first_user/first_user_sub/fred.anything

- CODE EXAMPLE 4-12 shows the files that are archived if you specify the directives shown in CODE EXAMPLE 4-10.

CODE EXAMPLE 4-12 Files Archived (Assuming Directives Shown in CODE EXAMPLE 4-10 )
    /sam1/fred.anything
    /sam1/share/fred.anything
    /sam1/testdir/fred.anything
    /sam1/testdir/share/fred.anything
    /sam1/testdir/share/marketing/fred.anything
    /sam1/testdir/share/marketing/second_user/fred.anything

5. Assume that your `archiver.cmd` file contains the lines shown in CODE EXAMPLE 4-13.

CODE EXAMPLE 4-13 Example `archiver.cmd` File
    # File selections.
    fs = samfs1
         1 1s
         2 1s
    no_archive share/marketing -name ^share/marketing/[^/]*/fred\.

The `archiver.cmd` file in CODE EXAMPLE 4-13 does not archive `fred.*` in the user home directories. This archives `fred.*` in the user subdirectories and in the directory `share/marketing`. In this case, the user home directories happen to be `first_user`. This example takes anything as a user's home directory from `share/marketing/` until the next slash character (`/`). Archiving occurs for files as follows:

- The following files are not archived:

    /sam1/share/marketing/first_user/fred.anything

- CODE EXAMPLE 4-14 shows the files that are archived if you specify the directives shown in CODE EXAMPLE 4-13.

CODE EXAMPLE 4-14 Files Archived (Assuming Directives Shown in CODE EXAMPLE 4-13 )
    /sam1/share/fred.anything
    /sam1/share/marketing/fred.anything
    /sam1/share/marketing/first_user/first_user_sub/fred.anything
    /sam1/fred.anything
    /sam1/testdir/fred.anything
    /sam1/testdir/share/fred.anything
    /sam1/testdir/share/marketing/fred.anything
    /sam1/testdir/share/marketing/second_user/fred.anything
    /sam1/testdir/share/marketing/second_user/sec_user_sub/fred.any

#### Release and Stage file_attributes: -release and -stage

You can set the release and stage attributes associated with files within an archive set by using the `-release` and `-stage` options, respectively. Both of these settings override stage or release attributes that a user might have set previously.

The `-release` option has the following format:

    -release attributes

The attributes for the `-release` directive follow the same conventions as the `release`(1) command and are as shown in TABLE 4-11.

TABLE 4-11 The `-release` Option
attributes | Meaning
--- | ---
`a` | Release the file following the completion of the first archive copy.
`d` | Reset to default.
`n` | Never release the file.
`p` | Partially release the file's disk space.

The `-stage` option has the following format:

    -stage attributes

The attributes for the `-stage` directive follow the same conventions as the `stage`(1) command and are as shown in TABLE 4-12.

TABLE 4-12 The `-stage` Directive's attributes
attributes | Meaning
--- | ---
`a` | Associative stage the files in this archive set.
`d` | Reset to default.
`n` | Never stage the files in this archive set.

The following example shows how you can use file name specifications and file attributes in order to partially release Macintosh resource directories:

    MACS  . -name .*/\.rscs/  -release p

#### Archive Set Membership Conflicts

Sometimes the choice of path and other file characteristics for inclusion of a file in an archive set results in ambiguous archive set membership. These situations are resolved in the following manner:

1. The membership definition occurring first in the archive set is chosen.

2. Membership definitions local to a file system are chosen before any globally defined definitions.

3. A membership definition that exactly duplicates a previous definition is noted as an error.

As a consequence of these rules, more restrictive membership definitions should be placed earlier in the directive file.

When controlling archiving for a specific file system (using the `fs=`fsname directive), the archiver evaluates the file system specific directives before evaluating the global directives. Thus, files can be assigned to a local archive set (including the `no_archive` archive set) instead of being assigned to a global archive. This has implications when setting global archive set assignments such as `no_archive`.

CODE EXAMPLE 4-15 shows an `archiver.cmd` file.

CODE EXAMPLE 4-15 An `archiver.cmd` File With Possible Membership Conflicts
    no_archive   . -name .*\.o$
    fs = samfs1
        allfiles  .
    fs = samfs2
        allfiles  .

In reading CODE EXAMPLE 4-15, it appears that the administrator did not intend to archive any of the `.o` files across both file systems. However, because the local archive set assignment `allfiles` is evaluated before the global archive set assignment `no_archive`, the `.o` files in the `samfs1` and `samfs2` file systems are archived.

CODE EXAMPLE 4-16 shows the directives to use to ensure that no `.o` files are archived in both file systems.

CODE EXAMPLE 4-16 Corrected `archiver.cmd` File
    fs = samfs1
        no_archive   . -name .*\.o$
        allfiles  .
    fs = samfs2
        no_archive   . -name .*\.o$
        allfiles  .

### Archive Copy Directives

If you do not specify archive copies, the archiver writes a single archive copy for files in the archive set. By default, this copy is made when the archive age of the file is four minutes. If you require more than one archive copy, all copies, including the first, must be specified using archive copy directives.

The archive copy directives begin with a copy_number that is an integer digit. This digit (`1`, `2`, `3`, or `4`) is the copy number. The digit is followed by one or more arguments that specify archive characteristics for that copy.

The archive copy directives must appear immediately after the archive set assignment directive to which they pertain. Each archive copy directive has the following format:

    copy_number [ -release | -norelease ] [archive_age] [unarchive_age]

The following sections describe the archive copy directive arguments.

#### Releasing Disk Space After Archiving: `-release`

You can specify that the disk space for files be automatically released after an archive copy is made by using the `-release` directive after the copy number. This option has the following format:

    -release

In CODE EXAMPLE 4-17, files with the group `images` are archived when their archive age reaches 10 minutes. After archive copy 1 is made, the disk cache space is released.

CODE EXAMPLE 4-17 An `archiver.cmd` File Using the `-release` Directive
    ex_set . -group images
        1 -release 10m

#### Delaying Disk Space Release: -norelease

You might not want to release disk space until multiple archive copies are completed. The `-norelease` option prevents the automatic release of disk cache until all copies marked with `-norelease` are made. This option has the following format:

    -norelease

CODE EXAMPLE 4-18 specifies an archive set named `vault_tapes`. Two copies are created, but the disk cache associated with this archive set is not released until both copies are made. This scenario can be used at a site that requires online access to files before creating volumes for offsite storage.

CODE EXAMPLE 4-18 An `archiver.cmd` File Using the `-norelease` Directive
    vault_tapes
        1 -norelease 10m
        2 -norelease 30d

Note that the `-norelease` specification on a single copy has no effect on automatic releasing because the file cannot be released until it has at least one archive copy. Also, the `-norelease` and `-release` specifications are mutually exclusive.

#### Setting the Archive Age

You can set the archive age for files by specifying the archive age as the next field on the directive. The archive age can be specified with a suffix character such as `h` for hours or `m` for minutes. The archiver.cmd File Directive Units, shows the complete list of suffix characters and their meanings.

In CODE EXAMPLE 4-19, the files in directory `data` are archived when their archive age reaches one hour.

CODE EXAMPLE 4-19 An `archiver.cmd` File that Specifies the Archive Age
    ex_set data
        1 1h

#### Unarchiving Automatically

If you specify more than one archive copy of a file, it is possible to unarchive all but one of the copies automatically. This might occur when the files are archived to various media using various archive ages.

CODE EXAMPLE 4-20 shows directives that specify the unarchive age.

CODE EXAMPLE 4-20 An `archiver.cmd` File that Specifies the Unarchive Age
    ex_set home/users
        1 6m 10w
        2 10w
        3 10w

The first copy of the files in the path `home/users` is archived six minutes after modification. When the files are 10 weeks old, second and third archive copies are made. The first copy is then unarchived.

For more ways to control unarchiving, see Controlling Unarchiving.

#### Specifying More Than One Copy for Metadata

If more than one copy of metadata is required, you can place copy definitions in the directive file immediately after an `fs=` directive.

CODE EXAMPLE 4-21 shows an `archiver.cmd` file that specifies multiple metadata copies.

CODE EXAMPLE 4-21 An `archiver.cmd` File that Specifies Multiple Metadata Copies
    fs = samfs7
        1 4h
        2 12h

In this example, copy 1 of the metadata for the `samfs7` file system is made after four hours and a second copy is made after 12 hours.

File system metadata includes changes to path names in the file system. For this reason, if you have frequent changes to directories, new archive copies are created. This results in frequent loads of the volumes specified for metadata.

### Archive Set Copy Parameters

The archive set parameters section of the `archiver.cmd` file begins with the params directive and ends with the `endparams` directive. CODE EXAMPLE 4-22 shows the format for directives for an archive set.

CODE EXAMPLE 4-22 Archive Set Copy Parameter Format
    params
    archive_set_name.copy_number[R] [ -param1 -param2 ...]
    .
    .
    .
    endparams

TABLE 4-13 Arguments for the Archive Set Copy Parameters
Argument | Meaning
--- | ---
archive_set_name | A site-defined name for the archive set. Usually indicative of the characteristics of the files belonging to the archive set. Can be `allsets`. Archive set names are restricted to the letters in the alphabet, numbers, and the underscore character (`_`). No other special characters or spaces are allowed. The first character in the archive set name must be a letter.
`.` | A period (`.`) character. Used to separate the archive_set_name from the copy_number.
copy_number | An integer number that defines the archive copy number. Can be `1`, `2`, `3`, or `4`.
`R` | Specifies that the parameters being defined are for rearchived copies of this archive set. For example, you can use the `R` and specify VSNs in the `-`param1 argument to direct rearchived copies to specific volumes.
`-`param1 `-`param2 | One or more parameters. The following subsections describe the parameters than can be specified between the `params` and `endparams` directives.

The pseudo archive set `allsets` provides a way to set default archive set directives for all archive sets. All `allsets` directives must precede those for actual archive set copies. Parameters set for individual archive set copies override parameters set by the `allsets` directive. For more information on the `allsets` archive set, see the `archiver.cmd`(4) man page.

All archive set processing parameters are described in this section, with the exception of the `-disk_archive` parameter. For information on the `-disk_archive` parameter, see Disk Archiving.

#### Controlling the Size of Archive Files: `-archmax`

The `-archmax` directive sets the maximum file size for an archive set. The format is as follows:

    -archmax target_size

This directive is very similar to the `archmax` global directive. For information on this directive, and the values to enter for target_size, see The archmax Directive: Controlling the Size of Archive Files.

#### Setting the Archiver Buffer Size: `-bufsize`

By default, a file being archived is stored in memory in a buffer prior to writing the file to archive media. You can use the `-bufsize` parameter to specify a nondefault buffer size. These actions can improve performance, and you can experiment with various buffer_size values.

This parameter has the following format:

    -bufsize=buffer_size

For buffer_size, specify a number from 2 through 32. 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` is specified in the `defaults.conf` file. For more information on this file, see the `defaults.conf`(4) man page.

For example, this parameter can be specified in the `archiver.cmd` file in a line such as the following:

`myset.1 -bufsize=6`

The equivalent of this directive can also be specified on a global basis by specifying the `bufsize=`media buffer_size directive. For more information on this topic, see The bufsize Directive: Setting the Archiver Buffer Size.

#### Specifying the Number of Drives for an Archive Request: `-drivemax`, `-drivemin`, and `-drives`

By default, the archiver uses only one media drive to archive one archive set's files. When an archive set has a many files or large files, it can be advantageous to use more than one drive. In addition, if the drives in your automated library operate at different speeds, using these directives can contribute to archiving efficiency.

CODE EXAMPLE 4-23 shows the parameters you can use to split archive requests across drives and to balance variations in tape drive transfer speeds.

CODE EXAMPLE 4-23 Formats for the `-drivemax` , `-drivemin` , and `-drives` Directives
    -drivemax max_size
    -drivemin min_size
    -drives number

TABLE 4-14 Arguments for the `-drivemax` , `-drivemin` , and `-drives` Parameters
Argument | Meaning
--- | ---
maxsize | The maximum amount of data to be archived using one drive.
minsize | The minimum amount of data to be archived using one drive. The default is the `-archmax` target_size value (if specified) or the default value for the media type. If you specify the `-drivemin` minsize parameter, Sun StorEdge SAM-FS uses multiple drives only if there is enough work to warrant it. As a guideline, you can set minsize to be large enough to cause the transfer time to be significantly longer than the cartridge change time (load, position, unload).
number | The number of drives to use when archiving this archive set. The default is 1.

An archive request is evaluated against the parameters that are specified, as follows:

- If an archive request is less than min_size, only one drive is used to write an archive request.

- If an archive request is larger than min_size, the archive request is evaluated against min_size and the appropriate number of drives is scheduled up to the full number of drives specified.

- If min_size is zero, an attempt is made to split among the full number of drives specified.

When you use the `-drives` parameter, multiple drives are used only if data that is more than the min_size is to be archived at once. The number of drives to be used in parallel is the lesser of arch_req_total_size/min_size and the number of drives specified by the `-drives` parameter.

To set these parameters, users need to consider file creation rates, the number of drives, the time it takes to load and unload drives, and drive transfer rates.

Example 1. You can use the `-drivemin` and `-drives` parameters if you want to divide an archive request among drives, but you want to avoid tying up all the drives with small archive requests. This might apply to operations that use very large files.

Example 2. Assume that you are splitting an archive set named `big_files` over five drives. Depending on its size, this archive set could be split as shown in TABLE 4-15.

TABLE 4-15 Archive Set Example Split
Archive Set Size | Number of Drives
--- | ---
< 20 gigabytes | 1
> 20 gigabytes to < 30 gigabytes | 2
> 30 gigabytes to < 40 gigabytes | 3
> 40 gigabytes to < 50 gigabytes | 4
> 50 gigabytes | 5

CODE EXAMPLE 4-24 shows the lines to use in the `archiver.cmd` file to split the archive request over multiple drives.

CODE EXAMPLE 4-24 Directives Used to Split an Archive Request Over Multiple Drives
    params
    bigfiles.1 -drives 5 -drivemin 10G
    endparams

Example 3. The following line is specified in the `archiver.cmd` file:

    huge_files.2 -drives 2

When the total size of the files in archive set `huge_files.2` is equal to or greater than two times `drivemin` for the media, two drives are used to archive the files.

Example 4. An archive request is 300 gigabytes. The following line is specified in the `archiver.cmd` file to archive 10 gigabytes at a time on each of 5 drives:

    -drives 5 -drivemax 10G

#### Maximizing Space on a Volume: `-fillvsns`

By default, the archiver uses all volumes assigned to an archive set when it writes archive copies. When writing the archive copies, the archiver selects a volume with enough space for all the files. This action can result in volumes not being filled to capacity. If `-fillvsns` is specified, the archiver separates the archive request into smaller groups.

#### Specifying Archive Buffer Locks: `-lock`

By default, a file being archived is stored in memory in a buffer prior to writing the file to archive media. If direct I/O is enabled, you can use the `-lock` parameter to lock this buffer. This action can improve performance, and you can experiment with this parameter.

This parameter has the following format:

    -lock

The `-lock` parameter indicates whether or not the archiver should 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`(1M) operation. This avoids paging the buffer, and it can improve performance.

The`-lock` parameter should be specified only on large systems with large amounts of memory. Insufficient memory can cause an out-of-memory condition.

The `-lock` parameter 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. For more information on enabling direct I/O, see the `setfa`(1) man page, the `sam_setfa`(3) library routine man page, or the `-O` `forcedirectio` option on the `mount_samfs`(1M) man page.

For example, this parameter can be specified in the `archiver.cmd` file in a line such as the following:

    yourset.3 -lock

You can also specify the equivalent of this parameter on a global basis by specifying the `lock` argument to the `bufsize=`media buffer_size [`lock`] directive. For more information on this topic, see The bufsize Directive: Setting the Archiver Buffer Size.

#### Making Archive Copies of Offline Files: `-offline_copy`

A file is a candidate for being released after one archive copy is made. If the file releases and goes offline before all the archive copies are made, the archiver uses this parameter to determine the method to be used when making the other archive copies. In choosing the method to be used, consider the number of drives available to the Sun SAM-FS system and the amount of disk cache available. This parameter has the following format:

    -offline_copy method

Specify one of the keywords shown in for method.

TABLE 4-16 Values for the `-offline_copy` Directive's method argument
method | Meaning
--- | ---
`none` | Stages files as needed for each file before copying to the archive volume. Default.
`direct` | Copies files directly from the offline volume to the archive volume without using the cache. This method assumes that the source volume and the destination volume are different volumes and that two drives are available. If this method is specified, raise the value of the `stage_n_window` mount option to a value that is greater than its default of 256 kilobytes. For more information on mount options, see the `mount_samfs`(1M) man page.
`stageahead` | Stages one file while archiving another. When specified, the system stages the next archive file while writing a file to its destination.
`stageall` | Stages all files to disk cache before archiving. This method uses only one drive and assumes that room is available on disk cache for all files.

#### Specifying Recycling

The recycling process allows you to reclaim space on archive volumes that is taken up by expired archive images. By default, no recycling occurs.

If you want to recycle, you can specify directives in both the `archiver.cmd` file and in the `recycler.cmd` file. For more information on the recycling directives supported in the `archiver.cmd` file, see Recycling.

#### Associative Archiving: `-join`

The archiver employs associative archiving if you specify the `-join` `path` parameter. Associative archiving is useful if you want an entire directory to be archived to one volume and you know that the archive file can physically reside on only one volume. Otherwise, if you want to keep directories together, use either the `-sort` `path` or `-rsort path` parameters to keep the files contiguous. The `-rsort` performs a reverse sort.

When the archiver writes an archive file to a volume, it efficiently packs the volume with user files. Subsequently, when accessing files from the same directory, you can experience delays as the stage process repositions through a volume to read the next file. To alleviate delays, you can archive files from the same directory paths contiguously within an archive file. The process of associative archiving overrides the space efficiency algorithm to archive files from the same directory together. The `-join path` parameter allows these files to be archived contiguously within an archive set copy.

Associative archiving is useful when the file content does not change but you want to access the group of files together at the same time all the time. For example, you might use associative archiving at a hospital for accessing medical images. Images associated with the same patient can be kept in a directory and the doctor might want to access those images together at one time. These static images can be accessed more efficiently if you archive them contiguously based on their directory location. For example:

    patient_images.1 -join path

Note - The `-join path` parameter writes data files from the same directory to the same archive file. If there are many directories with a few small files, the archiver creates many small archive files. These small, discrete archive files slow the write performance of the system because the data files are relatively small compared to the `tar`(1) header for each archive file. This can impair performance when writing to high-speed tape drives. Also, because the`-join path` parameter specifies that all the files from the same directory be archived on a single volume, it is possible that a group of files might not fit on any available volume. In this case, the files are not archived until more volumes are assigned to the archive set. It is also possible that the group of files to be archived is so large that it can never fit on a single volume. In such a case, the files are never archived. For most applications, using either `-sort path` or `-join path` parameter is preferred if the more restrictive operation of `-join path` is not a requirement.

It is also possible to sort files within an archive set copy by age, size, or path. The `age` and `size` arguments are mutually exclusive. CODE EXAMPLE 4-25 shows how to sort an archive set using the `-sort` parameter with the argument `age` or `size`.

CODE EXAMPLE 4-25 Directives for Sorting an Archive Set
    cardiac.1 -sort path
    cardiac.2 -sort age
    catscans.3 -sort size

The first line forces the archiver to sort an archive request by path name. The second example line forces the archiver to sort an archive set copy called `cardiac.2` by the age of the file, oldest to youngest. The third line forces the archive set copy called `catscans` to be sorted by the size of the file, smallest to largest. If you had wanted a reverse sort, you could have specified `-rsort` in place of `-sort`.

#### Controlling Unarchiving

Unarchiving is the process by which archive entries for files or directories are deleted. By default, files are never unarchived. Files are unarchived based on the time since last access. All frequently accessed data can be stored on a fast media, such as disk, and all older, infrequently accessed data can be stored on tape.

Example 1. CODE EXAMPLE 4-26 shows an `archiver.cmd` file.

CODE EXAMPLE 4-26 Directives to Control Unarchiving
    arset1 dir1
       1    10m    60d
       2    10m
       3    10m
    vsns
    arset1.1    mo       OPT00[0-9]
    arset1.2    lt       DLTA0[0-9]
    arset1.3    lt       DLTB0[0-9]

If `archiver.cmd` file shown in CODE EXAMPLE 4-26 controls a file that is accessed frequently, it remains on disk all the time, even if it is older than 60 days. The copy 1 information is removed only if the file is not accessed for 60 days.

If the copy 1 information is removed (because the file was not accessed for 60 days) and someone stages the file from copy 2, it is read from tape. After the file is back online, the archiver makes a new copy 1 on disk and the 60-day access cycle starts all over again. The Sun StorEdge SAM-FS archiver regenerates a new copy 1 if the file is accessed again.

##### Example 2

Assume that a patient is in the hospital for four weeks. During this time, all of this patient's files are on fast media (copy 1=`mo`). After four weeks, the patient is released from the hospital. If no data has been accessed for this patient for up to 60 days after the patient is released, the copy 1 entry in the inode is unarchived, and only copy 2 and copy 3 entries are available. The volume can now be recycled in order to make room for more current patients without having to increase the disk library. If the patient comes back to the hospital after six months for a checkup, the first access of the data is from tape (copy 2). Now the archiver automatically creates a new copy 1 on disk to ensure that the data is back on the fast media during the checkup, which could take several days or weeks.

#### Controlling How Archive Files are Written: `-tapenonstop`

By default, the archiver writes a tape mark, an EOF label, and two more tape marks between archive files. When the next archive file is started, the driver backs up to the position after the first tape mark, causing a loss of performance. The `-tapenonstop` parameter directs the archiver to write only the initial tape mark. In addition, if the `-tapenonstop` parameter is specified, the archiver enters the archive information at the end of the copy operation.

For more information on the `-tapenonstop` parameter, see the `archiver.cmd`(4) man page.

#### Reserving Volumes: `-reserve`

By default, the archiver writes archive set copies to any volume specified by a regular expression as described in the volume associations section of the `archiver.cmd` file. However, it is sometimes desirable for archive set volumes to contain files from only one archive set. The process of reserving volumes can be used to satisfy this data storage requirement.

Note - The `-reserve` parameter reserves a volume for exclusive use by one archive set. A site that uses reserved volumes is likely to incur more cartridge loads and unloads.

The `-reserve` parameter reserves volumes for an archive set. When the `-reserve` parameter is set and a volume has been assigned to an archive set copy, the volume identifier is not assigned to any other archive set copy, even if a regular expression matches it.

As volumes are selected for use by an archive set, a reserved name is assigned to the volume. The reserved name is a unique identifier that ties the archive set to the volume.

The format for the `-reserve` parameter is as follows:

    -reserve keyword

The keyword specified depends on the form you are using. The possible forms are archive set form, owner form, and file system form, as follows:

- Archive set form. This form uses the set keyword, as follows: `-reserve` `set`

- Owner form. This form uses one of the following keywords: `dir`, `user`, or `group`. CODE EXAMPLE 4-27 shows the formats for these directives.

CODE EXAMPLE 4-27 Owner Forms for the `-reserve` Parameter
    -reserve dir
    -reserve user
    -reserve group

The three owner forms shown in CODE EXAMPLE 4-27 are mutually exclusive. That is, only one of the three owner forms can be used on an archive set and copy.

- File system form. This form uses the `fs` keyword, as follows: `-reserve` `fs`

In the `archiver.cmd` file, you can specify a `-reserve` parameter for one, two, or all three possible forms. The three forms can be combined and used together in an archive set parameter definition.

For example, CODE EXAMPLE 4-28 shows an `archiver.cmd` file fragment. The line that begins with `arset.1` creates a reserved name based upon an archive set, a group, and the file system.

CODE EXAMPLE 4-28 An `archiver.cmd` File With Reserved Volumes
    params
    arset.1 -reserve set -reserve group -reserve fs
    endparams

The information regarding reserved volumes is stored in the library catalog. The lines within the library catalog contain the media type, the VSN, the reserve information, and the reservation date and time. The reserve information includes the archive set component, path name component, and file system component, separated by slashes (//).

These slashes are not indicative of a path name; they are merely separators for displaying the three components of a reserved name. As CODE EXAMPLE 4-29 shows, the lines that describe reserved volumes begin with `#R` characters in the library catalog.

CODE EXAMPLE 4-29 Library Catalog Showing Reserved Volumes
         6  00071  00071 lt     0xe8fe   12 9971464 1352412 0x6a000000 131072 0x
    #      -il-o-b-----  05/24/00 13:50:02  12/31/69 18:00:00  07/13/01 14:03:00
    #R lt 00071 arset0.3// 2001/03/19 18:27:31
        10 ST0001 NO_BAR_CODE lt     0x2741    9 9968052 8537448 0x68000000 1310
    #      -il-o-------  05/07/00 15:30:29  12/31/69 18:00:00  04/13/01 13:46:54
    #R lt ST0001 hgm1.1// 2001/03/20 17:53:06
        16 SLOT22 NO_BAR_CODE lt     0x76ba    6 9972252 9972252 0x68000000 1310
    #      -il-o-------  06/06/00 16:03:05  12/31/69 18:00:00  07/12/01 11:02:05
    #R lt SLOT22 arset0.2// 2001/03/02 12:11:25

Note that some lines in CODE EXAMPLE 4-29 have been truncated to fit on the page.

One or more of the reserve information fields can be empty, depending on the options defined in the `archiver.cmd` file. The date and time indicate when the reservation was made. A reservation line is appended to the file for each volume that is reserved to an archive set during archiving.

You can display the reserve information by using the `samu`(1M) utility's `v` display or by using the `archiver`(1M) or `dump_cat`(1M) commands in one of the formats shown in CODE EXAMPLE 4-30.

CODE EXAMPLE 4-30 Commands to Use to Display the Reserve Information
    archiver -lv
    dump_cat -V catalog_name

The following formats illustrate each form showing the parameter, keywords, and examples of reserved names assigned to volumes.

- Archive set form. As TABLE 4-17 shows, the `set` keyword activates the archive set component in the reserved name.

TABLE 4-17 Archive Set Form Examples
Directive and Keyword | Reserved Name Examples
--- | ---
`-reserve set` | `users.1//`
| `Data.1//`

For example, in CODE EXAMPLE 4-31, the `archiver.cmd` file fragment shows that the line that begins with the `allsets` archive set name sets reserve by archive set for all archive sets.

CODE EXAMPLE 4-31 Reserving Volumes by Archive Set
    params
    allsets -reserve set
    endparams

- Owner form. The `dir`, `user`, and `group` keywords activate the owner component in the reserved name. The `dir`, `user`, and `group` keywords are mutually exclusive. The `dir` keyword uses the directory path component immediately following the path specification of the archive set definition. The `user` and `group` keywords are self-explanatory. TABLE 4-18 shows examples.

TABLE 4-18 Owner Set Form Examples
Directive and Keyword | Reserved Name Examples
--- | ---
`-reserve dir` | `proj.1/p105/`
| `proj.1/p104/`
`-reserve user` | `users.1/user5/`
| `users.1/user4/`
`-reserve group` | `data.1/engineering/`

Note - The `-reserve` parameter is intended to reserve a volume for exclusive use by one archive set. Many directories with a few small files cause many small archive files to be written to each reserved volume. These small discrete archive files slow the performance of the system because data files are relatively small compared to the `tar`(1) header for each archive file.

- File system form. The `fs` keyword activates the file system component in the Reserved Name. TABLE 4-19 shows examples.

TABLE 4-19 File System Form Examples
Directive and Keyword | Reserved Name Examples
--- | ---
`-reserve fs` | `proj.1/p103/samfs1`
| `proj.1/p104/samfs1`

Example 4 shows a complete archive example using reserved volumes.

The archiver records volume reservations in the library catalog files. A volume is automatically unreserved when it is relabeled because the archive data has been effectively erased.

You can also use the `reserve`(1M) and `unreserve`(1M) commands to reserve and unreserve volumes. For more information on these commands, see the `reserve`(1M) and `unreserve`(1M) man pages.

#### Setting Archive Priorities: `-priority`

The Sun StorEdge SAM-FS file systems offer a configurable priority system for archiving files. Each file is assigned a priority computed from properties of the file and priority multipliers that can be set for each archive set in the `archiver.cmd` file. Properties include online/offline, age, number of copies made, and size.

By default, the files in an archive request are not sorted and all property multipliers are zero. This results in files being archived in first found, first archived order. For more information on priorities, see the `archiver`(1M) and `archiver.cmd`(4) man pages.

You can control the order in which files are archived by setting priorities and sort methods. The following are examples of priorities that you can set:

- Select the `priority` sort method to archive files within an archive request in priority order.

- Change the `archive_loaded` priority to reduce media loads.

- Change the `offline` priority to cause online files to be archived before offline files.

- Change the `copy#` priorities to make archive copies in copy order.

TABLE 4-20 lists the archive priorities.

TABLE 4-20 Archive Priorities
Archive Priority | Definition
--- | ---
`-priority age` value | Archive age property multiplier
`-priority archive_immediate` value | Archive immediate property multiplier
`-priority archive_overflow` value | Multiple archive volumes property multiplier
`-priority archive_loaded` value | Archive volume loaded property multiplier
`-priority copy1` value | Copy 1 property multiplier
`-priority copy2` value | Copy 2 property multiplier
`-priority copy3` value | Copy 3 property multiplier
`-priority copy4` value | Copy 4 property multiplier
`-priority copies` value | Copies made property multiplier
`-priority offline` value | File offline property multiplier
`-priority queuewait` value | Queue wait property multiplier
`-priority rearchive` value | Rearchive property multiplier
`-priority reqrelease` value | Reqrelease property multiplier
`-priority size` value | File size property multiplier
`-priority stage_loaded` value | Stage volume loaded property multiplier
`-priority stage_overflow` value | Multiple stage volumes property multiplier

For value, specify a floating-point number in the following range:

    -3.400000000E+38  value  3.402823466E+38

#### Scheduling Archiving: `-startage`, `-startcount`, and `-startsize`

As the archiver scans a file system, it identifies files to be archived. Files that are recognized as candidates for archiving are placed in a list known as an archive request. At the end of the file system scan, the system schedules the archive request for archiving. The `-startage`, `-startcount`, and `-startsize` archive set parameters control the archiving workload and assure timely archival of files. TABLE 4-21 shows the formats for these parameters.

TABLE 4-21 The `-startage` , `-startcount` , and `-startsize` Directive Formats
Directive | Meaning
--- | ---
`-startage` time | Specifies the amount of time that can elapse between the first file in a scan being marked for inclusion in an archive request and the start of archiving. For time, specify a time in the format used in Setting the Archive Age.
`-startcount` count | Specifies the number of files to be included in an archive request. When the number of files in the archive request reaches count, archiving begins. Specify an integer number for count. By default, count is not set.
`-startsize` size | Specifies the minimum total size, in bytes, of all files to be archived in an archive request. Archiving work is accumulated and archiving begins when the total size of the files reaches size. By default, size is not set.

The `examine=`method directive and the `interval=`time directives are global directives that interact with the `-startage`, `-startcount`, and `-startsize` directives. The `-startage`, `-startcount`, and `-startsize` directives optimize archive timeliness versus archive work done. These values override the `examine=`method specification, if any. For more information on the `examine` directive, see The examine Directive: Controlling Archive Scans. For more information on the `interval` directive, see The interval Directive: Specifying an Archive Interval.

Only one of the `-startage`, `-startcount`, and `-startsize` directives can be specified in an `archiver.cmd` file. If more than one of these directives is specified, the first condition encountered starts the archival operation. If neither `-startage`, `-startcount`, nor `-startsize` are specified, the archive request is scheduled based on the `examine=`method directive, as follows:

- If `examine=noscan`, the archive request is scheduled according to the `interval=`time directive's specification after the first file is entered in the archive request. This is continuous archiving. By default, `examine=noscan`.

- If `examine=scan | scaninodes | scandirs`, the archive request is scheduled for archiving after the file system scan.

The `archiver.cmd`(4) man page has examples that show how to use these directives.

### VSN Association Directives

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

Collections of volumes are assigned to archive sets by directives of the following form:

    archive_set_name.copy_num media_type vsn_expr ... [ -pool vsn_pool_name ... ]

TABLE 4-22 Arguments for the VSN Association Directive
Argument | Meaning
--- | ---
archive_set_name | A site-defined name for the archive set. Must be the first field in the archive set assignment directive. An archive set name is usually indicative of the characteristics of the files belonging to the archive set. Archive set names are restricted to the letters in the alphabet, numbers, and the underscore character (_). No other special characters or spaces are allowed. The first character in the archive set name must be a letter.
copy_num | A digit that is followed by one or more arguments that specify archive characteristics for that copy. Archive copy directives begin with a digit. This digit (`1`, `2`, `3`, or `4`) is the copy number.
media_type | The media type. For a list of valid media types, see the `mcf`(4) man page.
vsn_expr | A regular expression. See the `regexp`(5) man page.
`-pool` vsn_pool_name | A named collection of VSNs.

An association requires at least three fields: the archive_set_name and copy_number, the media_type, and at least one volume. The archive_set_name and copy_number are connected by a period (.).

The following examples specify the same VSNs in different ways.

Example 1. CODE EXAMPLE 4-32 shows two lines of VSN specifications.

CODE EXAMPLE 4-32 VSN Specifications - Example 1
    vsns
    set.1  lt  VSN001 VSN002 VSN003 VSN004 VSN005
    set.1  lt  VSN006 VSN007 VSN008 VSN009 VSN010
    endvsns

Example 2. CODE EXAMPLE 4-33 shows a VSN specification that uses a backslash character (\) to continue a line onto a subsequent line.

CODE EXAMPLE 4-33 VSN Specifications - Example 2
    vsns
    set.1  lt  VSN001 VSN002 VSN003 VSN004 VSN005 \
     VSN006 VSN007 VSN008 VSN009 VSN010
    endvsns

Example 3. CODE EXAMPLE 4-34 specifies VSNs using a regular expression in a shorthand notation.

CODE EXAMPLE 4-34 VSN Specifications - Example 3
    vsns
    set.1 lt VSN0[1-9] VSN10
    endvsns

The volumes are noted by one or more vsn_expression keywords, which are regular expressions as described in the `regexp`(5) man page. Note that these regular expressions do not follow the same conventions as wildcards. In addition to a regular expression, you can also specify VSN pools from which volumes are to be selected. Pools are expressed with the `-pool` vsn_pool_name directive with a VSN association.

When the archiver needs volumes for the archive set, it examines each volume of the selected media type in all automated libraries and manually mounted drives to determine if it would satisfy any VSN expression. It selects the first volume that fits an expression that contains enough space for the archive copy operation. For example:

- The following directive specifies that files belonging to archive set `ex_set` for copy 1 be copied to media type `mo` using any of the twenty volumes with the name `optic20` through `optic39`:

    ex_set.1 mo optic[2-3][0-9]

- The following directive copies files belonging to archive set `ex_set` for copy 2 to media type `lt` with any volume beginning with `TAPE`:

    ex_set.2  lt  ^TAPE

If your Sun StorEdge SAM-FS environment is configured to recycle by archive set, do not assign a VSN to more than one archive set.

Note - Make sure you assign volumes to the archive set for the metadata when setting up the `archiver.cmd` file. Each file system has an archive set with the same name as the file system. For more information on preserving metadata, see the `samfsdump`(1M) man page or see the Sun QFS, Sun SAM-FS, and Sun SAM-QFS Disaster Recovery Guide.

### VSN Pools Directives

The VSN pools section of the `archiver.cmd` file starts with a `vsnpools` directive and ends with either an `endvsnpools` directive or with the end of the `archiver.cmd` file. This section names a collection of volumes.

A VSN pool is a named collection of volumes. VSN pools are useful for defining volumes that can be available to an archive set. As such, VSN pools provide a useful buffer for assigning volumes and reserving volumes to archive sets.

You can use VSN pools to define separate groups of volumes for use by departments within an organization, users within a group, data types, and other convenient groupings. The pool is assigned a name, media type, and a set of volumes. 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. For more information on VSN associations, see VSN Association Directives.

If a volume is reserved, it is no longer available to the pool in which it originated. Therefore, the number of volumes within a named pool changes as volumes are used. You can view the VSN pools by entering the `archiver`(1M) command in the following format:

    # archiver -lv | more

A VSN pool definition requires at least three fields separated by white space: the pool name, the media type, and at least one VSN. The syntax is as follows:

    vsn_pool_name media_type vsn_expression

TABLE 4-23 Arguments for the VSN Pools Directive
Argument | Meaning
--- | ---
vsn_pool_name | Specifies the VSN pool
media_type | The 2-character media type. For a list of valid media types, see the `mcf`(4) man page.
vsn_expression | Regular expression. There can be one or more vsn_expression arguments. See the `regcmp`(3G) man page.

The following example uses four VSN pools: `users_pool`, `data_pool`, `proj_pool`, and `scratch_pool`. If one of the three specific pools is out of volumes, the archiver selects the scratch pool VSNs. CODE EXAMPLE 4-35 shows an `archiver.cmd` file that uses four VSN pools.

CODE EXAMPLE 4-35 Example Showing VSN Pools
    vsnpools
    users_pool   mo ^MO[0-9][0-9]
    data_pool    mo ^DA.*
    scratch_pool mo ^SC[5-9][0-9]
    proj_pool    mo ^PR.*
    endvsnpools
    vsns
    users.1     mo    -pool users_pool   -pool scratch_pool
    data.1      mo    -pool data_pool    -pool scratch_pool
    proj.1      mo    -pool proj_pool    -pool scratch_pool
    endvsns

##

Disk Archiving

Archiving is the process of copying a file from online disk to archive media. Often, archive copies are written to volumes on magneto optical or tape cartridges in an automated library, but with disk archiving, online disk in a file system is used as archive media.

Disk archiving can be implemented so that the files are archived from one Sun StorEdge SAM-FS file system to another file system on the same host computer system. Disk archiving can also be implemented so the source files are archived to another file system on a different Sun Solaris system. When disk archiving is implemented using two host systems, the systems involved act as a client and a server. The client system is the system that hosts the source files. The server system is the destination system that hosts the archive copies.

The file system to which the archive files are written can be any UNIX file system. It does not have to be a Sun StorEdge SAM-FS file system. If disk archive copies are written to a different host, the host must have at least one Sun StorEdge SAM-FS file system installed upon it.

The archiver treats files archived to disk volumes the same as it treats files archived to volumes in a library. You can still make one, two, three, or four archive copies. If you are making multiple archive copies, one of the archive copies could be written to disk volumes while the others are written to removable media volumes. In addition, if you typically archive to disk volumes in a Sun StorEdge SAM-FS file system, the archive file copies are themselves archived according to the `archiver.cmd` file rules in that file system.

The following list summarizes some of the similarities and differences between archiving to online disk and archiving to removable media:

- Unlike archive copies written to a magneto optical disk or to a tape, archive copies written to disk are not recorded in a catalog. In addition, archive files in disk volumes do not appear in the historian.

- If you are archiving to removable media volumes, you can begin archiving after the file system is mounted without changing any of the default values in the `archiver.cmd` file. If you are archiving to disk volumes, however, you must edit the `archiver.cmd` file and define disk archive sets prior to mounting the file system.

- Disk archiving does not rely on entries in the `mcf`(4) file. You need to specify the `-disk_archive` parameter in the `archiver.cmd` file, and you need to define disk volumes in `/etc/opt/SUNWsamfs/diskvols.conf`. This is an additional configuration file, and it is not needed if you are archiving to removable media volumes only.

A `diskvols.conf` file must be created on the system upon which the source files reside. Depending on where the archive copies are written, this file also contains the following information:

- If the archive copies are written to a file system on that same host system, the `diskvols.conf` file defines the VSNs and the paths to each VSN.

- If the archive copies are written to a different Sun Solaris system, the `diskvols.conf` file contains the host name of that server system. In this case, there must also be a `diskvols.conf` file on the server system that defines clients that are given permission to write to that system. If you want to create this client/server relationship, make sure that the host acting as the server has at least one Sun StorEdge SAM-FS file system installed up on it before starting the procedure called To Enable Disk Archiving.

### Configuration Guidelines

While there are no restrictions on where disk archive volumes can reside, it is recommended that the disk volumes reside on a disk other than the one upon which the original files reside. Preferably, the archive copies from a client system would be written to disk volumes on a server system. It is recommended that you make more than one archive copy and write to more than one type of archive media. For example, copy 1 could be archived to disk volumes, copy 2 to tape, and copy 3 to magneto-optical disk.

If you are archiving files to a file system on a server system, the archive files themselves can be archived to removable media cartridges in a library attached to the destination server.

### Directives for Disk Archiving

When archiving to online disk, the archiver recognizes most of the `archiver.cmd` directives. The directives it recognizes define the archive set and configure recycling. The directives that are silently ignored are those that are meaningless in a disk archiving enviroment because they specifically pertain to working with removable media cartridges. Specifically, the system recognizes the following directives for disk archive sets:

- All the recycling directives in Archive Set Copy Parameters except for the following:

- `-fillvsns`

- `-ovflmin` min_size

- `-reserve` method

- `-tapenonstop`

- All the directives in Step 2: Editing the archiver.cmd File (Optional) except for the following:

- `-recycle_dataquantity` size

- `-recycle_vsncount` count

- The `-disk_archive` parameter. This is an archive set processing parameter. You must specify `-disk_archive` parameters in the `archiver.cmd` file to define disk archive set. The archiver uses this parameter to maintain the file system hierarchy of the data as it is written to the archive disk's mount point. Like all archive set processing parameters, it must be specified between the `params` and `endparams` directives. CODE EXAMPLE 4-36 shows the format of this directive.

CODE EXAMPLE 4-36 Format for the `-disk_archive` Parameter
    params
    archive_set.copy_number -disk_archive VSN_Name
    endparams

For VSN_Name, specify a VSN that is defined in the `diskvols.conf` file.

- The `clients` and `endclients` directives. If you implement disk archiving such that you archive source files from a client host to a server host, you must configure a `diskvols.conf` file on the server host. The `diskvols.conf` file on the server system must contain the name of the client system. The format for these directives is as follows:

CODE EXAMPLE 4-37 Format for the `clients` and `endclients` Directive
    clients
    client_system1
    client_system2
    ...
    endclients

For client_system, specify the hostname of the client system that contains the source files.

For more information on directives for disk archiving, see the `archiver.cmd`(4) man page.

### To Enable Disk Archiving

You can enable disk archiving at any time. The procedure in this section assumes that you have archiving in place and you are adding disk archiving to your environment. If you are enabling disk archiving as part of an initial installation, see the Sun StorEdge QFS and Sun StorEdge SAM-FS Software Installation and Configuration Guide for information. Do not use this procedure because it contains steps that are not needed if you add disk archiving at installation time.

1. Make certain that the host to which you want to write your disk archive copies has at least one Sun StorEdge SAM-FS file system installed on it.

2. Become superuser on the host system that contains the files to be archived.

3. Follow the procedures in the Sun StorEdge QFS and Sun StorEdge SAM-FS Software Installation and Configuration Guide for enabling disk archiving.

The Sun StorEdge SAM-FS initial installation procedure contains a step called Enabling Disk Archiving. That step is broken down into two procedures.

4. Become superuser on the host that contains the files to be archived.

5. On the host that contains the files to be archived, use the `samd`(1M) `config` command to propagate the configuration file changes and restart the system.

For example:

    # samd config

6. Become superuser on the host system to which the archive copies are written. (Optional)

Perform this step only if you are archiving to disk on a different host.

7. On the host to which the archive copies will be written, use the `samd`(1M) `config` command to propagate the configuration file changes and restart the destination system. (Optional)

Perform this step only if you are archiving to disk on a different host.

For example:

    # samd config

### Disk Archiving Examples

#### Example 1

CODE EXAMPLE 4-38 shows the `diskvols.conf` file that resides on client system `pluto`.

CODE EXAMPLE 4-38 The `diskvols.conf` File on `pluto`
    # This is file /etc/opt/SUNWsamfs/diskvols.conf on pluto
    # VSN Name     [Host Name:]Path
    #
    disk01                     /sam_arch1
    disk02                     /sam_arch2/proj_1
    disk03                mars:/sam_arch3/proj_3

In the preceding `diskvols.conf` file, VSNs identified as `disk01` and `disk02` are written to the host system upon which the original source files reside. VSN `disk03` is written to a VSN on server system `mars`.

CODE EXAMPLE 4-39 shows the `diskvols.conf` file on server system `mars`.

CODE EXAMPLE 4-39 The `diskvols.conf` File on `mars`
    # This is file /etc/opt/SUNWsamfs/diskvols.conf on mars
    #
    clients
    pluto
    endclients

CODE EXAMPLE 4-40 shows a fragment of the `archiver.cmd` file on `pluto`.

CODE EXAMPLE 4-40 The `archiver.cmd` File on `pluto`
    params
    arset1.2 -disk_archive disk01
    arset2.2 -disk_archive disk02
    arset3.2 -disk_archive disk03
    endparams

#### Example 2

In this example, file `/sam1/testdir0/filea` is in the archive set for `arset0.1`, and the archiver copies the content of `/sam1/testdir0/filea` to the destination path named `/sam_arch1`. CODE EXAMPLE 4-41 shows the `diskvols.conf` file.

CODE EXAMPLE 4-41 A `diskvols.conf` File
    # This is file /etc/opt/SUNWsamfs/diskvols.conf
    #
    # VSN Name   [Host Name:]Path
    #
    disk01                  /sam_arch1
    disk02                  /sam_arch12/proj_1

CODE EXAMPLE 4-42 shows the `archiver.cmd` file lines that pertain to disk archiving:

CODE EXAMPLE 4-42 Directives in the `archiver.cmd` File that Pertain to Disk Archiving
    .
    .
    .
    params
    arset0.1 -disk_archive disk01
    endparams
    .
    .
    .

The following shows output from the `sls`(1) command for file `filea`, which was archived to disk. In CODE EXAMPLE 4-43, note the following:

- `dk` is the media type for disk archive media

- `disk01` is the VSN

- `f192` is the path to the disk archive `tar`(1) file

CODE EXAMPLE 4-43 Output From `sls` (1M)
    # sls -D /sam1/testdir0/filea
    /sam1/testdir0/filea:
      mode: -rw-r-----  links:   1  owner: root      group: other
      length:    797904  admin id:      0  inode:     3134.49
      archdone;
      copy 1: ---- Dec 16 14:03        c0.1354 dk disk01 f192
      access:      Dec 19 10:29  modification: Dec 16 13:56
      changed:     Dec 16 13:56  attributes:   Dec 19 10:29
      creation:    Dec 16 13:56  residence:    Dec 19 10:32

#### Example 3

In this example, file `/sam2/my_proj/fileb` is on client host `snickers` in archive set `arset0.1`, and the archiver copies the content of this file to the destination path `/sam_arch1` on server host `mars`.

CODE EXAMPLE 4-44 shows the `diskvols.conf` file on `snickers`.

CODE EXAMPLE 4-44 The `diskvols.conf` File on `snickers`
    # This is file /etc/opt/SUNWsamfs/diskvols.conf on snickers
    #
    # VSN Name   [Host Name:]Path
    #
    disk01        mars:/sam_arch1

CODE EXAMPLE 4-45 shows the `diskvols.conf` file on `mars`.

CODE EXAMPLE 4-45 The `diskvols.conf` File on `mars`
    # This is file /etc/opt/SUNWsamfs/diskvols.conf on mars
    #
    clients
    snickers
    endclients

CODE EXAMPLE 4-46 shows the directives in the `archiver.cmd` file that relate to this example.

CODE EXAMPLE 4-46 Directives in the `archiver.cmd` File that Pertain to Disk Archiving
    .
    .
    .
    params
    arset0.1 -disk_archive disk01
    endparams
    .
    .
    .

##

Archiver Examples

TABLE 4-24 shows the directory structure that all examples in this section use.

TABLE 4-24 Directory Structure Example
Top-most Directory | 1st-level Subdirectory | 2nd-level Subdirectory | 3rd-level Subdirectory
--- | --- | --- | ---
`/sam` | `/projs` | `/proj_1` | `/katie`
`/sam` | `/projs` | `/proj_1` | `/sara`
`/sam` | `/projs` | `/proj_1` | `/wendy`
`/sam` | `/projs` | `/proj_2` | `/joe`
`/sam` | `/projs` | `/proj_2` | `/katie`
`/sam` | `/users` | `/bob` |
`/sam` | `/users` | `/joe` |
`/sam` | `/users` | `/katie` |
`/sam` | `/users` | `/sara` |
`/sam` | `/users` | `/wendy` |
`/sam` | `/data` |  |
`/sam` | `/tmp` |  |

### Example 1

This example illustrates the action of the archiver when no `archiver.cmd` file is used. In this example, a Sun StorEdge SAM-FS environment includes one file system, an optical automated library with two drives, and six cartridges.

CODE EXAMPLE 4-47 shows the output produced by the `archiver`(1M) `-lv` command. It shows that the default media selected by the archiver is type `mo`. Only the `mo` media are available.

CODE EXAMPLE 4-47 `archiver` (1M) `-lv` Example Output Part One
    # archiver -lv
    Notify file: /etc/opt/SUNWsamfs/scripts/archiver.sh
    Archive media:
    media:lt archmax: 512.0M Volume overflow not selected
    media:mo archmax:   4.8M Volume overflow not selected

CODE EXAMPLE 4-48 shows output that indicates that the archiver uses two drives. It lists the 12 volumes, storage capacity, and available space.

CODE EXAMPLE 4-48 `archiver` (1M) `-lv` Example Output Part Two
    Archive libraries:
    Device:hp30 drives_available:2 archive_drives:2
      Catalog:
      mo.optic00          capacity:  1.2G space: 939.7M  -il-o-------
      mo.optic01          capacity:  1.2G space: 934.2M  -il-o-------
      mo.optic02          capacity:  1.2G space: 781.7M  -il-o-------
      mo.optic03          capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic10          capacity:  1.2G space:  85.5M  -il-o-------
      mo.optic11          capacity:  1.2G space:  0      -il-o-------
      mo.optic12          capacity:  1.2G space: 618.9k  -il-o-------
      mo.optic13          capacity:  1.2G space: 981.3M  -il-o-------
      mo.optic20          capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic21          capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic22          capacity:  1.2G space: 244.9k  -il-o-------
      mo.optic23          capacity:  1.2G space:   1.1G  -il-o-------

CODE EXAMPLE 4-49 shows that both the metadata and data files are included in the archive set `samfs`. The archiver makes one copy of the files when their archive age reaches the default four minutes (240 seconds).

CODE EXAMPLE 4-49 `archiver` (1M) `-lv` Example Output Part Three
    Archive file selections:
    Filesystem samfs  Logfile:
    samfs Metadata
        copy:1  arch_age:240
    samfs1  path:.
        copy:1  arch_age:240

CODE EXAMPLE 4-50 shows the files in the archive sets archived to the volumes in the indicated order.

CODE EXAMPLE 4-50 `archiver` (1M) `-lv` Example Output Part Four
    Archive sets:
    allsets
    samfs.1
     media: mo (by default)
     Volumes:
       optic00
       optic01
       optic02
       optic03
       optic10
       optic12
       optic13
       optic20
       optic21
       optic22
       optic23
     Total space available:   8.1G

### Example 2

This example shows how to separate data files into two archive sets separate from the metadata. There is a manually mounted DLT tape drive in addition to the optical automated library from Example 2. The big files are archived to tape, and the small files are archived to optical cartridges.

CODE EXAMPLE 4-51 shows the content of the `archiver.cmd` file.

CODE EXAMPLE 4-51 `archiver` (1M) `-lv` Output Part One Showing the `archiver.cmd` File
    # archiver -lv -c example2.cmd
    Reading archiver command file "example2.cmd"
    1: # Example 2 archiver command file
    2: # Simple selections based on size
    3:
    4: logfile = /var/opt/SUNWsamfs/archiver/log
    5: interval = 5m
    6:
    7: # File selections.
    8: big . -minsize 500k
    9: all .
    10:    1 30s
    11:
    12: vsns
    13: samfs.1 mo .*0[0-2]       # Metadata to optic00 - optic02
    14: all.1 mo .*0[3-9] .*[1-2][0-9]  # All others for files
    15: big.1 lt .*
    16: endvsns

CODE EXAMPLE 4-52 shows the media and drives to be used, not the addition of the DLT and its defaults.

CODE EXAMPLE 4-52 `archiver` (1M) `-lv` Output Part Two Showing Media and Drives
    Notify file: /etc/opt/SUNWsamfs/scripts/archiver.sh
    Archive media:
    media:lt archmax: 512.0M Volume overflow not selected
    media:mo archmax:   4.8M Volume overflow not selected
    Archive libraries:
    Device:hp30 drives_available:0 archive_drives:0
      Catalog:
      mo.optic00        capacity:  1.2G space: 939.7M  -il-o-------
      mo.optic01        capacity:  1.2G space: 934.2M  -il-o-------
      mo.optic02        capacity:  1.2G space: 781.7M  -il-o-------
      mo.optic03        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic04        capacity:  1.2G space: 983.2M  -il-o-------
      mo.optic10        capacity:  1.2G space:  85.5M  -il-o-------
      mo.optic11        capacity:  1.2G space:   0     -il-o-------
      mo.optic12        capacity:  1.2G space: 618.9k  -il-o-------
      mo.optic13        capacity:  1.2G space: 981.3M  -il-o-------
      mo.optic20        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic21        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic22        capacity:  1.2G space: 244.9k  -il-o-------
      mo.optic23        capacity:  1.2G space:   1.1G  -il-o-------
    Device:lt40 drives_available:0 archive_drives:0
      Catalog:
      lt.TAPE01         capacity:  9.5G space:  8.5G  -il-o-------
      lt.TAPE02         capacity:  9.5G space:  6.2G  -il-o-------
      lt.TAPE03         capacity:  9.5G space:  3.6G  -il-o-------
      lt.TAPE04         capacity:  9.5G space:  8.5G  -il-o-------
      lt.TAPE05         capacity:  9.5G space:  8.5G  -il-o-------
      lt.TAPE06         capacity:  9.5G space:  7.4G  -il-o-------

CODE EXAMPLE 4-53 shows the organization of the file system. Files bigger than 512000 bytes (500 kilobytes) are archived after four minutes; all other files are archived after 30 seconds.

CODE EXAMPLE 4-53 `archiver` (1M) `-lv` Output Part Three Showing File System Organization
    Archive file selections:
    Filesystem samfs  Logfile: /var/opt/SUNWsamfs/archiver/log
    samfs Metadata
        copy:1  arch_age:240
    big  path:. minsize:502.0k
        copy:1  arch_age:240
    all  path:.
        copy:1  arch_age:30

CODE EXAMPLE 4-54 shows the division of the archive sets among the removable media in the following output.

CODE EXAMPLE 4-54 `archiver` (1M) `-lv` Output Part Four Showing Archive Sets and Removable Media
    Archive sets:
    allsets
    all.1
     media: mo
    Volumes:
       optic03
       optic04
       optic10
       optic12
       optic13
       optic20
       optic21
       optic22
       optic23
     Total space available:   6.3G
    big.1
     media: lt
    Volumes:
       TAPE01
       TAPE02
       TAPE03
       TAPE04
       TAPE05
       TAPE06
     Total space available:  42.8G
    samfs.1
     media: mo
    Volumes:
       optic00
       optic01
       optic02
     Total space available:   2.6G

### Example 3

In this example, user files and project data files are archived to various media. Files from the directory `data` are segregated by size to optical and tape media. Files assigned to the group ID `pict` are assigned to another set of volumes. Files in the directories `tmp` and `users/bob` are not archived. Archiving is performed on a 15-minute interval, and an archiving record is kept.

CODE EXAMPLE 4-55 shows this example.

CODE EXAMPLE 4-55 `archiver` (1M) `-lv -c` Command Output
    # archiver -lv -c example3.cmd
    Reading archiver command file "example3.cmd"
    1: # Example 3 archiver command file
    2: # Segregation of users and data
    3:
    4: interval = 30s
    5: logfile = /var/opt/SUNWsamfs/archiver/log
    6:
    7: no_archive tmp
    8:
    9: fs = samfs
    10: no_archive users/bob
    11: prod_big data -minsize 50k
    12:    1 1m 30d
    13:    2 3m
    14: prod data
    15:    1 1m
    16: proj_1 projs/proj_1
    17:    1 1m
    18:    2 1m
    19: joe . -user joe
    20:    1 1m
    21:    2 1m
    22: pict . -group pict
    23:    1 1m
    24:    2 1m
    25:
    26: params
    27: prod_big.1 -drives 2
    28: prod_big.2 -drives 2
    29: endparams
    30:
    31: vsns
    32: samfs.1 mo optic0[0-1]$
    33: joe.1 mo optic01$
    34: pict.1 mo optic02$
    35: pict.2 mo optic03$
    36: proj_1.1 mo optic1[0-1]$
    37: proj_1.2 mo optic1[2-3]$
    38: prod.1 mo optic2.$
    39: joe.2 lt 0[1-2]$
    40: prod_big.1 lt 0[3-4]$
    41: prod_big.2 lt 0[5-6]$
    42: endvsns
    Notify file: /etc/opt/SUNWsamfs/scripts/archiver.sh
    Archive media:
    media:lt archmax: 512.0M Volume overflow not selected
    media:mo archmax:   4.8M Volume overflow not selected
    Archive libraries:
    Device:hp30 drives_available:0 archive_drives:0
      Catalog:
      mo.optic00        capacity:  1.2G space: 939.7M  -il-o-------
      mo.optic01        capacity:  1.2G space: 934.2M  -il-o-------
      mo.optic02        capacity:  1.2G space: 781.7M  -il-o-------
      mo.optic03        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic04        capacity:  1.2G space: 983.2M  -il-o-------
      mo.optic10        capacity:  1.2G space:  85.5M  -il-o-------
      mo.optic11        capacity:  1.2G space:  0      -il-o-------
      mo.optic12        capacity:  1.2G space: 618.9k  -il-o-------
      mo.optic13        capacity:  1.2G space: 981.3M  -il-o-------
      mo.optic20        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic21        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic22        capacity:  1.2G space: 244.9k  -il-o-------
      mo.optic23        capacity:  1.2G space:   1.1G  -il-o-------
    Device:lt40 drives_available:0 archive_drives:0
      Catalog:
      lt.TAPE01          capacity:  9.5G space:  8.5G  -il-o-------
      lt.TAPE02          capacity:  9.5G space:  6.2G  -il-o-------
      lt.TAPE03          capacity:  9.5G space:  3.6G  -il-o-------
      lt.TAPE04          capacity:  9.5G space:  8.5G  -il-o-------
      lt.TAPE05          capacity:  9.5G space:  8.5G  -il-o-------
      lt.TAPE06          capacity:  9.5G space:  7.4G  -il-o-------
    Archive file selections:
    Filesystem samfs  Logfile: /var/opt/SUNWsamfs/archiver/log
    samfs Metadata
        copy:1  arch_age:240
    no_archive Noarchive path:users/bob
    prod_big  path:data minsize:50.2k
        copy:1  arch_age:60 unarch_age:2592000
        copy:2  arch_age:180
    prod  path:data
        copy:1  arch_age:60
    proj_1  path:projs/proj_1
        copy:1  arch_age:60
        copy:2  arch_age:60
    joe  path:. uid:10006
        copy:1  arch_age:60
        copy:2  arch_age:60
    pict  path:. gid:8005
        copy:1  arch_age:60
        copy:2  arch_age:60
    no_archive Noarchive path:tmp
    samfs  path:.
        copy:1  arch_age:240
    Archive sets:
    allsets
    joe.1
     media: mo
     Volumes:
       optic01
     Total space available: 934.2M
    joe.2
     media: lt
     Volumes:
       TAPE01
       TAPE02
     Total space available:  14.7G
    pict.1
     media: mo
     Volumes:
       optic02
     Total space available: 781.7M
    pict.2
     media: mo
     Volumes:
       optic03
     Total space available:   1.1G
    prod.1
     media: mo
     Volumes:
       optic20
       optic21
       optic22
       optic23
     Total space available:   3.3G
    prod_big.1
     media: lt drives:2
     Volumes:
       TAPE03
       TAPE04
     Total space available:  12.1G
    prod_big.2
     media: lt drives:2
     Volumes:
       TAPE05
       TAPE06
     Total space available:  16.0G
    proj_1.1
     media: mo
     Volumes:
       optic10
     Total space available:  85.5M
    proj_1.2
     media: mo
     Volumes:
       optic12
       optic13
     Total space available: 981.9M
    samfs.1
     media: mo
     Volumes:
       optic00
       optic01
     Total space available:   1.8G

### Example 4

In this example, user files and project data files are archived to optical media. Note that CODE EXAMPLE 4-56 does not use the directory structure presented in TABLE 4-24.

Four VSN pools are defined; three pools are used for user, data, and project, and one is a scratch pool. When the `proj_pool` runs out of media, it relies on the `scratch_pool` to reserve volumes. This example shows how to reserve volumes for each archive set based on the set component, owner component, and file system component. Archiving is performed on a 10-minute interval, and an archiving log is kept.

CODE EXAMPLE 4-56 shows the `archiver.cmd` file and archiver output.

CODE EXAMPLE 4-56 `archiver.cmd` File and Archiver Output
    Reading archiver command file "example4.cmd"
    1: # Example 4 archiver command file
    2: # Using 4 VSN pools
    3:
    4: interval = 30s
    5: logfile = /var/opt/SUNWsamfs/archiver/log
    6:
    7: fs = samfs
    8: users users
    9:     1 10m
    10:
    11: data data
    12:    1 10m
    13:
    14: proj projects
    15:    1 10m
    16:
    17: params
    18: users.1 -reserve user
    19: data.1 -reserve group
    20: proj.1 -reserve dir -reserve fs
    21: endparams
    22:
    23: vsnpools
    24: users_pool mo optic0[1-3]$
    25: data_pool mo optic1[0-1]$
    26: proj_pool mo optic1[2-3]$
    27: scratch_pool mo optic2.$
    28: endvsnpools
    29:
    30: vsn
    31: samfs.1 mo optic00
    32: users.1 mo -pool users_pool -pool scratch_pool
    33: data.1 mo -pool data_pool -pool scratch_pool
    34: proj.1 mo -pool proj_pool -pool scratch_pool
    35: endvsns
    Notify file: /etc/opt/SUNWsamfs/scripts/archiver.sh
    Archive media:
    media:mo archmax:   4.8M Volume overflow not selected
    Archive libraries:
    Device:hp30 drives_available:0 archive_drives:0
      Catalog:
      mo.optic00        capacity:  1.2G space: 939.7M  -il-o-------
      mo.optic01        capacity:  1.2G space: 934.2M  -il-o-------
      mo.optic02        capacity:  1.2G space: 781.7M  -il-o-------
      mo.optic03        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic04        capacity:  1.2G space: 983.2M  -il-o-------
      mo.optic10        capacity:  1.2G space:  85.5M  -il-o-------
      mo.optic11        capacity:  1.2G space:   0     -il-o-------
      mo.optic12        capacity:  1.2G space: 618.9k  -il-o-------
      mo.optic13        capacity:  1.2G space: 981.3M  -il-o-------
      mo.optic20        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic21        capacity:  1.2G space:   1.1G  -il-o-------
      mo.optic22        capacity:  1.2G space: 244.9k  -il-o-------
      mo.optic23        capacity:  1.2G space:   1.1G  -il-o-------
    Archive file selections:
    Filesystem samfs  Logfile: /var/opt/SUNWsamfs/archiver/log
    samfs Metadata
        copy:1  arch_age:240
    users  path:users
        copy:1  arch_age:600
    data  path:data
        copy:1  arch_age:600
    proj  path:projects
        copy:1  arch_age:600
    samfs  path:.
        copy:1  arch_age:240
    VSN pools:
    data_pool media: mo Volumes:
       optic10
     Total space available:  85.5M
    proj_pool media: mo Volumes:
       optic12
       optic13
     Total space available: 981.9M
    scratch_pool media: mo Volumes:
       optic20
       optic21
       optic22
       optic23
     Total space available:   3.3G
    users_pool media: mo Volumes:
       optic01
       optic02
       optic03
     Total space available:   2.7G
    Archive sets:
    allsets
    data.1
      reserve:/group/
     media: mo
     Volumes:
       optic10
       optic20
       optic21
       optic22
       optic23
     Total space available:   3.4G
    proj.1
      reserve:/dir/fs
     media: mo
     Volumes:
       optic12
       optic13
       optic20
       optic21
       optic22
       optic23
     Total space available:   4.2G
    samfs.1
     media: mo
     Volumes:
       optic00
     Total space available: 939.7M
    users.1
      reserve:/user/
     media: mo
     Volumes:
       optic01
       optic02
       optic03
       optic20
       optic21
       optic22
       optic23
     Total space available:   6.0G

##

Archiver Guidelines

The archiver automates storage management operations using the `archiver.cmd` file. Before writing this file, it is useful to review some general guidelines that can improve the performance of your Sun StorEdge SAM-FS file system and the archiver. This ensures that your data is stored in the safest way possible.

Each site is unique in its application of computing, data storage hardware, and software. The following recommendations are based upon the experiences of Sun Microsystems. When writing the `archiver.cmd` file for your site, be sure that you reflect the data storage requirements at your site by considering the following aspects.

1. Save your archive logs. The archive logs provide information that is essential to recovering data, even when the Sun StorEdge SAM-FS software is unavailable. It is recommended that you keep these logs in a safe place in the event of a catastrophic disaster during which the Sun StorEdge SAM-FS software is unavailable.

2. Use regular expressions for volumes. Let the system work for you by allowing it to put files on many different volumes. Volume ranges (specified using regular expressions) allow the system to run continuously. Using specific volume names for archive set copies can rapidly fill a volume, causing undue workflow problems as you remove a piece of media and replace it with another.

3. Base your archive interval on how often files are created and modified, and whether you want to save all modification copies. Remember, that the archive interval is the time between file system scans. A very short archive interval keeps the archiver scanning almost continuously.

4. Consider the number of file systems you are using. Multiple Sun StorEdge SAM-FS file systems generally increase the performance of the archiver as compared to a single Sun StorEdge SAM-FS file system. The archiver uses a separate process for each file system. Multiple file systems can be scanned in considerably less time than a single file system.

5. Use directory structures to organize your files within the Sun StorEdge SAM-FS file system like UNIX file systems. For performance considerations, Sun Microsystems recommends that you do not place more than 10,000 files in a directory.

6. Always make a minimum of two file copies on two separate volumes. Putting data on a single media type puts your data at risk if physical problems with the media occur. Do not rely on a single archive copy if at all possible.

7. Make sure you are dumping your metadata using `samfsdump`(1M) on a regular basis. The metadata (directory structure, file names, and so on) is stored in an archive set that has the same name as the file system. You can use this information to recover a file system in the event of a disaster. If you do not want to do this, you can prevent this data from being archived by assigning this archive set to a nonexistent VSN. For more information on preserving metadata, see the Sun QFS, Sun SAM-FS, and Sun SAM-QFS Disaster Recovery Guide or the Sun StorEdge QFS and Sun StorEdge SAM-FS Software Installation and Configuration Guide.

##

Troubleshooting the Archiver

Upon initial setup, the archiver might not perform the tasks as intended. Make sure that you are using the following tools to monitor the archiving activity of the system:

- `samu`(1M) utility's `a` display. This display shows archiver activity for each file system. It also displays archiver errors and warning messages, such as the following:

    Errors in archiver commands - no archiving will be done

The `samu`(1M) utility's `a` display includes messages for each file system. It indicates when the archiver will scan the `.inodes` file again and the files currently being archived.

- Archive logs. You can define these logs in the `archiver.cmd` file, and you should monitor them regularly to ensure that files are archived to volumes. Archive logs can become excessively large and should be reduced regularly either manually or by using a `cron`(1) job. Archive these log files for safekeeping because the information enables data recovery.

- `sfind`(1). Use this command to check periodically for unarchived files. If you have unarchived files, make sure you know why they are not being archived.

- `sls`(1). Files are not considered for release unless a valid archive copy exists. The `sls -D` command displays inode information for a file, including copy information.

Note - Output from the `sls -D` command might show the word `archdone` on a file. This is not an indication that the file has an archive copy. It is only an indication that the file has been scanned by the archiver and that all the work associated with the archiver itself has been completed. An archive copy exists only when you can view the copy information displayed by the `sls`(1) command.

Occasionally, you might see messages to indicate that the archiver either has run out of space on cartridges or has no cartridges. These messages are as follows:

- When the archiver has no cartridges assigned to an archive set, it issues the following message:

    No volumes available for Archive Set setname

- When the archiver has no space on the cartridges assigned to an archive set, it issues the following message:

    No space available on Archive Set setname

### Why Files Are Not Archiving

The following checklist includes reasons why your Sun StorEdge SAM-FS environment might not be archiving files.

1. The `archiver.cmd` file has a syntax error. Run the `archiver` `-lv` command to identify the error, then correct the flagged lines.

2. The `archiver.cmd` file has a `wait` directive in it. Either remove the `wait` directive or override it by using the `samu`(1M) utility's :`arrun` command.

3. No volumes are available. You can view this from `archiver`(1M) `-lv` command output. Add more volumes as needed. You might have to export existing cartridges to free up slots in the automated library.

4. The volumes for an archive set are full. You can export cartridges and replace them with new cartridges (make sure that the new cartridges are labeled), or you can recycle the cartridges. For more information on recycling, see Recycling.

5. The VSN section of the `archiver.cmd` file fails to list correct media. Check your regular expressions and VSN pools to ensure that they are correctly defined.

6. There is not enough space to archive any file on the available volumes. If you have larger files and it appears that the volumes are nearly full, the cartridges might be as full as the Sun StorEdge SAM-FS environment allows. If this is the case, add cartridges or recycle.

If you have specified the `-join path` parameter, and there is not enough space to archive all the files in the directory to any volume, no archiving occurs. You should add cartridges, recycle, or use one of the following parameters: `-sort path` or `-rsort path`. For more information on these parameters, see Associative Archiving: -join.

7. The `archiver.cmd` file has the `no_archive` directive set for directories or file systems that contain large files.

8. The `archive`(1)`-n` (archive never) command has been used to set too many directories, and files are never archived.

9. Large files are busy. Thus, they never reach their archive age and are not archived.

10. Hardware or configuration problems exist with the automated library.

11. Network connection problems exist between client and server. Ensure that the client and the server have established communications.

### Additional Archiver Diagnostics

In addition to examining the items on the previous list, you should check the following when troubleshooting the archiver.

1. The syslog file (by default, `/var/adm/sam-log`). This file can contain archiver messages that can indicate the source of a problem.

2. Volume capacity. Ensure that all required volumes are available and have sufficient space on them for archiving.

3. If the archiver appears to cause excessive, unexplainable cartridge activity or appears to be doing nothing, turn on the trace facility and examine the trace file. For information on trace files, see the `defaults.conf`(4) man page.

4. You can use the `truss`(1)`-p` pid command on the archiver process (`sam-archiverd`) to determine the system call that is not responding. For more information on the `truss`(1) command, see the `truss`(1) man page.

5. The `showqueue`(1M) command displays the content of the archiver queue files. You can use this command to observe the state of archiver requests that are being scheduled or archived. Any archive request that cannot be scheduled generates a message that indicates the reason. This command also displays the progress of archiving.

### Why Files Are Not Releasing

The archiver and the releaser work together to balance the amount of data available on the disk cache. The main reason that files are not released automatically from disk cache is that they have not yet been archived.

For more information on why files are not being released, see Troubleshooting the Releaser.

Copyright © 2004, Sun Microsystems, Inc. All rights reserved.