DIGITAL Optical Storage Desktop Software (OSDS) for DIGITAL UNIX

Installation/User Guide

Part Number: AA-QFALC-TE

February 1997

Revision/Update Information: This is a revised manual.

Operating System and Version: DIGITAL UNIX 3.2c - 3.2g

Software Version: Version 1.5

Digital Equipment Corporation
Maynard, Massachusetts

February 1997

© Perceptics Corporation 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995

Portions © Digital Equipment Corporation, 1997. All rights reserved.

© Digital Equipment Corporation 1997. All rights reserved.

The information in this publication is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital Equipment Corporation, an authorized sublicensor, or the identified licensor.

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the agreement.

The following are trademarks of Digital Equipment Corporation: Alpha, DEC, DECchip, Digital, DIGITAL, DIGITAL UNIX, Storageworks, ThinWire, and the DIGITAL logo.

The following are third-party trademarks: LaserStar and LaserWare and WORMS-11 are registered trademarks of Perceptics Corporation. UNIX is a registered trademark licensed exclusively by X/Open Company Ltd. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.

All other trademarks and registered trademarks are the property of their respective holders.

Table of Contents

Optical Storage Desktop Software

Description of the OSDS Package

Installation and Configuration

Restrictions and Unsupported Utilities

Utility Descriptions

Preface

Purpose of This Guide

This guide describes how to install and operate the Optical Storage Desktop Software (OSDS) package.

Who Should Use This Guide

This guide is for system managers and others who perform operations and system management tasks.

Structure of This Guide

This guide is organized in the following manner:

• Chapter 1, Optical Storage Desktop Software - Introduces the OSDS package, describes related utilities, software package use, and software performance considerations.
• Chapter 2, Description of the OSDS Package - Provides lists of directories created and file descriptions.
• Chapter 3, Installation and Configuration - Provides software installation, configuration, and reconfiguration procedures. Also included are the rebuilding and restarting procedures for the DIGITAL UNIX kernel, and the kit removal procedure.
• Chapter 4, Restrictions and Unsupported Utilities - Describes the restrictions and unsupported utilities of the current software release.
• Chapter 5, Utility Descriptions - Describes each of the OSDS utilities and their related command option switches.

Conventions

The following conventions are used in this guide:

system output

Optical Storage Desktop Software

Introduction

This chapter introduces the Optical Storage Desktop Software (OSDS) package, describes the related utilities, software package use, and software performance considerations.

Optical Storage Desktop Software

The OSDS package is an implementation of the Optical File System (OFS), which is designed to support optical disks in the UNIX operating environment. It is comparable to and compatible with the standard UNIX File System (UFS) within the constraints of a Write-Once Read-Many (WORM) device.

Any program that runs under the standard UNIX File System with a magnetic disk will run with a WORM device using OSDS. This includes all the standard UNIX utilities (such as cd, cp, mv, ln, ls, ex, vi, cc, as, ar, and ld) and system calls (such as creat, link, mkdir, chdir, chmod, chown, chgrp, open, read, write, close, rmdir, and unlink).

Programs and libraries may reside on the optical disk. Optical File Systems may be exported, remotely mounted, and accessed through the Network File System (NFS) in a similar manner to native UNIX File Systems.

Technical Specifications

Function: File system software package supporting the OFS (Optical File System) structure.

Environment: Operates with DIGITAL UNIX systems and servers running the DIGITAL UNIX operating system, releases 3.2c through 3.2g.

Compatibility: Provides transparent access using standard UNIX utilities and file system library calls (open, close, seek, read, and write) from user programs. Exclusions and restrictions are listed in Chapter 4, Restrictions and Unsupported Utilities.

File Structure: OFS, emulating standard UNIX File System (UFS) structure. The structure of OFS is similar to UFS with alterations and extensions to support the write-once nature of optical media. Supports writing and reading of files, directories, hard and soft links, and remote access.

Equipment: OSDS requires an Alpha workstation or server with an external SCSI bus connection and an optical disk drive that supports virgin block detection (on write-once volumes only). Refer to the DIGITAL Optical Storage Desktop Software Product Description (SPD) for details on supported equipment configurations.

Distribution: Distribution media are available on CD-ROM.

Considerations: Files may be rewritten to a WORM optical disk without regard to its write-once nature. However, frequent modifications to these files will cause many blocks to be replaced. On a write-once optical disk, the space occupied by these superseded blocks cannot be reclaimed. Therefore, space utilization on a write-once disk will be improved if it is used primarily as an archival medium.

Operation

OFS Structures

The standard UNIX File System (UFS) maintains several data structures in each partition on block-structured (disk) devices. Some structures, such as the superblock and the bad block list, contain partition-specific information, and others, such as the index node (inode) list, contain file-specific information. The rest of the partition is used to store file data.

Some of the standard UFS structures, such as the superblock and the inode table, can be readily modified as files are added to the partition. Therefore, write-once optical disks may not utilize all the standard UFS structures without alterations.

The OFS structure implemented by OSDS uses the standard UFS structures as much as possible and modifies the others only as necessary. For example, directories use the standard UFS structure, index blocks are exactly like inodes except for the data pointers, and the superblock is not used at all.

An optical volume, like a standard UFS partition, comprises two distinct areas: one area for control structures and one area for data. Unlike the UFS structure, which allocates a fixed amount of space at the beginning of the partition for control structures (superblock and inode list), the OFS structure places the index area at the end of the volume and the data area at the start. This allows both areas to grow toward one another, such that neither area can become completely filled while any space remains unused in the other.

The main difference between the standard UFS structure and the OFS structure employed by OSDS is in the way file index information is handled. Each UFS file has an index node (inode) containing information about the file, such as its owner, its group, its length, and where its data is physically located on the disk.

Any time a file is modified, the file's inode is updated. On an optical disk, this means that the block containing the inode must be completely replaced.

Files may also have indirect pointer blocks associated with them to locate data blocks. For very large files, indirect pointers may be nested as many as three levels deep, so a single change to a file might entail replacing five different blocks ( a data block, three pointer blocks, and the inode). Therefore, the OFS structure replaces the UFS data location mechanism and extends the UFS structure with additional items to keep track of active file index blocks and optimize file lookup and volume mount performance.

