C H A P T E R 9

Advanced Topics

This chapter discusses advanced topics that are beyond the scope of basic system administration and usage.

The following topics are presented.

- Device Logging

- Removable Media Files

- Segmented Files

- System Error Facility Reporting

##

Device Logging

The device-logging facility provides device-specific error information that you can use to analyze certain types of device problems. It can help to determine a failing sequence of events for an automated library, tape drive, or optical drive. Note that the device-logging facility does not collect soft media errors (such as recoverable read errors).

Device-logging messages are written to individual log files. There is a log file for each automated library, each tape and optical drive device, and one for the historian. The log files are located in `/var/opt/SUNWsamfs/devlog`. The name of each individual log file is the same name as the Equipment Ordinal.

Example. Assume a Sun StorEdge SAM-FS file system and a single Hewlett Packard optical library with two optical drives.

CODE EXAMPLE 9-1 shows the `mcf` file.

CODE EXAMPLE 9-1 Example `mcf` File
    /dev/samst/c1t5u0  40  hp  hp40  -  etc/opt/SUNWsamfs/hp40_cat
    /dev/samst/c1t4u0  41  mo  hp40  -
    /dev/samst/c1t6u0  42  mo  hp40  -

CODE EXAMPLE 9-2 shows the `/var/opt/SUNWsamfs/devlog` file.

CODE EXAMPLE 9-2 The `devlog` File
    # pwd
    /var/opt/SUNWsamfs/devlog
    # ls
    40      41      42      43
    #

Device 43 is the historian.

### When to Use the Device Log

The device log can easily generate many log messages, especially when all logging options for all devices are turned on and there is a great deal of device activity. Initially, the device log settings are set to the following default values:

    err retry syserr date

If you suspect there is a problem with one of the devices configured within a Sun StorEdge SAM-FS environment, it is appropriate to enable additional logging events for that device. Also, it is appropriate to enable device logging if you are advised to do so by your service provider. In these situations, set the event to `detail`. In extreme cases, you might be advised by your service provider to set the event to `all` for a device. This adds additional log information. However, in general, it is probably not useful or practical to run the system with excessive logging.

The device log information is collected automatically when the `samexplorer`(1M) command is issued. This allows the file system service to review any possible device error information as part of problem analysis activity.

### Enabling the Device Log

There are two methods you can use to enable the device log.

For both method 1 and method 2:

- eq is the Equipment Ordinal of the device from the `mcf` file or the keyword `all` for all equipment.

- The device-logging events are listed in the `samset`(1M) man page. They are also listed in Enabling the Device Log. Note that the device log messages are available only in English text. An event is one or more event types from the following list:

- `all`

- `date`

- `default`

- `detail`

- `err`

- `event`

- `label`

- `mig`

- `module`

- `msg`

- `none`

- `retry`

- `stage`

- `stage_ck`

- `syserr`

- tapealert

- `time`

You can enable the device log in one of two ways. These procedures are as follows:

- To Enable the Device Log By Using the samset(1M) Command

- To Enable the Device Log by Editing the defaults.conf File

To Enable the Device Log By Using the `samset`(1M) Command

Use the `samset`(1M) command.

For example:

    # samset devlog eq event

For more information about the `samset`(1M) command, see the `samset`(1M) man page.

To Enable the Device Log by Editing the `defaults.conf` File

1. Become superuser.

2. Use `vi`(1) or another editor to open ``file `/etc/opt/SUNWsamfs/defaults.conf`.

3. Add the `devlog` directive in the `defaults.conf` file.

Add the following directive:

    devlog eq event

For eq, specify the Equipment Ordinal of the device for which you want to log messages.

For event, specify one or more of the events described in Enabling the Device Log. If you specify more than one event, separate them with space characters.

When a Sun StorEdge SAM-FS file system starts up, it automatically sets the event type for each available device to `default`. You can also use the `samset`(1M) command to determine the present settings for each device log.

4. Save and close the `defaults.conf` file.

5. Use the `samd`(1M) `config` command to propagate the `defaults.conf` file changes.

    # samd config

##

Removable Media Files

You can use the `request`(1) command to manually create, write, and read files that do not use the disk cache for buffering the data. Files created in this manner are called removable media files.

Removable media files look like typical Sun StorEdge SAM-FS files in that they have permissions, a user name, a group name, and size characteristics. However, the data does not reside in the disk cache. Thus, you can create files that are larger than the disk cache and write them to removable media cartridges. The system creates an inode entry in the `.inodes` file for the file that you specify on the `request`(1) command. The user does not need to know where the file begins on the removable media. (It is the same for a file with data in the disk cache.) The Sun StorEdge SAM-FS file systems read that information from the inode entry. Multiple removable media files can reside on the same volume.

If the removable media file spans multiple volumes, it is called a volume overflow file. The volume overflow feature enables the system to span a single file over multiple volumes on multiple cartridges. A volume overflow file is a type of removable media file. The volume overflow feature is useful if you have very large files that exceed the capacity of their chosen media.

### To Create a Removable Media or Volume Overflow File

1. Use the `tplabel`(1M) or `odlabel`(1M) command to label a tape or magneto-optical cartridge.

