C H A P T E R 1

Overview

The Sun StorEdge SAM-FS environment provides a configurable file system with storage, archive management, and retrieval capabilities. The Sun StorEdge SAM-FS software archives files by copying the files from online disk cache to archive media. The archive media can consist of disk slices in another file system or it can consist of removable tape or magneto-optical cartridges in automated or manually loaded storage devices. In addition, the Sun StorEdge SAM-FS software automatically maintains online disk space at site-specified usage thresholds. It releases disk space associated with archived file data and restores the files to online disk when they are needed.

This chapter provides a technical overview of the Sun StorEdge SAM-FS components. The following topics are presented:

- Capabilities

- Storage Devices

- Commands

##

Capabilities

The Sun StorEdge SAM-FS environment includes a file system and the storage and archive management software. The Sun SAM-QFS environment includes the Sun StorEdge QFS file system. Both file systems are high-performance UNIX file systems that reside in the server's disk cache. The major difference between these file systems is that the Sun SAM-QFS file system offers more high-performance features, including a distributed shared file system. For more information about the file systems themselves, see the Sun StorEdge QFS and Sun StorEdge SAM-FS File System Administration Guide.

The other components that reside in the Sun StorEdge SAM-FS environment are as follows:

- The archiver, which automatically copies online disk cache files to archive media. The archive media can consist of either online disk files or removable media cartridges.

- The releaser, which automatically maintains the file system's online disk cache at site-specified percentage usage thresholds by freeing disk blocks occupied by eligible archived files.

- The stager, which restores file data to the disk cache. When a user or process requests file data that has been released from disk cache, the stager automatically copies the file data back to the online disk cache.

- he recycler, which clears archive volumes of expired archive copies and makes volumes available for reuse.

The following sections briefly describe each of these capabilities. You can find more information about these capabilities in subsequent chapters.

### Archiving

By default, the archiver automatically creates one archive copy of all files in a Sun StorEdge SAM-FS file system and it writes the archive copy to archive media. You can configure the archiver to create up to four archive copies on a variety of archive media. If a file is segmented, each segment is treated as a file, and each segment is archived separately. The archiving process is initiated after disk-based files match a site-definable set of selection criteria.

For more information about the archiver, see Archiving. For more information about segmented files, see Segmented Files.

### Releasing

Releasing is the process of freeing primary (disk) storage that is used by an archived file's data. Two threshold values, both expressed as a percentage of total disk space, are used to manage online disk cache free space. These thresholds are the high water mark and the low water mark. When online disk consumption exceeds the high water mark, the system automatically begins releasing the disk space occupied by eligible archived files. Disk space occupied by archived file data is released until the low water mark is reached. Files are selected for release depending on the file's size and age. Optionally, the first portion of a file can be retained on disk for speedy access and for masking staging delays. If a file has been archived in segments, portions of the file can be released individually. For more information about the releaser, see Releasing.

### Staging

When a file whose data blocks have been released is accessed, the stager automatically stages the file or file segment data back to online disk cache. The read operation tracks along directly behind the staging operation, allowing the file to be immediately available to an application before the entire file is completely staged.

The Sun StorEdge SAM-FS software processes stage request errors automatically. If a stage error is returned, the system attempts to find the next available archive copy of the file. Stage errors that can be automatically processed include media errors, unavailability of media, unavailability of an automated library, and others. For more information about staging, see Staging.

### Recycling

As users modify files, archive copies associated with the old versions of these files are considered to be expired on their archive media. Such copies are no longer needed, so they can be purged from the system. The recycler identifies the archive volumes with the largest proportions of expired archive copies and preserves the nonexpired copies by moving them to separate volumes.

If a removable media volume contains only expired copies, you can take one of the following actions:

- You can relabel the volume for immediate reuse.

- You can export the volume to offsite storage as an historical record of file changes. You can use standard UNIX utilities to restore previous versions of files from expired archive copies.

The recycling process is transparent to end users as it relates to their data files. For more information about recycling, see Recycling.

##

Storage Devices

The Sun StorEdge SAM-FS environment supports a wide variety of tape storage and magneto-optical devices. The automated libraries that Sun StorEdge SAM-FS supports can be divided into the following groups depending on how they are attached to the environment:

- A direct attachment. A direct-attached library is connected directly to the host system using a small computer system interface (SCSI). This can be either a direct connection or a Fibre Channel connection. For example, a direct attachment is used for Sun StorEdge libraries. The Sun StorEdge SAM-FS system controls these libraries directly using the SCSI standard for automated libraries.