Implementation

OSDS is implemented as a background process (daemon) and a pseudodevice driver. Figure 1-1 shows the OSDS interface to the DIGITAL UNIX file system.

OSDS operates transparently to UNIX applications through the DIGITAL UNIX Virtual File System (VFS) interface. No modification to DIGITAL UNIX is required to install OSDS other than normal system configuration. OSDS intercepts VFS requests for the optical disk and routes them to the OFS control process, which performs the appropriate operations on the optical disk.

When a file is created or modified, data and index information destined for the optical disk is stored temporarily in cache buffers in memory. Data is written to the optical disk when the buffer is filled or the file is closed. When data is written to the optical disk, the file index is updated. Whenever the file index changes, a copy is saved in a file on magnetic disk called the index cache file. This buffering permits the file index to be modified during the writing process without using space on the optical disk.

If the system crashes with files open for writing on the optical disk, some or all of the data in those files may be lost, as is often the case for normal UNIX magnetic disk files.

A directory on the optical disk is treated similarly to any other file. However, whenever a file is created, moved, linked, or deleted, the directory in which that file resides is implicitly modified. To ensure that directory entries cannot be lost in the event of a system crash, a special technique is employed to store directory data in the file index so it can be saved in the index cache file. This method is also used for symbolic links and other very short files.

Figure 1-1 OSDS to DIGITAL UNIX Interface

In addition to improved directory security, this scheme reduces the space needed to hold such files and shortens the seek time while traversing the directory tree.

When a WORM optical disk is mounted, the index area is scanned and a list of active files is compiled. Then, the index cache file is consulted to identify any files that may have been modified but whose indices had not been updated on the optical disk. Such files are automatically restored to the state they were in when their indices were saved in the index cache file, including all the data written to them up to that time.

All active file indices are updated on the optical disk before it is demounted. Therefore, as long as the index cache file is intact, the optical disk file structure and all closed files are secure.

Device Drivers

Optical Driver

The optical driver is a UNIX pseudodevice driver designed to operate optical disk drives through the DIGITAL UNIX USCA cam optical driver for DIGITAL UNIX releases 3.2c through 3.2g. The driver performs standard open, close, read, and write operations on optical disk drives, as well as special control functions to sense optical media type and capacity.

OFS Driver

The OFS driver is a hybrid module comprising a special UNIX pseudodevice driver and a set of Virtual File System (VFS) operations. It is compatible with the Virtual File System in DIGITAL UNIX releases 3.2c through 3.2g and supports standard open, close, read, and write operations. The driver functions as a communication path linking UNIX kernel VFS functions with the OFS daemon.

One end of this path comprises the VFS operation set, which is attached to the mount point virtual node (vnode) when an Optical File System is mounted. The other end is represented by the pseudodriver read and write functions used by the OFS daemon to obtain VFS requests and return responses.

Optical Media

Media Types

There are three types of media classified by their capacity as follows:

Note

Installation

OSDS is installed on DIGITAL UNIX systems using the standard installation utility, setld. It is incorporated into the DIGITAL UNIX kernel by a normal system configuration and initiated at system startup time from the system startup command script, rc2. Refer to Chapter 3 for installation instructions.

Description of the OSDS Package

Introduction

This chapter provides the information about the directories created, system file that are saved and modified and the OSDS package.

Directories Created

During the installation the following directories are created:

