C H A P T E R 8

Advanced Topics

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

This chapter contains the following sections.

- Using Device Logging

- Using Removable Media Files

- Using Segmented Files

- Using System Error Facility Reporting

##

Using 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. 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, for each tape and optical drive device, and one the historian. The log files are located in `/var/opt/SUNWsamfs/devlog`. The name of each log file corresponds to the name of the equipment ordinal.

For example, assume that you have a Sun StorEdge SAM-FS file system and a single Hewlett Packard optical library with two optical drives.

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

CODE EXAMPLE 8-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 8-2 shows the `/var/opt/SUNWsamfs/devlog` file.

CODE EXAMPLE 8-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

You can enable the device log in one of two ways, as described in the following subsections:

- 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 eq, specify the equipment ordinal of the device for which you want to log messages.

For event, specify one or more of the events listed in the `samset`(1M) man page. If you specify more than one event, separate them with space characters.

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.

    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 listed in the `samset`(1M) man page. 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

##

Using 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.

Note - The `request`(1) command bypasses the typical functions of the archiver.

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, their data does not reside in the disk cache. Thus, you can create removable media 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 Sun StorEdge SAM-FS file systems read that information from the inode entry. Multiple removable media files can reside on the same volume.

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

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, removable media files are never archived. Removable media files are not supported over NFS.

### 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, respectively.

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 8-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 (VSN) 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.
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 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.

The following command creates a removable media file:

    # request -m lt -v aaa rem1

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

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

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

##

Using Segmented Files

The Sun StorEdge SAM-FS environment supports 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. It is possible for only part of a segmented file to reside on the disk cache at any one time.

The `segment`(1) command enables 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 during 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.

Note - The `mmap` function cannot take place on a segmented file. Because of this, a segmented file cannot be an executable binary.

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.

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 that 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. Up to four archive copies can be made for each segment. Sun StorEdge SAM-FS also supports volume overflow for segments.

Note - The index of a segmented file contains no user data. It is considered metadata and 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 StorEdge SAM-FS Troubleshooting Guide.

##

Using 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 and 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 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 create the log file.

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

The following command shows the SEF log file being created in the default location.

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

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

    # samd stop
    # samd start

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

Note - SEF reporting is enabled as long as the `sefdata` log file exists. To disable SEF reporting, you must rename or remove this file.

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.

### To Generate 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.

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

The following are the most commonly used options with 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 8-3 shows the content of `sef.output` file.

CODE EXAMPLE 8-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
    .
    .
    .

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.

### SEF `sysevent` Functionality

In addition to using the SEF log file, you can use the Solaris `sysevent` feature to obtain tape drive SCSI log sense error counter pages 2 and 3 for media analysis. By default, the SEF `sysevent` feature is enabled and set to poll once before unload. The SEF `sysevent` behavior is controlled by `defaults.conf` and `samset`.

In the `defaults.conf` file, the `sef` parameter can be used to enable SEF `sysevent` feature by equipment ordinal, or to specify the log sense polling frequency. For more information, see the `defaults.conf`(4) manu page.

To Create a SEF `sysevent` Handler

1. Create the `/var/tmp/xx` file similar to the following:

`#!/bin/ksh
`echo "$@" >> /var/tmp/xx.dat
exit 0

2. Make the `/var/tmp/xx` file executable:

# chmod a+rwx /var/tmp/xx

3. Add the SEF `sysevent` handler to the `syseventd`(1M) file by typing the following:

`#` syseventadm add -vSUNW -pSUNWsamfs -cDevice -sSEF /var/tmp/xx \"\$VENDOR\" \"\$PRODUCT\" \"\$USN\" \"\$REV\" \$TOD \$EQ_ORD \"\$NAME\" \$INQ_TYPE \"\$MEDIA_TYPE\" \"\$VSN\" \$LABEL_TIME \$LP2_PC0 \$LP2_PC1 \$LP2_PC2 \$LP2_PC3 \$LP2_PC4 \$LP2_PC5 \$LP2_PC6 \$LP3_PC0 \$LP3_PC1 \$LP3_PC2 \$LP3_PC3 \$LP3_PC4 \$LP3_PC5 \$LP3_PC6 \$WHERE \$sequence

`#` syseventadm restart

This command creates the `/etc/sysevent/config/SUNW,SUNWsamfs,Device,sysevent.conf` file containing the SEF `sysevent` handler `/var/tmp/xx` and loads the event handler into the `syseventd` daemon.

Note - The `syseventadm`(1M) command is not supported by the Solaris 8 Operating System. You must manually create the `/etc/sysevent/config/SUNW,SUNWsamfs,Device,sysevent.conf` file and contents, then type `pkill -HUP syseventd` to restart the `syseventd` daemon.

4. To load the SEF sysevent handler, use the command `pkill -HUP syseventd` to activate the `/var/tmp/xx` SEF `sysevent` handler.

For more information about SEF `sysevent` usage, see the `sefsysevent`(4) man page.

Copyright © 2006, Sun Microsystems, Inc. All Rights Reserved.