For information on these commands, see their respective man pages.

2. Use the `request`(1) command.

At a minimum, use the following options:

    request -m media_type -v vsn [vsn/vsn ...] [-l vsn_file] input_file

TABLE 9-1 Arguments for the `request` (1) Command
Argument | Meaning
--- | ---
media_type | The media type of the removable media cartridge. For information about valid media_type specifications, see the `mcf`(4) man page.
vsn | The Volume Serial Name of the removable media cartridge. If you specify more than one vsn, you are creating a volume overflow file. You can specify up to 256 vsns for volume overflow files. Use forward slash characters (`/`) to separate the vsn arguments. The vsns specified should not be among the volumes that are used in a Sun StorEdge SAM-FS environment for automated archiving. Archiving appends the next file to be archived to the end of the current data and moves the EOF label beyond the data each time.
vsn_file | An input file that contains a list of vsns. If you have many vsns, it can be easier to specify the list of vsns in an input file rather than on the command line.
input_file | The file to be written to the removable media cartridge. This file must reside in a Sun StorEdge SAM-FS file system.

Example 1. The following command creates a removable media file:

    # request -m lt -v aaa rem1

Example 2. The following command creates a volume overflow file on three volumes:

    # request -m lt -v TAPE01/TAPE02/TAPE03 large.file

You must read and write removable media files sequentially. The Sun StorEdge SAM-FS file system automatically mounts the requested volume if the volume resides in an automated library defined in the `mcf` file.

The presence of a removable media file on a volume prevents that volume from being recycled. The recycler expects that only archived files reside on the particular volume that is assigned for archiving. In addition, the removable media files are never archived.

Removable media files are not supported over NFS.

Using the `request`(1) command bypasses the typical functions of the archiver.

For examples that describe how to create removable media files, see the `request`(1) man page.

##

Segmented Files

The Sun StorEdge SAM-FS environments support segmented files. Segmenting files improves tape storage retrieval speed, access, and manageability for very large files. A segmented file can be larger than the physical disk cache. With a segmented file, it is possible for only part of a file to reside on the disk cache at any one time.

The `segment`(1) command allows you to specify the segment size. You cannot set a segment size that is smaller than the current file size.

Segmented files support tape striping. After a file is segmented, it can be striped simultaneously over multiple tape devices, which significantly reduces the time needed to store the file segments. Data access is accelerated by allowing users to retrieve only the desired file segments rather than the entire file.

Segmentation can enhance archiving efficiency because only changed portions of a file are rearchived. Segments of a file can be archived in parallel, and segmented files can be staged in parallel. This increases performance when archiving and retrieving.

Segmentation can be enabled on a file, directory, or entire file system. Segmented files support all other Sun StorEdge SAM-FS capabilities.

The following sections describe how segmented files differ from nonsegmented files. For more information about segmented files, see the `segment`(1) or the `sam_segment`(3) man pages.

### Archiving

For a segmented file, the archivable unit is the segment itself, not the file. All archiving properties and priorities apply to the individual segments, and not to the file.

The unit archived is the segment. You can stripe a segment by specifying both the `-drives` and `-drivemin` parameters for the archive set in the `archiver.cmd` file.

For example, assume that there is a 100-megabyte segmented file in the file system, and its segment size is 10 megabytes. If the `archiver.cmd` file defines an archive set with a `-drives` `2` directive, this file is archived to 2 drives in parallel. Segments 1, 3, 5, 7, and 9 are archived using the first drive, and segments 2, 4, 6, 8, and 10 are archived using the second drive.

Only segments that have been modified are archived--not the entire file. Up to four archive copies can be made for each segment. Sun StorEdge SAM-FS supports volume overflow for segments.

Note - The index of a segmented file contains no user data. It is considered metadata. It is assigned to the file system archive set.

### Disaster Recovery

For information about recovering a segmented file in the event of a disaster, see the Sun QFS, Sun SAM-FS, and Sun SAM-QFS Disaster Recovery Guide.

##

System Error Facility Reporting

The system error facility (SEF) reporting system captures log sense data from tape devices in an automated library, writes it to a log file, and translates that data into human-readable form. It consists of the following:

- A log file containing data from tape device log sense pages.

- A command, `sefreport`(1M), for writing the log file to `stdout` in a human-readable format. This log file can be used as input to a user-supplied analysis script.

The `sefreport`(1M) command reads the content of a Sun StorEdge SAM-FS SEF log file. The log file contains data gathered from the log sense pages of the peripheral tape devices used in a Sun StorEdge SAM-FS environment. The log sense pages differ from vendor to vendor. For the meanings of the parameter codes, control bits, and parameter values, see the vendor documentation for each specific device.

SEF is not supported for standalone tape drives. SEF reporting is most useful for older SCSI-2 devices that do not support the `tapealert`(1M) functionality. For more information, see the `tapealert`(1M) man page.

### To Enable SEF Reporting

1. Become superuser.

2. Use the `mkdir`(1) command to create the SEF directory.

For example:

    # mkdir /var/opt/SUNWsamfs/sef

3. Use the `touch`(1) command to enable SEF reporting.