• /usr/include/ofs
• /usr/sys/ofs
• /usr/sys/cam
• /ofs
• /usr/sys/include/ofs (created as a directory link to /usr/include/ofs

System Files Saved and Modified

The following files are modified. Each file is saved in the directory where it exists by adding a suffix to the filename as shown below before modification. During uninstalling OSDS the saved files are restored as original files; the kernel has to be rebuilt. This can be done on an error condition or abnormal termination during installation of OSDS.

OSDS Package

The OSDS package contains the files specified and described in Table 2-1.

Table 2-1 OSDS files

Installation and Configuration

Introduction

This chapter provides the software installation, configuration, and reconfiguration procedures. Also included are the rebuilding and restarting procedures for the DIGITAL UNIX kernel, and the kit removal procedure.

Installing the OSDS Kit

OSDS is supplied on CD-ROM in kit format suitable for use with setld. Refer to the section in this chapter showing the installation example for installing the software. BE SURE TO REMOVE ANY PREVIOUS OSDS SOFTWARE BEFORE THE OSDS INSTALLATION.

In the course of installing the OSDS kit, setld will execute the configuration script supplied in the kit. The script will ask you questions about the physical configuration of your system, including the connection addresses of SCSI bus controllers, optical disk drives, and jukeboxes. If you do not know the answer to a question, call customer support for help.

You have to perform the following five steps while installing OSDS:

1. You must know your system configuration.
2. Install OSDS files from your CD-ROM.
3. During Step 2, the install procedure asks you to configure the system for the optical hardware setup.
4. After configuration (Step 3), the install procedure prompts you for rebuilding the kernel.
5. After rebuilding the kernel (Step 4), you should verify that all OSDS subsets are installed correctly.

These five steps are explained in detail in the following sections. Read these sections before starting the installation process.

Note

Disk Space and Memory Requirements

Table 3-1 below shows the amount of disk space and RAM memory required for the OSDS product. A block equals 512 bytes.

Table 3-1 Disk Space and Memory Requirements

Know Your System Configuration

Before installing OSDS, it is essential that you know the following information about your optical system configuration.

1. Number of standalone optical drives.
2. SCSI host adapter ID for each standalone drive. The host adapter IDs are numbered as 0, 1, 2, and so on.
3. SCSI target IDs for the standalone drives. Each adapter can have up to six target IDs numbered from 0 to 6 to connect the drives.
4. The unit number (LUN) for each standalone drive. Often this is zero (0). The default value for this is set to zero.

If you are superuser on the system, warn the users currently logged in on the system to log out and be certain that there are not other users logged in except superuser (root). In order to gather this information, you can halt the system by using the following command:

shutdown -h now
When the system halts, it displays the console prompt (>>>).

The following is an illustration of a system configuration:

At this point, use the show device command as follows:

>>>show dev

The "show dev" command displayed the following information.

For your convenience in reading this illustration, the optical drive information is highlighted. The addr field specifies the host adapter ID, target ID, and LUN. The adapter ID is displayed as A, B, C, and so on.

For OSDS configurations, A should be treated as 0, B as 1, C as 2 and so forth. For example, the address A/6/0 means the standalone optical drive is connected to adapter ID 0, target ID 6, and LUN 0.

Note that the optical drive is connected to the adapter AHA1742A and the tape drive is connected to the adapter AHA1740A.

Write down the output of the show dev command. Bring the system up by booting genvmunix as follows:

>>>boot -fi "genvmunix"

Log in as root and start the installation of OSDS. Note that if you have already build a vmunix with all the optical devices connected, then you could boot vmunix and install OSDS.

Configuring the OSDS Kit

When the OSDS configuration script asks various questions, it usually presents a range of valid responses in parentheses. Questions ending in a question mark (?) expect a yes (y) or no (n) response, while those ending in a colon (:) require a numeric response. If a question is confusing, answering it with a question mark (?) will produce a description of the nature of the desired response.

To initiate the configuration procedure, the script first asks:

optical drives [0 - 32]:

The expected response to this question is the total number of drives in the configuration.

The script then asks:

od0 SCSI host adapter id:

Enter the adapter ID that the drives are connected to. For example, the native SCSI is 0 and the other external SCSI controllers can be 1 or 2.

If a wrong number is entered, the script will not take the answer.

The script asks:

od# SCSI target (0 to 6):

The response defines the address of the drive on the SCSI bus. Each device on a SCSI bus must have a distinct device address.

The script asks:

od# unit number (0 to 7):

The response should be zero unless the device controller supports multiple logical units. If so, drives should be assigned successive unit numbers starting with zero.

Rebuilding the DIGITAL UNIX Kernel

After drive configuration data has been entered, the script will ask:

Do you want to edit the configuration file? (y/n) [n]: n

If you answer no (n), the configuration script will execute the doconfig procedure to relink the DIGITAL UNIX kernel. If the procedure completes without error, OSDS has been installed successfully.

Installing OSDS from CD-ROM

The following example is a sample installation procedure, and output, that you will see on the screen of your DIGITAL UNIX system for two RWZ52 drives.

In order for the OSDS optical file system software to work correctly the following subsets must been installed: OSDSMAN150, OSDSOSF150, OSDSVFS150, and OSDSCAM150. If you are using a CD-ROM for your installation, type the following:

======================
# mkdir /mnt
# mount -dr /dev/rz4c /mnt       ! assuming CD-ROM id # is 4
#
# cd /mnt
#
# ls
INSTCTRL  OSDSCAM150  OSDSOSF150  OSDS.image  OSDSMAN150  OSDSVFS150  instctrl
#
# setld -l .

The next example shows the instructions for CD-ROM installations.

*** Enter subset selections ***
The following subsets are mandatory and will be installed
automatically unless you choose to exit without installing
any subsets:
* File System Patches
* Optical File System
* SCSI Device Drivers
The subsets listed below are optional:
There may be more optional subsets than can be presented
on a single screen. If this is the case, you can choose
subsets screen by screen or all at once on the last screen.
All of the choices you make will be collected for your
confirmation before any subsets are installed.
1) Online Manual Pages
Or you may choose one of the following options:
2) ALL mandatory and all optional subsets
3) MANDATORY subsets only
4) CANCEL selections and redisplay menus
5) EXIT without installing any subsets
Enter your choices or press RETURN to redisplay menus.
Choices (for example, 1 2 4-6): 2
You are installing the following mandatory subsets:
File System Patches
Optical File System
SCSI Device Drivers
You are installing the following optional subsets:
Online Manual Pages
Is this correct? (y/n): y
Checking file system space required to install selected subsets:
File system space checked OK.
SCSI Device Drivers
Copying from . (disk)
Verifying
Online Manual Pages
Copying from . (disk)
Verifying
File System Patches
Copying from . (disk)
Verifying
Optical File System
Copying from . (disk)
Verifying
Modifying /sys/include/io/cam/pdrv.h
Modifying /sys/include/io/common/devio.h
Modifying /sys/include/io/cam/cam_debug.h
Modifying /sys/io/cam/cam_config.c
Modifying /sys/data/cam_data.c
SCSI Device Drivers installed
Configuring "SCSI Device Drivers" (OSDSCAM150)
On-Line Manual Pages installed
Configuring "Online Manual Pages" (OSDSMAN150)
File System Patches installed
Configuring "File System Patches" (OSDSOSF150)
Modifying /etc/inittab
Modifying /sys/vfs/vfs_conf.c
Optical File System installed
Configuring "Optical File System" (OSDSVFS150)
*****
***** Optical File System
***** Release: V1.5
***** Subset:  OSDSVFS150
***** Phase:   CONFIGURE
***** Action:  INSTALL
*****
Ready to configure the system to run Optical File System V1.5.
This procedure will modify several system files, compile the
optical disk drive configuration data and rebuild the kernel.
You will be asked questions about the SCSI bus configuration,
such as the SCSI bus, target and unit numbers of disk drives.
If you do not understand a question, enter ? to obtain help.
When the installation procedure is finished, you must reboot
to activate the Optical File System.
Would you like to continue? (y/n):  y
Compiling configuration data
optical drives [0-32]: 1
od0 SCSI host adapter id: 0
od0 SCSI target (0 to 6): 6
od0 unit number (0 to 7): 0
The rest of the procedure may take 10 to 15 minutes to rebuild your kernel.
You will be asked whether or not you want to edit the configuration file.
The default is no; take the default.
Starting kernel rebuild...
*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
Saving /sys/conf/HISSEE as /sys/conf/HISSEE.bck
Do you want to edit the configuration file? (y/n) [n]: n
*** PERFORMING KERNEL BUILD ***
Working....Tue Jan 14 11:50:10 EST 1997
Working....Tue Jan 14 11:52:11 EST 1997
Working....Tue Jan 14 11:54:11 EST 1997
The new kernel is /sys/HISSEE/vmunix
Disk space needed for vmunix is: 7042712 bytes.
Saving /vmunix as /vmunix.preOSDSVFS
Moving /sys/HISSEE/vmunix to /vmunix
*****
***** OSDSVFS150: CONFIGURE phase complete.
*****
#