- A network attachment. The Sun StorEdge SAM-FS software can be configured as a client of the library's host system. The network-attached libraries include some of the StorageTek, ADIC/Grau, IBM, and Sony libraries. These libraries use a software package supplied by the vendor. In these cases, the Sun StorEdge SAM-FS software interfaces with the vendor software using a daemon specifically designed for the automated library.

TABLE 1-1 shows the daemons specific to various automated libraries.

TABLE 1-1 Automated Library Daemons
Daemon | Description
--- | ---
`sam-robotsd` | Monitors the execution of robot control daemons. The `sam-robotsd` daemon is started automatically by the `sam-amld` daemon.
`sam-genericd` | Controls direct-attached libraries and media changers. Also controls ADIC libraries through the DAS interface.
`sam-stkd` | Controls the StorageTek media changers through the ACSAPI interface.
`sam-ibm3494d` | Controls the IBM 3494 tape libraries through the `lmcpd` interface.
`sam-sonyd` | Controls the Sony network-attached automated libraries through the DZC-8000S interface.

For a list of supported storage devices, contact your Sun Microsystems sales representative or your authorized service provider (ASP).

The relationships between the devices managed within the Sun StorEdge SAM-FS environment are defined in the master configuration file, `/etc/opt/SUNWsamfs/mcf`. The `mcf` file specifies the removable media devices, libraries, and file systems included in the Sun StorEdge SAM-FS environment. Each piece of equipment is assigned a unique equipment identifier in the `mcf` file. Entries in the `mcf` also define manually mounted archiving devices and automated library catalog files.

When possible, the system uses the standard Solaris disk and tape device drivers. For devices not directly supported in the Solaris operating system (OS), such as certain library and optical disk devices, special device drivers are included in the Sun StorEdge SAM-FS software packages.

##

Commands

The Sun StorEdge QFS and Sun StorEdge SAM-FS environments consist of a file system, daemons, processes, various types of commands (user, administrator, and so on), and tools. This section describes the commands that are included in the Sun StorEdge QFS and Sun StorEdge SAM-FS software distributions.

The Sun StorEdge QFS and Sun StorEdge SAM-FS commands operate in conjunction with the standard UNIX file system commands. Some commands are specific to only one product. All the commands are documented in UNIX `man`(1) pages.

The Sun StorEdge QFS and Sun StorEdge SAM-FS File System Administration Guide contains overview information for the daemons, but individual daemons are described throughout the documentation set where appropriate.

This section introduces the commands and indicates which commands you can use within the Sun StorEdge QFS or Sun StorEdge SAM-FS file systems. See the man pages that are included in the software distribution for more information.

This section contains the following topics:

- User Commands

- General System Administrator Commands

- File System Commands

- Automated Library Commands

- Archiver Commands

- Specialized Maintenance Commands

- Site-Customizable Scripts

- Application Programming Interface

- Operational Utilities

### User Commands

By default, file system operations are transparent to the end user. Depending on your site practices, however, you might want to make some commands available to users at your site to fine-tune certain operations. TABLE 1-2 summarizes these commands.

TABLE 1-2 User Commands
Command | Description | Used By
--- | --- | ---
`archive`(1) | Archives files and sets archive attributes on files. | Sun StorEdge SAM-FS
`release`(1) | Releases disk space and sets release attributes on files. | Sun StorEdge SAM-FS
`request`(1) | Creates a removable media file. | Sun StorEdge SAM-FS
`sdu`(1) | Summarizes disk usage. The sdu(1) command is based on the GNU version of the du(1) command. | Sun StorEdge QFS Sun StorEdge SAM-FS
`segment`(1) | Sets segmented file attributes. | Sun StorEdge SAM-FS
`setfa`(1) | Sets file attributes. | Sun StorEdge QFS Sun StorEdge SAM-FS
`sfind`(1) | Searches for files in a directory hierarchy. The sfind(1) command is based on the GNU version of the find(1) command and contains options for searching based on Sun StorEdge QFS and Sun StorEdge SAM-FS file attributes. | Sun StorEdge QFS Sun StorEdge SAM-FS
`sls`(1) | Lists contents of directories. The sls(1) command is based on the GNU version of the ls(1) command and contains options for displaying file system attributes and information. | Sun StorEdge QFS Sun StorEdge SAM-FS
`squota`(1) | Reports quota information. | Sun StorEdge QFS Sun StorEdge SAM-FS
`ssum`(1) | Sets the checksum attributes on files. | Sun StorEdge SAM-FS
`stage`(1) | Sets stage attributes on files and copies offline files to disk. | Sun StorEdge SAM-FS

### General System Administrator Commands

TABLE 1-3 summarizes the commands that you can use to maintain and manage the system.