You can enable SEF reporting any time after installation by creating the `sefdata` log file. Initially, the SEF log file must be empty.

    # touch /var/opt/SUNWsamfs/sef/sefdata

The preceding example command shows the SEF log file being created in `/var/opt/SUNWsamfs/sef/sefdata`. This is the default location.

4. Use the `samd`(1M) `stop` and `samd`(1M) `start` to initialize SEF reporting.

For example:

    # samd stop
    # samd start

SEF data is appended to the log file as it is generated.

You can configure SEF reporting to log and read log sense data from an alternate location. For more information about reading log sense data from an alternate location, see the `sefreport`(1M) man page.

### SEF Report Output

Before you use the `sefreport`(1M) command, ensure that `/opt/SUNWsamfs/sbin` is in your command path. The SEF report output consists of header lines and log sense data.

Following the header lines, the log sense data for each page in the record is printed. For each log sense page, a line identifying the page code is printed, followed by a line of column headings. The data is then printed, three columns per line, with the following headings: `param code`, `control`, and `param value`. All data is generated in hexadecimal notation.

To Generate SEF Output

Use the `sefreport`(1M) command to generate SEF output.

The following are the most commonly used options on the `sefreport`(1M) command:

- The `-d` option. The `-d` option generates additional device information. It writes an additional header line that contains the Equipment Ordinal and path name to the device for each record. This makes it easier to search for and to locate SEF records that pertain to a specific device.

- The `-v` option or the `-t` option.

The `-v` option generates information in verbose mode. It appends information regarding the Equipment Ordinal, page code, and VSN to each line of a record. This makes it possible to select only those lines that pertain to a specific device or a specific volume.

The `-t` option generates log sense output with text descriptions. For each line of log sense data output, the report includes an additional string containing the Equipment Ordinal, page code, VSN, and parameter code description.

Do not specify the `-t` and `-v` options on the same command line. They are mutually exclusive.

For example, the following SEF command reads the SEF log file from the default location, writes the device number and path name for each device, and generates output:

    # sefreport -d /var/opt/SUNWsamfs/sef/sefdata > sef.output

CODE EXAMPLE 9-3 shows the content of `sef.output` file.

CODE EXAMPLE 9-3 `sef.output` Contents
    Record no. 1
    Mon Mar 26 11:17:48 2001  STK      9840             1.25 VSN 002981
       Eq no. 32   Dev name /dev/rmt/1cbn
       PAGE CODE 2
       param code  control   param value
           00h       74h     0x0
           01h       74h     0x0
           02h       74h     0x0
           03h       74h     0x0
           04h       74h     0x0
           05h       74h     0x40050
           06h       74h     0x0
       PAGE CODE 3
       param code  control   param value
           00h       74h     0x0
           01h       74h     0x0
           02h       74h     0x0
           03h       74h     0x0
           04h       74h     0x0
           05h       74h     0x140
           06h       74h     0x0
       PAGE CODE 6
       param code  control   param value
           00h       74h     0x0
    Record no. 2
    Mon Mar 26 11:30:06 2001  STK      9840             1.25 VSN 002999
       Eq no. 31   Dev name /dev/rmt/0cbn
       PAGE CODE 2
       param code  control   param value
           00h       74h     0x0
           01h       74h     0x0
           02h       74h     0x0
           03h       74h     0x0
           04h       74h     0x0
           05h       74h     0x1400a0
           06h       74h     0x0
       PAGE CODE 3
       param code  control   param value
           00h       74h     0x0
           01h       74h     0x0
           02h       74h     0x0
           03h       74h     0x0
           04h       74h     0x0
           05h       74h     0x190
           06h       74h     0x0
       PAGE CODE 6
       param code  control   param value
           00h       74h     0x0
    Record no. 3
    Mon Mar 26 11:30:23 2001  STK      9840             1.25 VSN 002981
       Eq no. 32   Dev name /dev/rmt/1cbn
       PAGE CODE 2
       param code  control   param value
           00h       74h     0x0
           01h       74h     0x0
           02h       74h     0x0
           03h       74h     0x0
           04h       74h     0x0
           05h       74h     0x18400f0
           06h       74h     0x0
       PAGE CODE 3
       param code  control   param value
           00h       74h     0x0
           01h       74h     0x0
           02h       74h     0x0
           03h       74h     0x0
           04h       74h     0x0
           05h       74h     0x1e0
           06h       74h     0x0
       PAGE CODE 6
       param code  control   param value
           00h       74h     0x0
    .
    .
    .

Note - The preceding output has been truncated for inclusion in this manual.

For more information about the SEF log file, including its content and format, see the `sefdata`(4) man page. For more information about optional SEF report formats, see the `sefreport`(1M) man page.

### Managing the SEF Log File

You manage the SEF log file just as you manage any other Sun StorEdge SAM-FS log file. You can run a `cron`(1) job periodically to save the current log file to another location, to delete old SEF files, to create new (empty) SEF files, or to perform other tasks.

You can also use the `log_rotate.sh`(1M) utility to rotate this log file.

For more information about tools for managing the SEF log file, see the `cron`(1) or `log_rotate.sh`(1M) man pages.

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