Verifying OSDS Installed Correctly

Check the installed subsets by using the setld utility with the i option as follows.

# setld -i | grep OSDS
OSDSCAM150 installed SCSI Device Drivers
OSDSMAN150 installed Online Manual Pages
OSDSOSF150 installed File System Patches
OSDSVFS150 installed Optical File System

Registering OSDS Using LMF PAK

After installing the OSDS product, it is essential to register OSDS product using LMF (License Management Facility) in order to use it. An OSDS Product Authorization Key (PAK) is needed in order to register. You must have received it when the product has been purchased. Get the document that contains the PAK information.

The manual pages for registering any UNIX product using LMF can be found in the UNIX man pages for lmf and lmfsetup. To see the man pages, login to the system and type the following:

man  lmf
man lmfsetup

The rest of this section describes how to register OSDS using lmfsetup utility and the information in the OSDS PAK.

First install OSDS product. Login as root. Then type

lmfsetup

The system will display the following message:

Register PAK (type q or quit to exit)  [template] 

Press Enter key. Then, it will ask you to type the following information:

Issuer: 
Authorization Number: 
Product Name: 
Producer: 
Number of Units: 
Version: 
Product Release Date: 
Key Termination Date: 
Availability Table Code: 
Activity Table Code: 
Key Options: 
Product Token: 
Hardware-Id: 
Checksum: 

If an information not supplied in the OSDS PAK is asked, simply press the Enter key. Once you have entered all the information, the lmfsetup utility will display whether OSDS has been registered successfully or not. If it not successful, try to register again because often times typing error occurs resulting in the failure of registration. If you cannot register after several tries, contact field service.

LMF automatically enables a license when you register it. After successful installation, the status of the OSDS PAK must be in the active status. To list the status of all register products in the system, type the following command

lmf  list

For more information on lmf refer to man pages and/or documentation for lmf and lmfsetup.

Shutting the System Down

In order to shutdown the system, type the following:

# shutdown -h now

Shut down messages display.

Restarting the DIGITAL UNIX Kernel

Reboot the system by typing the following at the console prompt (>>>):

>>> boot

Verifying Optical Hardware Configuration

Use the following command to verify that the optical devices are registered in the system's error log file.

The following example refers to RWZ52 installation only.

#
# uerf -R 300 | more
********************************* ENTRY    1. **********************



----- EVENT INFORMATION -----

EVENT CLASS                  OPERATIONAL EVENT 
OS EVENT TYPE       300.     SYSTEM STARTUP 
SEQUENCE NUMBER       0.
OPERATING SYSTEM             DEC OSF/1 
OCCURRED/LOGGED ON           Tue Jan 14 11:56:55 1997
OCCURRED ON SYSTEM           ntbk11 
SYSTEM ID   x00020006        CPU TYPE:  DEC 2000 
SYSTYPE     x00000000
MESSAGE                              PCXAL keyboard, language English 
_(American) 

Alpha boot: available memory from 
_0x70a000 to 0x5000000 
Digital UNIX V3.2C  (Rev. 148); Tue 
_Jan 14 11:54:17 EST 1997  
physical memory = 80.00 megabytes. 
available memory = 72.96 megabytes. 
using 299 buffers containing 2.33 
_megabytes of memory 
DEC2000 model 300 system 
Firmware revision: 1.2 
PALcode: OSF version 1.32 
ibus0 at nexus 
ace0 at ibus0 
gpc0 at ibus0 
eisa0 at ibus0 
vga0 at eisa0 
1024x768 (QVision ) 
ln0 at eisa0 
ln0: DEC LANCE Ethernet Interface, 
_hardware address: 08-00-2B-BD-2A-22  
aha0 at eisa0 slot 5 
scsi0 at aha0 
rz0 at scsi0 bus 0 target 0 lun 0 (DEC 
_    RZ26L    (C) DEC 440C) 
rz1 at scsi0 bus 0 target 1 lun 0 (DEC 
_    RZ26L    (C) DEC 440C) 
rz4 at scsi0 bus 0 target 4 lun 0 (DEC 
_    RRD44   (C) DEC  3593) 
op48 at scsi0 unit 48 (DEC     RWZ52   
_  (C)DEC 3404) 
aha1 at eisa0 slot 6 
scsi1 at aha1 
tz13 at scsi1 bus 1 target 5 lun 0 
_(DEC     TLZ06     (C)DEC 0374) 
fdi0 at eisa0 
fd0 at fdi0 unit 0 
lp0 at ibus0 
lvm0: configured. 
lvm1: configured. 
dli: configured 
SuperLAT. Copyright 1993 Meridian 
_Technology Corp. All rights 
_reserved. 
--more-- q
#

If the optical device is not listed (opxxx) then the OSDS software will not operate properly. Therefore, you will need to do the following:

1. Check for loose cables.
2. Check for SCSI ID address conflicts.
3. Run the configuration (setld -c OSDSVFS150 CONFIG) to reconfigure the SCSI address for the optical device. Refer to Reconfiguring the OSDS Kit, found in this chapter.
4. Reboot the system.

In order to use OSDS, insert an optical platter into the optical drive, mount it and perform read/write operations using UNIX utilities.

At this point, you have verified that the OSDS software is configured correctly.

Verifying the OFS Daemon is Running

To verify that the optical file system (ofs) daemon named, ofsd, is running, type the ps -e command as shown below.

#
# ps -e | grep ofs
1485 ttyp3    I 0:00.01 /usr/sbin/ofsd of0 /dev/nod0
1499 ttyp3    S  + 0:00.01 grep ofs
#

There should be one ofsd daemon for each drive.

Reconfiguring the OSDS Kit

If you must reconfigure your kernel to recognize a different optical device configuration, invoke the configuration procedure manually by typing:

# setld -c OSDSVFS150 CONFIG

You will be executing the configuration procedure shown in the section Installing OSDS from CD-ROM found in this chapter.

Removing the OSDS Kit

This section shows how to remove the OSDS kit from the system.