TABLE 1-3 General System Administrator Commands
Command | Description | Used By
--- | --- | ---
`samcmd`(1M) | Executes one `samu`(1M) operator interface utility command. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samd`(1M) | Starts or stops robotic and removable media daemons. | Sun StorEdge SAM-FS
`samexplorer`(1M) | Generates a Sun StorEdge QFS or Sun StorEdge SAM-FS diagnostic report script | Sun StorEdge QFS Sun StorEdge SAM-FS
`samset`(1M) | Changes Sun StorEdge SAM-FS settings. | Sun StorEdge SAM-FS
`samu`(1M) | Invokes the full-screen, text-based operator interface. This interface is based on the `curses`(3CURSES) software library. The `samu` utility displays the status of devices and allows the operator to control automated libraries. | Sun StorEdge QFS Sun StorEdge SAM-FS

### File System Commands

TABLE 1-4 summarizes the commands that you can use to maintain the file system.

TABLE 1-4 File System Commands
Commands | Description | Used By
--- | --- | ---
`mount`(1M) | Mounts a file system. The man page name for this command is `mount_samfs`(1M). | Sun StorEdge QFS Sun StorEdge SAM-FS
`qfsdump`(1M) `qfsrestore`(1M) | Creates or restores a dump file containing the file data and metadata associated with a Sun StorEdge QFS file system. | Sun StorEdge QFS
`sambcheck`(1M) | Lists block usage for a file system. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samchaid`(1M) | Changes file admin set ID attribute. For use with quotas. | Sun StorEdge QFS Sun StorEdge SAM-FS
samfsck(1M) | Checks and repairs metadata inconsistencies in a file system and reclaims allocated, but unused, disk space. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samfsconfig`(1M) | Displays configuration information. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samfsdump`(1M) `samfsrestore`(1M) | Creates or restores a dump file of the metadata associated with a Sun StorEdge SAM-FS file system. | Sun StorEdge SAM-FS Sun SAM-QFS
`samfsinfo`(1M) | Displays information about the layout of a Sun StorEdge QFS or Sun StorEdge SAM-FS file system. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samfstyp`(1M) | Determines the Sun StorEdge QFS or Sun StorEdge SAM-FS file system type. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samgrowfs`(1M) | Expands a file system by adding disk devices. | Sun StorEdge QFS Sun StorEdge SAM-FS
`sammkfs`(1M) | Initializes a new file system from disk devices. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samncheck`(1M) | Returns a full directory path name given the mount point and inode number. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samquota`(1M) | Reports, sets, or resets quota information. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samquotastat`(1M) | Reports on active and inactive file system quotas. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samsharefs`(1M) | Manipulates the Sun StorEdge QFS shared file system configuration information. | Sun StorEdge QFS
`samtrace`(1M) | Dumps the trace buffer. | Sun StorEdge QFS Sun StorEdge SAM-FS
`samunhold`(1M) | Releases SANergy file holds. | Sun StorEdge QFS Sun StorEdge SAM-FS
`trace_rotate`(1M) | Rotates trace files. | Sun StorEdge QFS Sun StorEdge SAM-FS

### Automated Library Commands

TABLE 1-5 summarizes the automated library commands that you can use to configure, initialize, and maintain the automated libraries and devices within the Sun StorEdge SAM-FS environment.

TABLE 1-5 Automated Library Commands
Command | Description
--- | ---
`auditslot`(1M) | Audits a single media cartridge slot within a specified automated library.
`build_cat`(1M) | Builds a media catalog file for an automated library. Optionally, can also populate the catalog file.
`chmed`(1M) | Sets or clears library catalog flags and values on a specific cartridge.
`cleandrive`(1M) | Requests that a tape drive be loaded with a cleaning tape.
`dump_cat`(1M) | Displays the content of a binary catalog file in various ASCII formats.
`import`(1M) `samexport`(1M) | Imports or exports cartridges from a library by placing it in the mailbox. For network-attached libraries, this command updates the library catalog, but it does not physically move cartridges.
`samload`(1M) `unload`(1M) | Loads or unloads a cartridge for a specified device.
`move`(1M) | Moves a cartridge from one slot to another.
`odlabel`(1M) | Labels optical disks for use with the Sun StorEdge SAM-FS system.
`samdev`(1M) | Adds `/dev/samst` logical device entries. Used to communicate automated library, optical disk, and tape drive information.
`tplabel`(1M) | Labels tapes for use with the Sun StorEdge SAM-FS system.

### Archiver Commands

TABLE 1-6 summarizes the commands that control the archiver's actions within the Sun StorEdge SAM-FS environment.