#
# setld -i | grep OSDS
OSDSCAM150 installed SCSI Device Drivers
OSDSMAN150 installed Online Manual Pages
OSDSOSF150 installed File System Patches
OSDSVFS150 installed Optical File System
#
#
# setld -d OSDSCAM150 OSDSMAN150 OSDSOSF150 OSDSVFS150
Unmounting OFS file systems
Stopping OFS daemons

Deleting "Optical File System" (OSDSVFS150).
Restoring /sys/vfs/vfs_conf.c
Restoring /etc/inittab
Do you want to purge control files? (y/n):  y
Restoring /vmunix.preOSDSVFS as /vmunix
The Optical File System is no longer installed
Remember to rebuild the kernel with doconfig
to remove the Optical File System functionality


Deleting "File System Patches" (OSDSOSF150).
File System Patches no longer installed
Remember to rebuild the kernel with doconfig
to remove the File System Patches functionality


Deleting "Online Manual Pages" (OSDSMAN150).
On-Line Manual Pages no longer installed


Deleting "SCSI Device Drivers" (OSDSCAM150).
Restoring /sys/data/cam_data.c
Restoring /sys/io/cam/cam_config.c
Restoring /sys/include/io/cam/cam_debug.h
Restoring /sys/include/io/common/devio.h
Restoring /sys/include/io/cam/pdrv.h
SCSI Device Drivers no longer installed
Remember to rebuild the kernel with doconfig
to remove the SCSI Device Drivers functionality
#
# setld -i | grep OSDS
#

If there are no OSDS subsets left, then the OSDS kit has been removed.

Starting and Stopping Optical File System

OSDS has one optical file system daemon called, ofsd running for each drive in the jukeboxes as well as standalone drives. These daemons are automatically started when the system boots. Sometimes, an administrator may want to stop the optical file system daemons and start them later. A script file named, ofs has been provided to stop and start ofs daemons. It is installed in the directory /sbin/init.d.

In order to stop the daemons, invoke the script as follows:

/sbin/init.d/ofs  stop

Before stopping the daemons, all the ofs file systems will be unmounted.

To start the ofs daemons, invoke the script as follows:

/sbin/init.d/ofs  start

This will start the daemons first and then it will mount all the ofs volumes.

Initializing Optical Disks

Unlike standard UNIX File Systems, which must be initialized by mkfs before they can be used to store files, OFS file systems require no initialization.

Whenever a virgin volume is mounted, an empty root directory is inferred, and all its attributes (owner, group, and access modes) are copied from the mount point. These default attributes may be altered after the volume is mounted, or selected in advance by changing the mount point attributes before mounting. Erasable volumes should be cleared before mounting to identify available space.

True WORM platters should not be cleared. Rewritable volumes can be initialized to either WORM (OFS_WORM) mode or Rewritable (OFS_POOL) mode.

In order to clear rewritable (erasable) volumes, use the over utility as described below.

Note

The following options of over utility are used in the example:

The following examples assumes that the volume is in drive 1 (device /dev/od0).

over  -v  /dev/od0

over  -fv  /dev/od0

over  -zv  /dev/od0

over  -zfv  /dev/od0

over  -av  /dev/od0

Using OSDS

Accessing Optical Disks

Once OSDS is installed, optical disk drives may be accessed using device nodes of the form:

/dev/od# (where # is the unit number).

For example:

/dev/od0 is for drive 1

/dev/od1 is for drive 2

OSDS can handle up to 16 units (optical disk drives) in the current implementation.

Once the OFS daemon is active, optical disk file systems may be activated by the omount utility using driver nodes of the form:

/dev/of#, where # is the unit number

For example

/dev/of0 is for drive 1

/dev/of1 is for drive 2

There is no limit to the number of file systems that OSDS can handle.

Mounting Optical Disks

Optical volumes must be mounted using the omount utility the same way UNIX File Systems are mounted with the standard mount utility. Most of the option switches recognized by mount are available in omount as well. Example:

#
# omount /dev/of0 /mnt
#
# omount /dev/of1 /mnt1
#

Once a volume has been mounted, you may access the optical disk by using any of the standard UNIX utilities or system calls from your own programs to read from and write to the optical volume. Volumes can be automatically mounted at system boot time by specifying the volumes to be mounted in the /etc/ofstab file. See ofstab in the Utilities Section of this manual.

Unmounting Optical Disks

It is important that the optical disk be properly unmounted if any write operations have been performed. This is because directory and file index information is held in a temporary buffer to optimize performance. This information is written to the optical disk when the disk is unmounted. Unmount an optical disk with the standard umount utility just as you would with any other UNIX File System. Example:

#
# umount /mnt
#
# umount /mnt1
#

Checking Mounted Volumes

To check the mounted volumes in the jukebox, type the mount command as follows. Note the ofs is displayed as pc file system (pcfs) since ofs replaces the slot allocated for the pcfs file system. Example:

# mount
/dev/rz12a on / type ufs (rw)
/proc on /proc type procfs (rw)
/dev/rz12g on /usr type ufs (rw)
/dev/rz12h on /usr/users type ufs (rw)
/dev/of0 on /mnt type pcfs (rw)
/dev/of1 on /mnt1 type pcfs (rw)
#
#

Looking at Volume Capacity

To look at the volume capacity use the df command as follows.

# df

Filesystem

512-blocks

Used

Avail

Capacity

Mounted on

/dev/rz12a

126462

105372

8442

93%

/

/proc

0

0

0

100%

/proc

/dev/rz12g

792124

639342

73568

90%

/usr

/dev/rz12h

810952

151660

578196

21%

/usr/users

/dev/of0

576999

576999

0

0%

/mnt

/dev/of1

576999

162541

413882

28%

/mnt1

#
#

Note

At this point, you have verified that the OSDS software is configured correctly.

If you are able to write and read from the /jb0/0a mount point or any other OSDS mount points, then the OSDS installation was successful.

Recovering from a System Crash

In the development of OSDS, recovery from a system crash was an important consideration. OSDS has been designed to minimize the impact of a system crash and the effort required to recover. The result is that the state of your optical disk is never worse (and is usually better) than that of the magnetic disks on your system.

If an optical disk is not properly unmounted (as might happen during a system crash), then any files that were being created or modified when the system crashed are indeterminate (that is, they may or may not be complete). All other files on the volume should be intact.

Files that were created or modified and successfully closed before the system crash are intact on the disk. However, their directory entries or file indices may not be up-to-date. Such files will be automatically restored when the file system is remounted after the crash.

Files that were created or modified but not successfully closed before a system crash or hardware failure have most likely lost data; that is, some data successfully written to the file has not been recorded on the optical disk. Such lost data is not recoverable by any method.

Performance Considerations

The performance of your optical disk subsystem under OSDS is primarily dictated by your optical disk equipment. The overhead imposed by OSDS is minimal. However, there are some things you can do to enhance performance.

Subdirectories

One of the most time-consuming operations on the optical disk is file lookup. This requires reading directories and locating the requested files within those directories. This process can be enhanced considerably by the judicious use of subdirectories.

With 10,000 files in a directory, it could take a long time to locate a particular file because of the number of files. Performance would be substantially enhanced if you create 100 subdirectories with 100 files in each subdirectory because only 100 files must be searched to locate the requested file.

File Buffer Size

All writes to files on the optical disk are buffered in memory. Data in the buffer is written to the optical disk when:

• The buffer is filled
• The file is closed
• The optical disk is unmounted

A separate buffer is maintained for every open file, and the size of each buffer is controlled by a parameter that may be set when the volume is mounted. The size of these buffers can have a strong effect on the performance of OSDS in many cases. This is highly dependent on your application.

If only a few files are open at once, a large buffer size will reduce latency considerably. However when many files are open, the memory space occupied by these buffers may dramatically increase swapping overhead.

File Fragmentation

File fragmentation occurs when file data are not located in contiguous blocks on the optical disk. This will require the optical disk to seek across discontinuities while reading the file. Since the optical disk cannot transfer data and seek at the same time, file fragmentation will have a negative impact on read performance.

The following are the most frequent reasons for file fragmentation on the optical disk:

• Writing two or more files at the same time with a file buffer size that is smaller than the size of any of the files being written
• Writing a file on a WORM disk in a nonsequential manner, such as writing a file in reverse order or rewriting parts of a file in random order

Restrictions and Unsupported Utilities

Introduction

This chapter describes the restrictions and unsupported utilities that apply to the current release of OSDS under the DIGITAL UNIX operating system.

Restrictions

Access Times

OSDS does not maintain file access times on read access to WORM volumes. This is done to avoid having to update the file index whenever a file is accessed, which would be prohibitively wasteful of optical disk space. Access time is only updated in conjunction with other modifications.

Link Counts

The current release of OSDS maintains accurate link counts only for directories on rewritable volumes. This is done primarily as an optimization to avoid having to update the file index whenever a link is made to a file. File link counts on WORM volumes may be updated as an option in a future release.

Disk Quotas

The current release of OSDS does not support the use of disk quotas on an Optical File System. Disk quota support may be added in a future release.

Labels

The current release of OSDS does not furnish a method to attach any sort of label to an Optical File System. Some form of labeling may be provided in a future release.

Unsupported Utilities

The following subsections describe the DIGITAL UNIX utilities that cannot be used with OSDS.

format Utility

The format utility operates directly on the raw disk device, performing various functions such as integrity checks. This function is inappropriate on optical volumes because they normally are preformatted at the factory, so no formatting is unnecessary.

mkfs Utility

The mkfs utility creates a UNIX File System directly on the raw disk device and is not applicable to optical volumes. Erasable optical volumes should be cleared with the over utility before mounting. WORM optical volumes do not require any advance preparation to be used for file storage. Insert a virgin WORM volume in the drive and mount it with the omount utility.

tunefs Utility

The tunefs utility modifies various parameters of a UNIX File System, which are maintained in a special structure called the superblock for which there is no analog on OSDS optical volumes. OSDS operating parameters are specified as command line switches.

fsck Utility

The fsck utility verifies a UNIX File System directly on the raw disk device, bypassing the file system completely. If you suspect there is a problem with the structure of OSDS optical volumes, the ofsck utility should be used to diagnose and correct the problem.

quota Utility

DIGITAL UNIX disk quotas are not supported under OSDS. Therefore, the following disk quota commands are not supported by the OSDS software: edquota(8), quotacheck(8), quotaon(8)/quotaoff(8), and repquota(8). Functions: quotactl(2), and setquota(2).

disklabel Utility

This utility is used to create, modify, and read a disk label on a disk pack. The disklabel utility contains partition information. At this time, each side of an optical platter cannot be divided into multiple disk partitions. The disklabel utility is associated with the UNIX File System; the Optical File System in OSDS does not support the disklabel on optical platters.

vet Utility

The optical devices supported by OSDS do not recognize the DIGITAL UNIX vet utility.

diskx Utility

The diskx utility is associated with the UNIX File System; the Optical File System in OSDS does not support diskx on optical platters.

OFS Restrictions

This section identifies the known restrictions of OSDS V1.5 software on DIGITAL UNIX 3.2c through 3.2g.

dump/restore

The current version of the Optical File System does NOT support the dump/restore command. The tar command can be used to back up files instead.

pcfs

The current version of the Optical File System borrows file system index 4, and therefore, appears to users as pcfs. This problem will prevent you from mounting a pcfs on the same system on which OSDS is running.

executable file

It is not possible to run an executable file from an optical disk.

power off during copy command

The optical device must be powered on before the system boots. It will not be accessible if it is powered off at boot time.

executing omount

Executing omount of an empty slot results in an I/O error.

multiple attach

If the same device is configured and attached by several drivers, the system will crash.

Utility Descriptions

Introduction

This chapter describes each of the OSDS utilities and their related command option switches.

Table 5-1 lists and describes the OSDS utilities. Table 5-1 Utility DescriptionsUtilitiestable of

OFS Check Utility (ofsck)

Synopsis

ofsck [-is] [-b size] [-f size] [-l length] [-q quota] [-r [date]] [-volume] od [... od]

Description

ofsck verifies the consistency of an optical file system. od is a character-special device node referencing the od device driver or an ordinary file containing an optical file system. Multiple file systems may be specified, and file systems may be interleaved with option switches. Options are effective for all following file systems.