TABLE 1-6 Archiver Commands
Command | Description
--- | ---
`archiver`(1M) | Evaluates the archiver commands file for syntax completeness and semantic accuracy.
`archiver.sh`(1M) | Logs exceptional archiver events.
`showqueue`(1M) | Displays the content of an archiver queue file.
`reserve`(1M) `unreserve`(1M) | Reserves and unreserves volumes.

### Specialized Maintenance Commands

TABLE 1-7 summarizes the various maintenance commands you can use in a Sun StorEdge SAM-FS environment.

TABLE 1-7 Specialized Maintenance Commands
Command | Description
--- | ---
`archive_audit`(1M) | Generates a report of all archived files on each cartridge.
`dmpshm`(1M) | Dumps the shared memory segments.
`exarchive`(1M) | Manipulates (exchanges) archive copies.
`itemize`(1M) | Catalogs an optical disk.
`rearch`(1M) `unrearch`(1M) | Marks or unmarks archive entries to be rearchived.
`sam-recycler`(1M) | Reclaims space used by expired archive copies from archive media.
`sam-releaser`(1M) | Releases disk space from online disk cache file systems.
`samdev`(1M) | Creates symbolic links in the `/dev/samst` directory that point to the actual devices to be used by the Sun StorEdge SAM-FS file system. This command is similar in function to the UNIX `makedev`(1M) command.
`samset`(1M) | Changes or displays variables used in Sun StorEdge SAM-FS operations.
`set_admin`(1M) | Adds or removes permission for an administrator group to execute administrator commands.
`set_state`(1M) | Sets the state of a Sun StorEdge SAM-FS device.
`stageback.sh`(1M) | Stages files from Sun StorEdge SAM-FS or Sun SAM-QFS archive tapes
`star`(1M) | Creates tape archives and adds or extracts files. This is a GNU version of the `tar`(1) command, and it has been extended for use with the Sun StorEdge SAM-FS file system. You can use this command in a disaster recovery situation if you need to read data from archive tapes.
`tapealert`(1M) | Decodes TapeAlert events.
`unarchive`(1M) | Deletes archive entries for one or more files.
`undamage`(1M) | Marks an archive entry for one or more files or directories as undamaged.

### Site-Customizable Scripts

TABLE 1-8 summarizes the site-customizable scripts that you can use to monitor and control the Sun StorEdge SAM-FS environment. By default, the software installs these scripts in `/opt/SUNWsamfs/examples`. You can move these scripts from `/opt/SUNWsamfs/examples` to `/etc/opt/SUNWsamfs/scripts` and modify them to perform the desired action for your site. For more information about these scripts, see their respective man pages.

TABLE 1-8 Site-Customizable Scripts
Script | Description
--- | ---
`dev_down.sh`(1M) | Sends email to `root` when a device is marked `down` or `off`.
`load_notify.sh`(1M) | Notifies the operator when the Sun StorEdge SAM-FS software requests a cartridge that resides outside the library.
`log_rotate.sh`(1M) | Rotates log files.
`recover.sh`(1M) | Recovers files archived after the last `samfsdump`(1M) was taken.
`restore.sh`(1M) | Restores files to their online or partially online status.
`stageback.sh`(1M) | Stages files from archive media.
`tarback.sh`(1M) | Reloads files from archive media.

### Application Programming Interface

You can use the application programming interface (API) to make file system requests from within a user application. The requests can be made locally or remotely to the machine on which the file system is running. The API consists of the `libsam` and `libsamrpc` libraries. These libraries contain library routines for obtaining file status; for setting archive, release, and stage attributes for a file; and for manipulating the library catalog of an automated library. The `sam-rpcd` remote procedure call daemon handles remote requests. To automatically start the `sam-rpcd` daemon, set `samrpc=on` in the `defaults.conf` file.

For more information about the API, see the `intro_libsam`(3) man page. This man page provides overview information for using the library routines in `libsam` and `libsamrpc`.

### Operational Utilities

Within the Sun StorEdge SAM-FS environment, you can use the `samu`(1M) operator utility and SAM-QFS Manager to perform basic operations. TABLE 1-9 summarizes the operational tools.

TABLE 1-9 Operational Tools
GUI Tools | Description
--- | ---
SAM-QFS Manager | Provides a web-based graphical user interface to the Sun StorEdge QFS and Sun StorEdge SAM-FS software. You can use this interface to configure, control, monitor, and reconfigure the components of your Sun StorEdge QFS and Sun StorEdge SAM-FS environment. For information on installing SAM-QFS Manager, see the Sun StorEdge QFS and Sun StorEdge SAM-FS Software Installation and Configuration Guide. For information on using the SAM-QFS Manager, see its online help.
`samu`(1M) | Provides the starting point for accessing the `samu`(1M) operator utility.

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