ofsck reads the private cache file /ofs/$<volume> used by the ofs daemon to buffer index records for active files on an optical volume (see ofsd(8)). Each record in this file is the length of a logical block on the file system, and one record is needed for each file that has been altered but not yet flushed; that is, files currently open for writing and directories that have recently been modified. This file serves to guard the integrity of the optical file system in the event of a catastrophic system failure, and is used to restore index records when checking a volume after a crash.

When a volume is mounted, an index map is constructed for the volume showing the location of the latest index record for each active file. The index map is preserved in the volume map file /ofs/#<volume>. If this file is present when the volume is checked, the index map is obtained from the map file to expedite the process. The file also contains the time of the last update, which is verified to ensure the map file matches the volume. The volume reference number may be specified as a command-line option.

Options

The ofsck utility accepts the following control option switches:

-b <size> (block size):

-c (confirm):

-f <size> (fake):

-i (invert):

-l <length> (buffer length):

-n (no):

-q <quota> (fault quota):

-r (read only):

-s (slow-check):

-y (yes):

-# (volume number):

Examples

To verify an optical volume: ofsck /dev/od0

To verify a fake file system: ofsck -f20 file

Files

/ofs/#<volume> optical disk volume index map.

/ofs/$<volume> optical disk volume index cache.

See Also

ofs(4), ofsd(8), omount(8)

OFS Daemon (ofsd)

Synopsis

ofsd [-cirsz] [-b size] [-f size] [-l length] [-p pad] [-q quota] [-t time] ofs od

Description

ofsd accepts file system operations via ofs to be performed on od. The file system ofs is a character-special device node referencing the OFS pseudo-device driver (see ofs(4)). The storage medium od is a character-special device node referencing the od device driver or an ordinary file containing an optical file system. ofsd is normally initiated from the /etc/rc.local script at system startup time. ofsd establishes a logical relation between the real device od and the pseudo-device ofs, which may then be mounted as a standard UNIX file system (see omount(8)).

ofsd uses a private cache file /ofs/@<volume> to buffer index records for active files on an optical volume. Each record in this file is the length of a logical block on the file system, and one record is needed for each file that has been altered but not yet flushed; that is, files currently open for writing and directories that have recently been modified. This file serves to guard the integrity of the optical file system in the event of a catastrophic system failure, and is only used to restore index records when re-mounting a volume after a crash.

When a volume is mounted, the file index records are scanned and an index map is constructed showing the location of the index record for each active file. The index map is updated as new file index records are generated. When the volume is demounted, the index map is preserved in the volume map file /ofs/#<volume>. If this file is present when the volume is remounted, the index map is obtained from the map file to expedite the mount process. The file also contains a copy of the root directory attributes, the file system statistics, and the time of the last update, which is verified to ensure the map file matches the volume.

Options

The ofsd accepts the following control option switches:

-b <size> (block size):

-c (consistency):

-f <size> (fake):

-i (invert):

-l <length> (buffer length):

-p <pad> (padding):

-q <quota> (fault quota):

-r (read-only):

-s (slow-mount):

-t <time> (flush time):

-z (zero):

Note

Examples

To attach an optical drive: ofsd /dev/of0 /dev/od0 &

To access a fake file system: ofsd /dev/of0 -f20 odfs &

Files

/ofs/@<volume> optical disk volume index cache.

/ofs/#<volume> optical disk volume index map.

See Also

ofs(4), omount(8), umount(8)

OFS File Access (ofile)

Synopsis

ofile [-is] [-b size] [-f size] [-l length] [-q quota] [-r [date]] [-volume] od [filename ...]

Description

ofile extracts the content of files in an optical file system. The file system od is a character-special device node referencing the od device driver or an ordinary file containing an optical file system. If any filenames are specified, the content of the selected files is sent to the standard output. If no filenames are specified, only the volume usage statistics are presented.

Options

The ofile accepts the following control option switches:

-b (block size):

-f (file size)

-i (invert)

-l (buffer length)

-q (fault quota)

-r (regress)

-s (slow check)

-# (volume number)

Example

To extract a file from an optical volume: ofile /dev/od0 file

Files

/ofs/#<volume> optical disk volume index map.

/ofs/$<volume> optical disk volume index cache.

See Also

ofs(4), ofsd(8), ofsck(8), ofind(8), omap(8), omount(8)

OFS Find Utility (ofind)

Synopsis

ofind [-rs] [-b size] [-f size] [-l length] [-q quota] od [filename ...]

Description

ofind examines an optical file system to locate missing files and inspect earlier generations of files. The file system od is a character-special device node referencing the od device driver or an ordinary file containing an optical file system.

If any filenames are specified, ofind traverses the entire optical file system tree, inspecting previous generations of any directories encountered, and presents on its standard output all the file index numbers found associated with each filename. If no filename is specified, ofind interactively accepts a file index number (and optional generation level and depth) from its standard input and presents information about the corresponding file on its standard output. If file index number zero is entered, the generation level and depth are assumed to represent an absolute block number and block count, and the corresponding blocks are presented in both hexadecimal and text format.

Options

The ofind utility accepts the following control option switches:

-b <size> (block size):

-f <size> (fake):

-l <length> (buffer length):

-q <quota> (fault quota):

-r (raw):

-s (slow-scan):

Examples

To inspect an optical file system: ofind /dev/od0

To locate a missing optical file: ofind /dev/od0 file

Files

/ofs/#<volume> optical disk volume index map.

/ofs/$<volume> optical disk volume index cache.

See Also

ofs(4), ofsd(8)

OFS Index Map Utility (omap)

Synopsis

omap [-is] [-b size] [-f size] [-l length] [-q quota] [-r [date]] [-volume] od [filename ...]

Description

Optical File System index map (omap) extracts or constructs index records in an optical file system. The file system od is a character-special device node referencing the od device driver or an ordinary file containing an optical file system. If any filenames are specified, an index map of the selected files is generated on the standard output. If no filenames are specified, and od is not writable, an index map of all files is generated. Otherwise, index map text is accepted on the standard input.

The map text comprises one line for each file mapped. The initial portion of an index map line (up to the first space) represents the path name of the file relative to the root of the file system. Special characters in the remainder of the line identify specific fields in the file index record:

If no address is specified for a range of logical blocks in a file, that range of logical blocks remains unmapped. Unmapped blocks within a file appear as all-zero blocks.

Options

The omap utility accepts the following control option switches:

-b (block size)

-f (file size)

-i (invert)

-l (buffer length)

-q (fault quota)

-r (read)

-s (slow)

-# (volume number)

Examples

To produce a map of an optical file system: omap -r /dev/od0 > map

To obtain a map of a specific optical file: omap /dev/od0 file > map

To incorporate a fresh or revised file map: omap /dev/od0 < map

Files

/ofs/#<volume> optical disk volume index map.

/ofs/$<volume> optical disk volume index cache.

See Also

ofs(4), ofsd(8), ofsck(8), ofind(8), ofile(8), omount(8)

OFS Link Utility (olink)

Synopsis

olink ofs [filename ...]

Description

olink is a command script used to restore missing or deleted files on an optical file system. ofs is the mount point of an optical file system.

For each filename specified, olink invokes ofind to discover all of the file index numbers ever associated with filename. If filename names an existing file, no action is taken. If more than one file index number is found associated with any filename, ls is invoked to display the attributes of each, and the user is requested to select one. filename is then linked to the associated file index using ln (or mv in the case of a directory).

The operation of this script depends upon a special feature of the optical file system daemon permitting files to be specified by index number. If the first character of an optical file name is a delete character (preceded by \ if entered from the keyboard), the remainder of the file name string is interpreted as a decimal number specifying the file index. Thus, .../ofs/^?2 is a valid alternate name for the root directory of the optical file system containing the directory ofs. Since optical disk file space cannot be recovered and file index numbers are never reused, this form of reference remains valid even when all references to a file have been deleted from every directory in an optical file system. In particular, a name of this form can be passed as a parameter to a standard utility such as ln or mv to create a directory entry.

Examples

To restore a missing optical file: olink /ofs file

See Also

ofind(1), ofs(4), ofsd(8)

OFS Mounting Table (ofstab)

The administrator can make OSDS mount selected optical volumes automatically at system boot time by creating the file /etc/ofstab. The information about the volumes to be mounted are to be specified in this file. When the ofstab file exist, the startup script /sbin/init.d/ofs will only mount the volumes specified in the ofstab file.

Synopsis

/etc/ofstab

Description

The file /etc/ofstab contains entries for optical file systems to mount using the omount(8) command, which is normally invoked by the /etc/rc.local script at system startup time.

Each entry consists of a line of the form: device, directory, label, options

device

Options

-a (automatic)

-g (group)

-l (buffer length)

-m (no mount)

-p (padding)

-q (error quota)

-r (read only)

-s (slow mount)

-t (flush time)

-x (execution)

A pound-sign (#) as the first character of a word identifies the rest of that line as a comment to be ignored by omount.

/etc/ofstab is only read by omount, and not written; it is the duty of the system administrator to properly create and maintain this file.

The order of records in /etc/ofstab is important because omount processes the file sequentially; the entry for a file system must appear before the entries for any file systems to be mounted within it.

Files

/etc/ofstab

See Also

ofs(4), omount(8)

OFS Mount Utility (omount)

Synopsis

omount -a[cfvz] [-l length] [-p pad] [-q quota] [-r [date]] [-t time]

omount [-cfisz] [-l length] [-p pad] [-q quota] [-r [date]] [-t time] ofs dir [tag]

omount [-cfisz] [-l length] [-p pad] [-q quota] [-r [date]] [-t time] ofs | dir | tag

Description

omount attaches the file system ofs to the file system hierarchy at the directory dir, which must already exist. If dir has any contents prior to the omount operation, these remain hidden until the file system is unmounted. The file system ofs is a character-special device node referencing the ofs pseudo-device driver (see ofs(4)). tag is an optional label for the volume. It should be a single word (or a string enclosed in quotes) not over 15 characters in length. If present, tag is used to verify the identity of the volume.

If invoked with only one of ofs, dir, or tag, omount searches the file /etc/ofstab (see ofstab (5)) for a matching entry and extracts additional parameters from that entry.

Options

The omount utility accepts the following control option switches:

-a (mount all):

-c (consistency):

-f (file):

-i (invert):

-l <length> (buffer length):

-o (options):

-p <pad> (padding):

-q <quota> (fault quota):

-r <date> (regress):

-s (slow-mount):

-t <time> (flush time):

-v (verbose):

-z (zero):

Examples

To mount a volume read-write: omount /dev/of0 /od

To mount a volume read-only: omount -r /dev/of0 /od

To specify the flush time: omount -t60 /dev/of0 /od

To select buffer size: omount -l40 /dev/of0 /od

To set regression date: omount -r930 /dev/of0 /od

To select dir from ofstab: omount /dev/of0

To select ofs from ofstab: omount /od

To mount all ofs volumes: omount -a

Files

/etc/ofstab table of optical file systems

See Also

ofs(4), ofstab(5), ofsd(8), mount(8), umount(8)

OFS Over Utility (over)

Synopsis

over [-abfnvz] [-l length] [-p pattern] [-q quota] [-s source] od [... od]

Description

over destroys the contents of an erasable optical volume by initializing the POOL and ROOT index blocks. over should be run on erasable optical volumes before they are mounted. Otherwise, these volumes may appear to have no available space. od is a character-special device node referencing the od device driver. Multiple device names may be specified, and device names may be interleaved with option switches. Options are effective for all following device names.

Options

The over utility accepts the following control option switches:

-a (clear):

-b (Block):

-f (force):

-l (buffer length):

-n (blocks to clear):

-p (pattern to record):

-q (value contiguous errors):

-s (source):

-v (verbose):

-z (zero):

Examples

To clear an empty volume: over /dev/od0

To clear an active volume: over -f /dev/od0

To clear a volume to zero: over -z /dev/od0

See Also

ofs(4), ofsd(8), ofsck(8), omount(8)

OFS Update Daemon (update)

Synopsis

update [interval]

Description

update is a program that executes the sync(2) system call primitive periodically at a specified interval in seconds. If the interval is not specified, the default interval is 30 seconds. This ensures that the file system is fairly up to date in case of a system crash. This command should not be executed directly, but should be initiated from /etc/inittab.

See Also

sync(1), sync(2), init(8)