Part VIII Managing File Systems

This part provides instructions for managing file systems in the Solaris operating environment. This part contains these chapters.

Chapter 26 File Systems (Overview)

This is a list of the overview information in this chapter.

• "What's New in File Systems?"

• "Types of File Systems"

• "File System Administration Commands"

• "The Default Solaris File Systems"

• "Swap Space"

• "The UFS File System"

• "Mounting and Unmounting File Systems"

• "Determining a File System's Type"

What's New in File Systems?

The Solaris 7 release provides two new file system features: UFS logging and a new mount option to ignore access time updates on files.

UFS logging is the process of storing transactions (changes that make up a complete UFS operation) into a log before the transactions are applied to the UFS file system. Once a transaction is stored, the transaction can be applied to the file system later.

UFS logging provides two advantages. It prevents file systems from becoming inconsistent, therefore eliminating the need to run the fsck command. And, because fsck can be bypassed, UFS logging reduces the time required to reboot a system if it crashes, or after an unclean halt.

UFS logging is not enabled by default. To enable UFS logging, you must specify the -o logging option with the mount command when mounting the file system. Also, the fsdb command has been updated with new debugging commands to support UFS logging.

To ignore access time updates on files, you can specify the -o noatime option when mounting a UFS file system. This option reduces disk activity on file systems where access times are unimportant (for example, a Usenet news spool). See the mount_ufs(1M) man page for more details.

Introduction

A file system is a structure of directories used to organize and store files. The term "file system" is used to describe:

• A particular type of file system: disk-based, network-based, or virtual

• The entire file tree from the root directory downward

• The data structure of a disk slice or other media storage device

• A portion of a file tree structure that is attached to a mount point on the main file tree so that it is accessible

Usually, you can tell from context which meaning is intended.

The Solaris operating environment uses the virtual file system (VFS) architecture, which provides a standard interface for different file system types. The VFS architecture enables the kernel to handle basic operations, such as reading, writing, and listing files, without requiring the user or program to know about the underlying file system type.

Administering file systems is one of your most important system administration tasks. Read this chapter for file system background and planning information. Refer to other chapters in the System Administration Guide for instructions about the following tasks:

• Creating new file systems - See Chapter 27, Creating File Systems (Tasks) and Chapter 29, The Cache File System (Tasks) for detailed information.

• Making local and remote files available to users - See Chapter 28, Mounting and Unmounting File Systems (Tasks) for detailed information.

• Connecting and configuring new disk devices - See Chapter 21, Disk Management (Overview) for detailed information.

• Designing and implementing a backup schedule and restoring files and file systems as needed - See Chapter 33, Backing Up and Restoring File Systems (Overview) for information about backing up and restoring files and file systems.

• Checking for and correcting file system damage - See Chapter 31, Checking File System Integrity for detailed information on how to proceed if the automatic (boot time) checking fails.

Types of File Systems

The Solaris operating environment supports three types of file systems:

• Disk-based

• Network-based

• Virtual

To identify the type for a particular file system, see "Determining a File System's Type".

Disk-based File Systems

Disk-based file systems are stored on physical media such as hard disks, CD-ROMs, and diskettes. Disk-based file systems can be written in different formats. The available formats are:

• UFS - UNIX file system (based on the BSD Fast File system that was provided in the 4.3 Tahoe release). UFS is the default disk-based file system for the Solaris operating environment.

  Before you can create a UFS file system on a disk, the disk must be formatted and divided into slices. A disk slice is a physical subset of a disk that is composed of a single range of contiguous blocks. A slice can be used either as a raw device that provides, for example, swap space, or to hold a disk-based file system. See Chapter 21, Disk Management (Overview) for complete information on formatting disks and dividing disks into slices.

• HSFS - High Sierra and ISO 9660 file system. High Sierra is the first CD-ROM file system; ISO 9660 is the official standard version of the High Sierra File System. The HSFS file system is used on CD-ROMs, and is a read-only file system. Solaris HSFS supports Rock Ridge extensions to ISO 9660, which, when present on a CD-ROM, provide all UFS file system semantics and file types except for writability and hard links.

• PCFS - PC file system, which allows read/write access to data and programs on DOS-formatted disks written for DOS-based personal computers.

Each type of disk-based file system is customarily associated with a particular media device:

• UFS with hard disk

• HSFS with CD-ROM

• PCFS with diskette

These associations are not, however, restrictive. For example, CD-ROMs and diskettes can have UFS file systems created on them.

Network-based File Systems

Network-based file systems can be accessed over the network. Typically, network-based file systems reside on one system, typically a server, and are accessed by other systems across the network. The Network File System (NFS) is the only available network-based file system.

NFS is the distributed file system service for Solaris. With NFS, you can administer distributed resources (files or directories) by exporting them from a server and mounting them on individual clients. See "The Network File System (NFS)" for more information.

Virtual File Systems

Virtual file systems are memory-based file systems that provide access to special kernel information and facilities. Most virtual file systems do not use file system disk space. However, the Cache File System (CacheFS) uses a file system on the disk to contain the cache, and some virtual file systems, such as the Temporary File System (TMPFS), use the swap space on a disk.

The Cache File System

The Cache File System (CacheFS^TM) can be used to improve performance of remote file systems or slow devices such as CD-ROM drives. When a file system is cached, the data read from the remote file system or CD-ROM is stored in a cache on the local system. See Chapter 29, The Cache File System (Tasks) for detailed information on setting up and administering CacheFS File Systems.

The Temporary File System

The Temporary File System (TMPFS) uses local memory for file system reads and writes, which is typically much faster than a UFS file system. Using TMPFS file systems can improve system performance by saving the cost of reading and writing temporary files to a local disk or across the network. For example, temporary files are created when you compile a program, and the operating system generates a lot of disk or network activity while manipulating these files. Using TMPFS to hold these temporary files may significantly speed up their creation, manipulation, and deletion.

Files in TMPFS file systems are not permanent. They are deleted when the file system is unmounted and when the system is shut down or rebooted.

TMPFS is the default file system type for the /tmp directory in the Solaris operating environment. You can copy or move files into or out of the /tmp directory, just as you would in a UFS file system.

The TMPFS file system uses swap space as a temporary backing store. If a system with a TMPFS file system does not have adequate swap space, two problems can occur:

• The TMPFS file system can run out of space, just as a regular file system can fill up.

• Because TMPFS allocates swap space to save file data (if necessary), some programs may not execute because there is not enough swap space.

See Chapter 27, Creating File Systems (Tasks) for information about creating TMPFS file systems. See Chapter 30, Configuring Additional Swap Space (Tasks) for information about increasing swap space.

The Loopback File System

The Loopback File System (LOFS) lets you create a new virtual file system, so you can access files by using an alternative path name. For example, you can create a loopback mount of root / on /tmp/newroot, which will make the entire file system hierarchy look like it is duplicated under /tmp/newroot, including any file systems mounted from NFS servers. All files will be accessible either with a path name starting from (/), or with a path name starting from /tmp/newroot.

See Chapter 27, Creating File Systems (Tasks) for information on how to create LOFS file systems.

The Process File System

The Process File System (PROCFS) resides in memory. It contains a list of active processes, by process number, in the /proc directory. Information in the /proc directory is used by commands like ps. Debuggers and other development tools can also access the address space of the processes by using file system calls.

Do not delete the files in the /proc directory. Deleting processes from the /proc directory is not the best way to kill them. Remember, /proc files do not use disk space, so there is little reason to delete files from this directory.

The /proc directory does not require system administration.

Additional Virtual File Systems

These additional types of virtual file systems are listed for your information. They do not require administration.

• FIFOFS (first-in first-out) - Named pipe files that give processes common access to data

• FDFS (file descriptors) - Provides explicit names for opening files using file descriptors

• NAMEFS - Used mostly by STREAMS for dynamic mounts of file descriptors on top of files

• SPECFS (special) - Provides access to character special and block devices

• SWAPFS - File system used by the kernel for swapping

File System Administration Commands

Most file system administration commands have both a generic and a file system-specific component. You should use the generic commands whenever possible, which call the file system-specific component. Table 26-1 lists the generic file system administrative commands, which are located in the /usr/sbin directory.

How the File System Commands Determine the File System Type

The generic file system commands determine the file system type by following this sequence:

1. From the -F option, if supplied.

2. By matching a special device with an entry in /etc/vfstab file (if special is supplied). For example, fsck first looks for a match against the fsck device field; if no match is found, it then checks the special device field.

3. By using the default specified in /etc/default/fs for local file systems and in /etc/dfs/fstypes for remote file systems.

Manual Pages for Generic and Specific Commands

Both the generic and specific commands have manual pages in the man Pages(1M): System Administration Commands. The specific manual page is a continuation of the generic manual page. To look at a specific manual page, append an underscore and the file system type abbreviation to the generic command name. For example, to see the specific manual page for mounting a UFS file system, type man mount_ufs(1M).

The Default Solaris File Systems

The Solaris file system is hierarchical, starting with the root directory (/) and continuing downwards through a number of directories. The Solaris installation process enables you to install a default set of directories and uses a set of conventions to group similar types of files together. Table 26-2 provides a summary of the default Solaris file systems, and shows the type of each file system.

The root (/) and /usr file systems are both needed to run a system. Some of the most basic commands from the /usr file system (like mount) are included in the root (/) file system so that they are available when the system boots or is in single-user mode and /usr is not mounted. See Chapter 32, File System Reference for more detailed information on the default directories for the root (/) and /usr file systems.

Swap Space

The Solaris operating environment uses some disk slices for temporary storage rather than for file systems. These slices are called swap slices, or swap space. Swap space is used as virtual memory storage areas when the system does not have enough physical memory to handle current processes.

Since many applications rely on swap space, it is important to know how to plan for, monitor, and add more swap space when needed. For an overview about swap space and instructions for adding swap space, see Chapter 30, Configuring Additional Swap Space (Tasks).

The UFS File System

UFS is the default disk-based file system in Solaris operating environment. Most of the time, when you administer a disk-based file system, you will be administering UFS file systems. UFS provides the following features:

• State flags - Show the state of the file system: clean, stable, active, logging, or unknown. These flags eliminate unnecessary file system checks. If the file system is "clean," "stable," or "logging," file system checks are not run.

• Extended fundamental types (EFT) - 32-bit user ID (UID), group ID (GID), and device numbers.

• Large file systems - A UFS file system can be as large as 1 Tbyte (terabyte). The Solaris operating environment does not provide striping, which is required to make a logical slice large enough for a 1-Tbyte file system. However, the Solstice^TM DiskSuite^TM software, available from Sun, provides this capability.

• Large files - By default, a UFS file system can have regular files larger than 2 Gbytes (gigabytes). You must explicitly use the nolargefiles mount option to enforce a 2 Gbyte maximum file size limit.

See Chapter 32, File System Reference for detailed information about the UFS file system.

Parts of a UFS File System

When you create a UFS file system, the disk slice is divided into cylinder groups, which are made up of one or more consecutive disk cylinders. The cylinder groups are then further divided into addressable blocks to control and organize the structure of the files within the cylinder group. Each type of block has a specific function in the file system.

A UFS file system has these four types of blocks:

• Boot block - Stores information used when booting the system

• Superblock - Stores much of the information about the file system

• Inode - Stores all information about a file except its name

• Storage or data block - Stores data for each file

See "The Structure of UFS File System Cylinder Groups" for more detailed information about each type of block.

If you want to customize a file system using arguments with the newfs command or the mkfs command, see Chapter 32, File System Reference for information about altering these parameters.

UFS Logging

UFS logging is the process of storing transactions (changes that make up a complete UFS operation) in a log before the transactions are applied to the UFS file system. Once a transaction is stored, the transaction can be applied to the file system later.

At reboot, the system discards incomplete transactions, but applies the transactions for completed operations. The file system remains consistent because only completed transactions are ever applied. This is true even when a system crashes, which normally interrupts system calls and introduces inconsistencies into a UFS file system.

UFS logging provides two advantages. It prevents file systems from becoming inconsistent, therefore eliminating the need to run fsck. And, because fsck can be bypassed, UFS logging reduces the time required to reboot a system if it crashes, or after an unclean halt (see "What fsck Checks and Tries to Repair" for details on unclean halts). UFS logging can especially reduce the boot time on systems that have large file systems, which usually take a long time to read and verify with fsck.

The log created by UFS logging is continually flushed as it fills up. The log is totally flushed when the file system is unmounted or as a result of the lockfs -f command.

UFS logging is not enabled by default. To enable UFS logging, you must specify the -o logging option with the mount command when mounting the file system. The log is allocated from free blocks on the file system, and it is sized approximately 1 Mbyte per 1 Gbyte of file system, up to a maximum of 64 Mbytes. Logging can be enabled on any UFS, including the root (/) file system. Also, the fsdb command has been updated with new debugging commands to support UFS logging.

Planning UFS File Systems

When laying out file systems, you need to consider possible conflicting demands. Here are some suggestions:

• Distribute the work load as evenly as possible among different I/O systems and disk drives. Distribute /export/home and swap space evenly across disks.

• Keep pieces of projects or members of groups within the same file system.

• Use as few file systems per disk as possible. On the system (or boot) disk, you should have three file systems: /, /usr, and swap space. On other disks, create one or, at most, two file systems. Fewer, roomier file systems cause less file fragmentation than many small, over-crowded file systems. Higher-capacity tape drives and the ability of ufsdump to handle multiple volumes make it easier to back up larger file systems.

• If you have some users who consistently create very small files, consider creating a separate file system with more inodes. However, most sites do not need to be concerned about keeping similar types of user files in the same file system.

See Chapter 27, Creating File Systems (Tasks) for information on default file system parameters as well as procedures for creating new UFS file systems.

Mounting and Unmounting File Systems

Before you can access the files on a file system, you need to mount the file system. Mounting a file system attaches that file system to a directory (mount point) and makes it available to the system. The root (/) file system is always mounted. Any other file system can be connected or disconnected from the root (/) file system.

When you mount a file system, any files or directories in the mount point directory are unavailable as long as the file system is mounted. These files are not permanently affected by the mounting process, and they become available again when the file system is unmounted. However, mount directories are typically empty, because you usually do not want to obscure existing files.

For example, Figure 26-1 shows a local file system, starting with a root (/) file system and subdirectories sbin, etc, and opt.

Figure 26-1 Sample root (/) File System

Now, say you wanted to access a local file system from the /opt file system that contains a set of unbundled products.

First, you must create a directory to use as a mount point for the file system you want to mount, for example, /opt/unbundled. Once the mount point is created, you can mount the file system (by using the mount command), which makes all of the files and directories in /opt/unbundled available, as shown in Figure 26-2. See Chapter 28, Mounting and Unmounting File Systems (Tasks) for detailed instructions on how to perform these tasks.

Figure 26-2 Mounting a File System

Unmounting a file system removes it from the file system mount point. Some file system administration tasks cannot be performed on mounted file systems. You should unmount a file system when:

• It is no longer needed or has been replaced by a file system that contains more current software.

• You check and repair it using the fsck command. See Chapter 31, Checking File System Integrity for more information about the fsck command.

It is a good idea to unmount a file system before doing a complete backup of it. See Chapter 33, Backing Up and Restoring File Systems (Overview) for more information about doing backups.

File systems are automatically unmounted as part of the system shutdown process.

The Mounted File System Table

Whenever you mount or unmount a file system, the /etc/mnttab (mount table) file is modified with the list of currently mounted file systems. You can display the contents of the mount table using the cat or more commands, but you cannot edit it. Here is an example of a /etc/mnttab file:

$ more /etc/mnttab
/dev/dsk/c0t3d0s0    /       ufs     rw,suid,dev=800018,largefiles 863804345
/dev/dsk/c0t3d0s6    /usr    ufs     rw,suid,dev=80001e,largefiles 863804345
/proc   /proc   proc    rw,suid,dev=2900000     863804345
fd      /dev/fd fd      rw,suid,dev=29c0000     863804345
/dev/dsk/c0t3d0s3   /export ufs     suid,rw,largefiles,dev=80001b  863804347
/dev/dsk/c0t3d0s7   /export/home ufs suid,rw,largefiles,dev=80001f 863804348
/dev/dsk/c0t3d0s4   /export/swap ufs suid,rw,largefiles,dev=80001c 863804348
/dev/dsk/c0t3d0s5   /opt  ufs   suid,rw,largefiles,dev=80001d  863804347
swap    /tmp    tmpfs   dev=2a80000     863804347
$

The Virtual File System Table

It would be a very time-consuming task to manually mount file systems every time you wanted to access them. To fix this, the virtual file system table (the /etc/vstab file) was created to maintain a list of file systems and how to mount them. The /etc/vfstab file provides two important features: you can specify file systems to automatically mount when the system boots, and you can mount file systems by using only the mount point name, because the /etc/vfstab file contains the mapping between the mount point and the actual device slice name.

A default /etc/vfstab file is created when you install a system depending on the selections you make when installing system software; however, you can edit the /etc/vfstab file on a system whenever you want. To add an entry, the main information you need to specify is the device where the file system resides, the name of the mount point, the type of the file system, whether you want it to boot automatically when the system boots (by using the mountall command), and any mount options.

The following is an example of an /etc/vfstab file. Comment lines begin with #. This example shows an /etc/vfstab file for a system with two disks (c0t0d0 and c0t3d0).

Example 26-1 Sample /etc/vfstab File

$ more /etc/vfstab
#device         device          mount           FS      fsck   mount  mount
#to mount       to fsck         point           type    pass   at boot options
/dev/dsk/c0t0d0s0 /dev/rdsk/c0t0d0s0 /          ufs     1       no      -
/proc           -               /proc           proc    -       no      -
/dev/dsk/c0t0d0s1 -                -            swap    -       no      -
swap            -               /tmp            tmpfs   -       yes     -
/dev/dsk/c0t0d0s6 /dev/rdsk/c0t0d0s6 /usr       ufs     2       no      -
/dev/dsk/c0t3d0s7 /dev/rdsk/c0t3d0s7 /test      ufs     2       yes     -
$

In Example 26-1, the last entry specifies that a UFS file system on the /dev/dsk/c0t2d0s7 slice will be automatically mounted on the /test mount point when the system boots. Note that, for root (/) and /usr, the mount at boot field value is specified as no, because these file systems are mounted by the kernel as part of the boot sequence before the mountall command is run.

See Chapter 28, Mounting and Unmounting File Systems (Tasks) for descriptions of each of the /etc/vfstab fields and information on how to edit and use the file.

The Network File System (NFS)

NFS is a distributed file system service that can be used to share resources (files or directories) from one system, typically a server, with other systems across the network. For example, you might want to share third-party applications or source files with users on other systems.

NFS makes the actual physical location of the resource irrelevant to the user. Instead of placing copies of commonly used files on every system, NFS allows you to place one copy on one system's disk and let all other systems access it across the network. Under NFS, remote files are virtually indistinguishable from local ones.

A system becomes an NFS server if it has resources to share or export over the network. A server keeps a list of currently exported resources and their access restrictions (such as read/write or read-only).

When you share a resource, you make it available for mounting by remote systems.

You can share a resource in these ways:

• By using the share or shareall command

• By adding an entry to the /etc/dfs/dfstab (distributed file system table) file

See Chapter 28, Mounting and Unmounting File Systems (Tasks) for information on how to share resources. See the NFS Administration Guide for a complete description of NFS.

AutoFS

You can mount NFS file systems by using a client-side service called automounting, or AutoFS, which enables a system to automatically mount and unmount NFS file systems whenever you access them. The file system remains mounted as long as you remain in the file system and are using a file. If the file system is not accessed for a certain period of time, it is automatically unmounted.

AutoFS provides the following features:

• NFS file systems don't need to be mounted when the system boots, which saves booting time.

• Users don't need to know the root password to mount and unmount NFS file systems.

• Network traffic may be reduced, since NFS file systems are only mounted when they are in use.

The AutoFS service is initialized by automount, which is run automatically when a system is booted. The automount daemon, automountd, runs continuously and is responsible for the mounting and unmounting of the NFS file systems on an as-needed basis. By default, the Solaris operating environment automounts /home.

AutoFS works with file systems specified in the name service. This information can be maintained in NIS, NIS+, or local /etc files. With AutoFS, you can specify several multiple servers to provide the same file system. This way, if one of the servers is down, AutoFS can try to mount from another machine. You can specify which servers are preferred for each resource in the maps by assigning each server a weighting factor.

See the NFS Administration Guide for complete information on how to set up and administer AutoFS.

The Cache File System (CacheFS)

If you want to improve the performance and scalability of your NFS-mounted file system, you should use the Cache File System (CacheFS). CacheFS is a general purpose file system caching mechanism that improves NFS server performance and scalability by reducing server and network load.

Designed as a layered file system, CacheFS provides the ability to cache one file system on another. In an NFS environment, CacheFS increases the client per server ratio, reduces server and network loads, and improves performance for clients on slow links, such as Point-to-Point Protocol (PPP). You can also combine CacheFS with the AutoFS service to help boost performance and scaliability.

See Chapter 29, The Cache File System (Tasks) for detailed information about CacheFS.

Deciding How to Mount File Systems

Table 26-3 provides guidelines on mounting file systems based on how you use them.

You can mount a CD-ROM containing a file system by simply inserting it into the drive (Volume Management will automatically mount it). You can mount a diskette containing a file system by inserting it into the drive and running the volcheck command. See Part IV for more information.

Determining a File System's Type

You can determine a file system's type by using the following:

• The FS type field in the virtual file system table (/etc/vfstab file)

• The /etc/default/fs file for local file systems

• The /etc/dfs/fstypes file for NFS file systems

How to Determine a File System's Type

This procedure works whether the file system is mounted or not.

Determine a file system's type by using the grep command.

$ grep mount-point fs-table

Information for the mount point is displayed.

If you have the raw device name of a disk slice, you can use the fstyp(1M) command to determine a file system's type (if the disk slice contains a file system).

Example--Determining a File System's Type

The following example uses the /etc/vfstab to determine the type of the /export file system.

$ grep /export /etc/vfstab
/dev/dsk/c0t3d0s6   /dev/rdsk/c0t3d0s6  /export ufs   2       yes    -
$ 

The following example uses the /etc/mnttab file to determine the file system type of the currently mounted diskette (mounted by volume management).

$ grep /floppy /etc/mnttab
/vol/dev/diskette0/unnamed_floppy   /floppy/unnamed_floppy  pcfs    rw,nohidden,
nofoldcase,dev=16c0009      89103376
$

Chapter 27 Creating File Systems (Tasks)

This chapter describes how to create UFS, TMPFS, and LOFS file systems. For UFS file systems, this chapter shows you how to create a file system on a hard disk using the newfs command. Because TMPFS and LOFS are virtual file systems, you actually "create" them by mounting them.

This is a list of the step-by-step instructions in this chapter.

• "How to Create a UFS File System"

• "How to Create a TMPFS File System"

• "How to Create a LOFS File System"

For instructions on how to create UFS and DOS file systems on removable media, see Chapter 11, Guidelines for Using CDs and Diskettes (Overview).

Creating a UFS File System

Before you can create a UFS file system on a disk, the disk must be formatted and divided into slices. A disk slice is a physical subset of a disk that is composed of a single range of contiguous blocks. A slice can be used either as a raw device that provides, for example, swap space, or to hold a disk-based file system. See Chapter 21, Disk Management (Overview) for complete information on formatting disks and dividing disks into slices.

Solaris device names use the term slice (and the letter s in the device name) to refer to the slice number. Slices used to be called "partitions" in the SunOS 4.0 or compatible releases.

You need to create UFS file systems only occasionally, because the Solaris operating environment automatically creates them as part of the installation process. You need to create (or re-create) a UFS file system when you:

• Add or replace disks

• Change the existing partitioning structure

• Do a full restoration on a file system

The newfs command is the standard way to create UFS file systems. The newfs(1M) command is a convenient front-end to the mkfs(1M) command, which actually creates the new file system. On Solaris systems, newfs parameter defaults, such as tracks per cylinder and sectors per track, are read from the disk label that will contain the new file system, and the options you choose are passed to the mkfs command to build the file system.

File System Parameters

To make a new file system on a disk slice, you almost always use the newfs command. Table 27-1 shows the default parameters used by the newfs command.

How to Create a UFS File System

1. Make sure you have met the following prerequisites:

   • The disk must be formatted and divided into slices before you can create UFS file systems on it. See Chapter 21, Disk Management (Overview) for complete information on formatting disks and dividing disks into slices.

   • You need to know the device name of the slice that will contain the file system. See Chapter 22, Administering Disks (Tasks) for information on finding disks and disk slice numbers.

   • If you are re-creating an existing UFS file system, unmount it.

   • You must be superuser.

2. Create the UFS file system.

   # newfs [-N] [-b size] [-i bytes] /dev/rdsk/device-name

   -N	Displays what parameters newfs would pass to mkfs without actually creating the file system. This is a good way to test the newfs command.
   -b size	Specifies the file system block size. Default is 8192 blocks.
   -i bytes	Specifies the number of bytes per inode. Default is 2048 bytes.
   device-name	Specifies the disk device name on which to create the new file system.

   ---

   Caution -

   Be sure you have specified the correct device name for the slice before performing the next step. If you specify the wrong slice, you will erase its contents when the new file system is created.

   ---

   The system asks for confirmation.

3. To verify the creation of the UFS file system, check the new file system with the fsck(1M) command.

   # fsck /dev/rdsk/device-name

   device-name

   Specifies the name of the disk device containing the new file system.

   The fsck command checks the consistency of the new file system, reports problems it finds, and prompts you before repairing the problems. See Chapter 31, Checking File System Integrity for more information on fsck.

Example--Creating a UFS File System

The following example creates a UFS file system on /dev/rdsk/c0t3d0s7.

# newfs /dev/rdsk/c0t3d0s7
newfs: construct a new file system /dev/rdsk/c0t3d0s7 (y/n)? y
/dev/rdsk/c0t3d0s7:     163944 sectors in 506 cylinders of 9 tracks, 
   36 sectors 83.9MB in 32 cyl groups (16 c/g, 2.65MB/g, 1216 i/g)
super-block backups (for fsck -b #) at:
 32, 5264, 10496, 15728, 20960, 26192, 31424, 36656, 41888,
 47120, 52352, 57584, 62816, 68048, 73280, 78512, 82976, 88208,
 93440, 98672, 103904, 109136, 114368, 119600, 124832, 130064, 
 135296, 140528, 145760, 150992, 156224, 161456,

Where to Go From Here

To mount the file system and make it available, go to Chapter 28, Mounting and Unmounting File Systems (Tasks).

Creating a Temporary File System (TMPFS)

The Temporary File System (TMPFS) uses local memory for file system reads and writes, which is typically much faster than a UFS file system. Using TMPFS file systems can improve system performance by saving the cost of reading and writing temporary files to a local disk or across the network. Files in TMPFS file systems do not survive across reboots or unmounts.

If you create multiple TMPFS file systems, be aware that they all use the same system resources. Files created under one TMPFS file system use up the space available for any other TMPFS, unless you limit TMPFS sizes using the -o size option of the mount command.

See the tmpfs(7FS) man page for more information.

How to Create a TMPFS File System

1. Become superuser.

2. If necessary, create the directory where you want to mount the TMPFS file system and set permissions and ownership as necessary.

3. Create a TMPFS file system.

   To set up the system to automatically create a TMPFS file system when it boots, see "Example--Creating a TMPFS File System at Boot Time".

   # mount -F tmpfs -o size=number swap mount-point

   size=number	Specifies the size of the TMPFS file system in Mbytes.
   mount-point	The directory on which the TMPFS file system is mounted.

4. Look at the output from the mount command to verify that the TMPFS file system has been created.

   # mount -v

Example--Creating a TMPFS File System

The following example creates a new directory, /export/reports, and mounts a TMPFS file system at that point, limiting it to 50 Mbytes.

# mkdir /export/reports
# chmod 777 /export/reports
# mount -F tmpfs -o size=50 swap /export/reports

Example--Creating a TMPFS File System at Boot Time

You can set up the system to automatically create a TMPFS file system when it boots by adding an entry to the /etc/vfstab file. The following example shows an entry in the /etc/vfstab file that will create a TMPFS file system on /export/test when the system boots. Since the size=number option is not specified, the size of the TMPFS file system on /export/test is limited only by the available system resources.

swap - /export/test  tmpfs   -  yes  -

For more information the /etc/vfstab file, see "/etc/vfstab Field Descriptions".

Creating a Loopback File System (LOFS)

A LOFS file system is a virtual file system that provides an alternate path to an existing file system. When other file systems are mounted onto a LOFS file system, the original file system does not change.

See the lofs(7FS) man page for more information.

Be careful when creating LOFS file systems. Because these are virtual file systems, the potential for confusing both users and applications is enormous.

How to Create a LOFS File System

1. Become superuser.

2. Create the directory where you want to mount the LOFS file system and give it the appropriate permissions and ownership.

3. Create a LOFS file system.

   To set up the system to automatically create a TMPFS file system when it boots, see "Example--Creating a LOFS File System at Boot Time".

   # mount -F lofs loopback-directory mount-point

   loopback-directory	Specifies the file system to be mounted on the loopback mount point.
   mount-point	Specifies the directory on which to mount the LOFS file system.

4. Look at the output from the mount command to verify that the LOFS file system has been created.

   # mount -v

Example--Creating a LOFS File System

The following example shows how to use a new LOFS file system with the chroot(1M) command to provide a complete virtual file system view of a process or family of processes.

# mkdir /tmp/newroot
# mount -F lofs / /tmp/newroot
# chroot /tmp/newroot command

Example--Creating a LOFS File System at Boot Time

You can set up the system to automatically create a LOFS file system when it boots by adding an entry to the end of the /etc/vfstab file. The following example shows an entry in the /etc/vfstab file that will create a LOFS file system for the root (/) file system on /tmp/newroot.

/ - /tmp/newroot  lofs   -  yes  -

Make sure the loopback entry is the last entry in the /etc/vfstab file. Otherwise, if the /etc/vfstab entry for the loopback file system precedes the file systems to be included in it, the loopback file system cannot be created.

For more information the /etc/vfstab file, see "/etc/vfstab Field Descriptions".

Chapter 28 Mounting and Unmounting File Systems (Tasks)

This chapter describes how to mount and unmount file systems. This is a list of the step-by-step instructions in this chapter.

• "How to Determine Which File Systems Are Mounted"

• "How to Add an Entry to the /etc/vfstab File"

• "How to Mount Multiple File Systems Listed in the /etc/vfstab File"

• "How to Mount a File System Listed in the /etc/vfstab File"

• "How to Mount a UFS File System"

• "How to Mount an NFS File System"

• "x86: How to Mount a System V (S5FS) File System"

• "x86: How to Mount a PCFS (DOS) File System From a Hard Disk"

• "How to Stop All Processes for a File System"

• "How to Unmount a File System"

• "How to Unmount File Systems Listed in the /etc/vfstab File"

Mounting File Systems

After you create a file system, you need to make it available to the system so you can use it. You make a file system available by mounting it, which attaches the file system to the system directory tree at the specified mount point. The root (/) file system is always mounted. Any other file system can be connected or disconnected from the root (/) file system.

Table 28-1 provides guidelines on mounting file systems based on how you use them.

You can mount a CD-ROM containing a file system by simply inserting it into the drive (Volume Management will automatically mount it). You can mount a diskette containing a file system by inserting it into the drive and running the volcheck(1) command. See Chapter 11, Guidelines for Using CDs and Diskettes (Overview) for more information.

Commands Used to Mount and Unmount File Systems

Table 28-2 lists the commands in the /usr/sbin directory that you use to mount and unmount file systems.

The mount commands will not mount a read/write file system that has inconsistencies. If you receive an error message from the mount or mountall command, you may need to check the file system. See Chapter 31, Checking File System Integrity for information on how to check the file system.

The umount commands will not unmount a file system that is busy. A file system is considered busy if a user is in a directory in the file system, or if a program has a file open in that file system.

Commonly Used Mount Options

Table 28-3 describes the commonly used mount options that you can specify with the -o option of the mount command. If you specify multiple options, separate them with commas (no spaces). For example, -o ro,nosuid.

For a complete list of mount options for each file system type, refer to the specific mount command man pages (for example, mount_ufs(1M)).

How to Determine Which File Systems Are Mounted

You can determine which file systems are mounted by using the mount command.

$ mount -v

Example--Determining Which File Systems Are Mounted

$ mount
/ on /dev/dsk/c0t3d0s0 read/write/setuid/largefiles on ...
/usr on /dev/dsk/c0t3d0s6 read/write/setuid/largefiles on ...
/proc on /proc read/write/setuid on Mon Jun 8 10:28:31 1998
/dev/fd on fd read/write/setuid on Mon Jun 8 10:28:31 1998
/export on /dev/dsk/c0t3d0s3 setuid/read/write/largefiles on ...
/export/home on /dev/dsk/c0t3d0s7 setuid/read/write/largefiles on ...
/export/swap on /dev/dsk/c0t3d0s4 setuid/read/write/largefiles on ...
/opt on /dev/dsk/c0t3d0s5 setuid/read/write/largefiles on ...
/tmp on swap read/write on Mon Jun 8 10:28:31 1998
$

Mounting File Systems Using the /etc/vfstab File

/etc/vfstab Field Descriptions

An entry in the /etc/vfstab file has seven fields, which are described in Table 28-4.

You must have an entry in each field in the /etc/vfstab file. If there is no value for the field, be sure to enter a dash (-).

How to Add an Entry to the /etc/vfstab File

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Edit the /etc/vfstab file and add an entry.

   ---

   Note -

   Since the root (/) file system is mounted read-only by the kernel during the boot process, only the remount option (and options that can be used in conjunction with remount) affect the root (/) entry in the /etc/vfstab file.

   ---

   See Table 28-4 for detailed information about the /etc/vfstab field entries. Make sure that you:

   • Separate each field with white space (a space or a tab).

   • Enter a dash (-) if a field has no contents.

3. Save the changes.

Examples--Adding an Entry to the /etc/vfstab File

The following example mounts the disk slice /dev/dsk/c0t3d0s7 as a UFS file system attached to the mount point directory /files1 with the default mount options (read/write). It specifies the raw character device /dev/rdsk/c0t3d0s7 as the device to fsck. The fsck pass value of 2 means that the file system will be checked, but not sequentially.

#device           device             mount    FS       fsck   mount    mount
#to mount         to fsck            point    type     pass   at boot  options
#
/dev/dsk/c0t3d0s7 /dev/rdsk/c0t3d0s7 /files1  ufs      2      yes       -
/                   -                /tmp/newroot lofs -      yes       -                   

The following example mounts the directory /export/man from the system pluto as an NFS file system on mount point /usr/man. It does not specify a device to fsck or a fsck pass because it's an NFS file system. In this example, mount options are ro (read-only) and soft. For greater reliability, specify the hard mount option for read/write NFS file systems.

#device           device             mount    FS       fsck   mount    mount
#to mount         to fsck            point    type     pass   at boot  options
pluto:/export/man   -                /usr/man nfs      -      yes       ro,soft

The following example mounts the root (/) file system on a loopback mount point named /tmp/newroot. It specifies yes for mount at boot, no device to fsck, and no fsck pass number. LOFS file systems must always be mounted after the file systems used to make up the LOFS file system.

#device           device             mount    FS       fsck   mount    mount
#to mount         to fsck            point    type     pass   at boot  options
#
/                   -                /tmp/newroot lofs -      yes       -                   

How to Mount Multiple File Systems Listed in the /etc/vfstab File

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Mount the file systems listed in the /etc/vfstab file.

   # mountall [-l | -r] [-F fstype]

   If no options are specified, all file systems listed in the /etc/vfstab file with yes in the mount at boot field are mounted.

   -l	Mounts all the local file systems listed in the /etc/vfstab file with yes in the mount at boot field.
   -r	Mounts all the remote file systems listed in the /etc/vfstab file with yes in the mount at boot field.
   -F fstype	Mounts all file systems of the specified type listed in the /etc/vfstab file with yes in the mount at boot field.

   All the file systems with a device to fsck entry are checked and fixed, if necessary, before mounting.

Examples--Mounting Multiple File Systems Listed in the /etc/vfstab File

The following example shows the messages displayed if file systems are already mounted when you use the mountall command.

# mountall
mount: /tmp already mounted
nfs mount: mount: /usr/openwin: Device busy
nfs mount: mount: /usr/man: Device busy

The following example mounts all the local systems listed in the /etc/vfstab file.

# mountall -l
# mount
/ on /dev/dsk/c0t3d0s0 read/write/setuid/largefiles on ...
/usr on /dev/dsk/c0t3d0s6 read/write/setuid/largefiles on ...
/proc on /proc read/write/setuid on Wed May 27 09:11:50 1998
/dev/fd on fd read/write/setuid on Wed May 27 09:11:50 1998
/tmp on swap read/write on Wed May 27 09:11:50 1998

The following example mounts all the remote file systems listed in the /etc/vfstab file.

# mountall -r
# mount
/ on /dev/dsk/c0t3d0s0 read/write/setuid/largefiles on ...
/usr on /dev/dsk/c0t3d0s6 read/write/setuid/largefiles on ...
/proc on /proc read/write/setuid on Mon Jun  8 10:28:31 1998
/dev/fd on fd read/write/setuid on Mon Jun  8 10:28:31 1998
/tmp on swap read/write on Mon Jun  8 10:28:31 1998
/nfs/mars.dist on mars:/usr/dist intr/remote on ...
/nfs/mars.mail on mars:/var/mail intr/noac/remote on ...

How to Mount a File System Listed in the /etc/vfstab File

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Mount a file system listed in the /etc/vfstab file.

   # mount mount-point

   mount-point

   Specifies an entry in the mount point or device to mount field in the /etc/vfstab file. It is usually easier to specify the mount point.

Example--Mounting a File System Listed in the /etc/vfstab File

The following example mounts the /usr/openwin file system listed in the /etc/vfstab file.

# mount /usr/openwin

Mounting File Systems Using the mount Command

How to Mount a UFS File System

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Mount the UFS file system by using the mount command.

   # mount [-o mount-options] /dev/dsk/device-name mount-point

   -o mount-options	Specifies mount options that you can use to mount a UFS file system. See Table 28-3 for the list of general mount options or mount_ufs(1M) for a commonly used list of options.
   /dev/dsk/device-name	Specifies the disk device name for the slice holding the file system (for example, /dev/dsk/c0t3d0s7). See "How to Display Disk Slice Information" to get slice information for a disk.
   mount-point	Specifies the directory on which to mount the file system.

Example--Mounting a UFS File System

The following example mounts /dev/dsk/c0t3d0s7 on the /files1 directory.

# mount /dev/dsk/c0t3d0s7 /files1

Example--Mounting a UFS File System With Logging Enabled

UFS logging eliminates file system inconsistency, which can significantly reduce the time of system reboots. The following example mounts /dev/dsk/c0t3d0s7 on the /files1 directory with logging enabled.

# mount -o logging /dev/dsk/c0t3d0s7 /files1

How to Remount a UFS File System Without Large Files

When you mount a file system, the largefiles option is selected by default, which enables you to create files larger than 2 Gbytes. Once a file system contains large files, you cannot remount the file system with the nolargefiles option until you remove any large files and run fsck to reset the state to nolargefiles.

This procedure assumes that the file system is in the /etc/vfstab file.

1. Become superuser.

2. Make sure there are no large files in the file system.

   # cd mount-point # find . -xdev -size +2000000 -exec ls -l {} \;

   mount-point

   Specifies the mount point of the file system you want to check for large files.

   If large files exist within this file system, they must be removed or moved to another file system.

3. Unmount the file system.

   # umount mount-point

4. Reset the file system state.

   # fsck mount-point

5. Remount the file system with the nolargefiles option.

   # mount -o nolargefiles mount-point

Example--Mounting a File System Without Large Files

The following example checks the /datab file system and remounts it with the nolargefiles option.

# cd /datab
# find . -xdev -size +2000000 -exec ls -l {} \;
# umount /datab 
# fsck /datab
# mount -o nolargefiles /datab

How to Mount an NFS File System

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Make sure the resource (file or directory) is available from a server.

   To mount an NFS file system, the resource must be made available on the server by using the share command. See NFS Administration Guide for information on how to share resources.

3. Mount the NFS file system by using the mount command.

   # mount -F nfs [-o mount-options] server:/directory mount-point

   -o mount-options	Specifies mount options that you can use to mount an NFS file system. See Table 28-3 for the list of commonly used mount options or mount_nfs(1M) for a complete list of options.
   server:/directory	Specifies the server's host name that contains the shared resource, and the path to the file or directory to mount.
   mount-point	Specifies the directory on which to mount the file system.

Example--Mounting an NFS File System

The following example mounts the /export/packages directory on /mnt from the server pluto.

# mount -F nfs pluto:/export/packages /mnt

x86: How to Mount a System V (S5FS) File System

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Mount the S5FS file system by using the mount command.

   # mount -F s5fs [-o mount-options] /dev/dsk/device_name mount-point

   -o mount-options	Specifies mount options that you can use to mount a S5FS file system. See Table 28-3 for the list of commonly used mount options or mount_s5fs(1M) for a complete list of options.
   /dev/dsk/device-name	Specifies the disk device name of the slice holding the file system (for example, /dev/dsk/c0t3d0s7). See "How to Display Disk Slice Information" to get slice information for a disk.
   mount-point	Specifies the directory on which to mount the file system.

Example--Mounting an S5FS File System

The following example mounts /dev/dsk/c0t3d0s7 on the /files1 directory.

# mount -F s5fs /dev/dsk/c0t3d0s7 /files1

x86: How to Mount a PCFS (DOS) File System From a Hard Disk

Use the following procedure to mount a PCFS (DOS) file system from a hard disk.

1. Become superuser.

   Also, there must be a mount point on the local system to mount a file system. A mount point is a directory to which the mounted file system is attached.

2. Mount the PCFS file system by using the mount command.

   # mount -F pcfs [-o rw | ro] /dev/dsk/device-name:logical-drive mount-point

   -o rw | ro	Specifies that you can mount a PCFS file system read/write or read-only. If you do not specify this option, the default is read/write.
   /dev/dsk/device-name	Specifies the device name of the whole disk (for example, /dev/dsk/c0t0d0p0).
   logical-drive	Specifies either the DOS logical drive letter (c through z) or a drive number 1 through 24. Drive c is equivalent to drive 1 and represents the Primary DOS slice on the drive; all other letters or numbers represent DOS logical drives within the Extended DOS slice.
   mount-point	Specifies the directory on which to mount the file system.

   Note that the device-name and logical-drive must be separated by a colon.

Examples--Mounting a PCFS (DOS) File System From a Hard Disk

The following example mounts the logical drive in the Primary DOS slice on the /pcfs/c directory.

# mount -F pcfs /dev/dsk/c0t0d0p0:c /pcfs/c

The following example mounts the first logical drive in the Extended DOS slice read-only on /pcfs/d.

# mount -F pcfs -o ro /dev/dsk/c0t0d0p0:2 /pcfs/d

Unmounting File Systems

Unmounting a file system removes it from the file system mount point, and deletes the entry from the /etc/mnttab file. Some file system administration tasks cannot be performed on mounted file systems. You should unmount a file system when:

• It is no longer needed or has been replaced by a file system that contains more current software.

• You need to check and repair it using the fsck command. See Chapter 31, Checking File System Integrity for more information about the fsck command.

  It is a good idea to unmount a file system before doing a complete backup. See Chapter 34, Backing Up Files and File Systems (Tasks) for more information about doing backups.

  ---

  Note -

  File systems are automatically unmounted as part of the system shutdown procedure.

  ---

Prerequisites

The prerequisites to unmount file systems are:

• You must be superuser.

• A file system must be available for unmounting. You cannot umount a file system that is busy. A file system is considered busy if a user is in a directory in the file system, or if a program has a file open in that file system. You can make a file system available for unmounting by:

  • Changing to a directory in a different file system.

  • Logging out of the system.

  • Using the fuser command to list all processes accessing the file system and to stop them if necessary. See "How to Stop All Processes for a File System" for more details.

    Notify users if you need to unmount a file system they are using.

Verifying an Unmounted File System

To verify that you unmounted a file system or a number of file systems, look at the output from the mount command. This is described in "How to Determine Which File Systems Are Mounted".

How to Stop All Processes for a File System

1. Become superuser.

2. List all the processes that are using the file system, so you know which processes you are going to stop.

   # fuser -c [ -u ] mount-point

   -c	Reports on files that are mount points for file systems and any files within those mounted file systems.
   -u	Displays the user login name for each process ID.
   mount-point	The name of the file system for which you want to stop processes.

3. Stop all processes for the file system.

   ---

   Note -

   You should not stop a user's processes without warning.

   ---

   # fuser -c -k mount-point

   A SIGKILL is sent to each process using the file system.

4. Verify that there are no processes using the file system.

   # fuser -c mount-point

Example--Stopping All Processes for a File System

The following example stops process 4006c that is using the /export/home file system.

# fuser -c /export/home
/export/home:     4006c
# fuser -c -k /export/home
/export/home:     4006c
# fuser -c /export/home
/export/home: 

How to Unmount a File System

Use the following procedure to unmount a file system (except / or /usr):

The root (/) and /usr file systems are special cases. The root (/) file system can be unmounted only during a shutdown, since the system needs the root (/) file system to function.

1. Make sure you have met the prerequisites listed on "Prerequisites".

2. Unmount the file system.

   # umount mount-point

   mount-point

   The name of the file system that you want to unmount. This can either be the directory name where the file system is mounted, the device name path of the file system, the resource for an NFS file system, or the loopback directory for LOFS file systems.

Examples--Unmounting a File System

The following example unmounts a local home file system.

# umount /export/home

The following example unmounts the file system on slice 7.

# umount /dev/dsk/c0t0d0s7

How to Unmount File Systems Listed in the /etc/vfstab File

Use the following procedure to unmount all the file systems listed in the /etc/vfstab file, except for the /, /proc, /var, and /usr file systems.

1. Make sure you have met the prerequisites listed on "Prerequisites".

2. Unmount all the file systems listed in the /etc/vfstab file.

   # umountall

   All systems that are unmounted, except those that are busy.

3. For the file systems that were busy and not unmounted, make them available to be unmounted as described in "How to Stop All Processes for a File System".

4. Repeat Step 2 as needed until all file systems are unmounted.

Chapter 29 The Cache File System (Tasks)

The Cache File System (CacheFS) is a general purpose file system caching mechanism that improves NFS server performance and scalability by reducing server and network load. Designed as a layered file system, CacheFS provides the ability to cache one file system on another. In an NFS environment, CacheFS increases the client per server ratio, reduces server and network loads and improves performance for clients on slow links, such as Point-to-Point Protocol (PPP).

The following is a list of the step-by-step instructions in this chapter.

• "How CacheFS Works"

• "Setting Up a Cached File System Task Map"

• "How to Create a Cache"

• "How to Specify a File System to Be Mounted in a Cache With mount"

• "How to Mount a File System in a Cache by Editing the /etc/vfstab File"

• "How to Mount a File System in a Cache With AutoFS"

• "How to Modify File Systems in a Cache"

• "How to Display Information About Cached File Systems"

• "How to Specify Consistency Checking on Demand"

• "How to Delete a Cached File System"

• "How to Check the Integrity of Cached File Systems"

• "CacheFS Statistics"

• "Prerequisites for Setting Up and Viewing the CacheFS Statistics"

• "Setting Up CacheFS Statistics Task Map"

• "How to Set Up the Logging Process"

• "Viewing the Cache Size"

• "How to View the Working Set (Cache) Size"

• "Viewing the Statistics"

• "How to View Cache Statistics"

• "The Cache Structure and Behavior"

• "Consistency Checking of Cached File Systems With the Back File System"

• "Consistency Checking on Demand"

How CacheFS Works

You create a cache, using the cfsadmin(1M) command, on the client so that file systems you specify to be mounted in the cache can be accessed by the user locally instead of across the network. Figure 29-1 shows the relationship of the components involved in using CacheFS.

The back file system is the file system that you specify to be mounted in the cache, which can be either an NFS or HSFS (High Sierra File System) file system. When the user attempts to access files that are part of the back file system, those files are placed in the cache. To the user, the initial request to access a file may seem slow, but subsequent uses of the same file will be faster.

You can mount only file systems that are shared. See share(1M) for information on sharing file systems.

Figure 29-1 How CacheFS Works

Setting Up a Cached File System Task Map

Creating a Cache

How to Create a Cache

1. Become superuser.

2. Create a cache using the -c option of the cfsadmin command.

   # cfsadmin -c cache-directory

   cache-directory

   Indicates the name of the directory where the cache resides. For more information, see the cfsadmin man page.

   ---

   Note -

   After you have created the cache, do not perform any operations within the cache directory itself. This causes conflicts within the CacheFS software.

   ---

Example--Creating a Cache

The following example creates a cache in the /local/mycache directory by using the default cache parameter values.

# mkdir /local
# cfsadmin -c /local/mycache
 

Specifying a File System to Be Mounted in the Cache

You specify file systems to be mounted in the cache so that users can locally access files in the file system you've specified. The files do not actually get placed in the cache until the user accesses the files.

There are three ways to specify file systems to be cached:

• Using the mount(1M) command - you need to use the mount command every time the system reboots in order to access the same file system.

• Editing the /etc/vfstab file - you only need to do this once. The /etc/vfstab file will remain unaltered after the system reboots.

• Using AutoFS - you only need to do this once. AutoFS maps remain unaltered after the system reboots.

Choose the method of mounting file systems you are most familiar with.

Caching of the root (/) and /usr file systems is not supported in CacheFS. To cache the root (/) and /usr file systems, you must purchase the Solstice AutoClient product. For more information about the AutoClient product, see the Solstice AutoClient 2.1 Administration Guide.

How to Specify a File System to Be Mounted in a Cache With mount

1. Become superuser.

2. Create a mount point.

   The mount point allows user access to the file system specified under that mount point. You can create the mount point from anywhere. The CacheFS options used with the mount command, as shown in the next step, will determine that the mount point you created will be cached in the cache directory you specified.

3. Mount a file system in a cache with the mount command.

   # mount -F cachefs -o backfstype=fstype,cachedir=cache-directory[, options] back-filesystem mount-point

   fstype	Indicates the file system type of the back file system (can be either nfs or hsfs).
   cache-directory	Indicates the name of the directory where the cache resides. This is the same name you specified when you created the cache in "How to Create a Cache".
   options	Specifies other mount options that you can include when mounting a file system in a cache. See mount_cachefs(1M) for a list of CacheFS mount options.
   back-filesystem	The mount point of the back file system to cache. If the back file system is an NFS file system, you must specify the host name of the server from which you are mounting the file system and the name of the file system to cache (separated by a colon), for example, merlin: /usr/openwin
   mount-point	Indicates the directory where the file system is mounted.

4. Verify that the cache you created was actually mounted by using the cachefsstat(1M) command, as follows:

   # cachefsstat mount-point

   For example:

   # cachefsstat /docs /docs cache hit rate: 100% (0 hits, 0 misses) consistency checks: 1 (1 pass, 0 fail) modifies: 0 garbage collection: 0

   The mount point is the cached file system you created. For more information about the cachefsstat command, see "CacheFS Statistics".

   If the file system was not mounted in the cache, you will receive an error message similar to the following:

   # cachefsstat mount-point cachefsstat: mount-point: not a cachefs mountpoint

Examples--Specifying a File System to be Mounted in a Cache With mount

The following example creates the mount point /docs, and mounts the NFS file system merlin:/docs as a cached file system named /docs in the cache named /local/mycache.

# mkdir /docs
# mount -F cachefs -o backfstype=nfs,cachedir=/local/mycache merlin:/docs /docs
 

The following example makes a CD-ROM (HSFS file system) available as a cached file system named /docs. Because you cannot write to the CD-ROM, the ro argument is specified to make the cached file system read-only. You must specify the backpath option because Volume Management automatically mounts the CD-ROM when it is inserted. The mount point is in the /cdrom directory and is determined by the name of the CD-ROM. The special device to mount is the same as the value for the backpath command.

# mount -F cachefs -o backfstype=hsfs,cachedir=/local/mycache,ro backpath=/cdrom/cdrom_name 
/cdrom/cdrom_name /docs

The following example uses the demandconst option to specify consistency checking on demand for the NFS cached file system /docs, whose back file system is merlin:/docs. See "Consistency Checking of Cached File Systems With the Back File System" for more information.

# mount -F cachefs -o backfstype=nfs,cachedir=/local/mycache,demandconst merlin:/docs /docs
 

How to Mount a File System in a Cache by Editing the /etc/vfstab File

1. Become superuser.

2. Using an editor, specify the file systems to be mounted in the /etc/vfstab file:

   #device device mount FS fsck mount mount #to mount to fsck point type pass at boot options # /dev/dsk/devicename /dev/rdsk/devicename /mount-point cachefs 2 yes -

   This line represents the new entry.

3. Mount the cached file system using the mount command, as follows:

   # mount /mount-point

   or reboot.

Example--Mounting a File System in a Cache by Editing the /etc/vfstab File

The following example shows the /etc/vfstab entry for the cache file system.

 
#device           device             mount      FS    fsck  mount   mount
#to mount         to fsck            point      type  pass  at boot options
#
/dev/dsk/c0t1d0s0 /dev/rdsk/c0t1d0s0 /usr/local cachefs  2   yes     -

The /usr/local directory is mounted in the cache directory.

# mount /usr/local

How to Mount a File System in a Cache With AutoFS

You can mount a file system in a cache with AutoFS by specifying the -fstype=cachefs mount option in your automount map. Note that CacheFS mount options (for example, backfstype and cachedir) are also specified in the automount map. See automount(1M) for details on automount maps. Also see the NFS Administration Guide.

1. Become superuser.

2. Using an editor, add the following line to the auto_direct map:

   /mount-point -fstype=cachefs,cachedir=/directory,backfstype=nfs server:/file-system

3. Using an editor, add the following line to the auto_master map:

   /-

   The /- entry is a pointer to check the auto_direct map.

4. Reboot the system.

5. Verify that the entry was made correctly by changing to the file system you mounted in the cache, and then list the contents, as follows:

   # cd filesystem # ls filesystem

For more information about AutoFS and how to edit the maps, refer to the AutoFS chapter of the NFS Administration Guide.

Example--Mounting a File System in a Cache With AutoFS

The following auto_master entry automatically mounts the cache file system in the /docs directory.

/docs	 -fstype=cachefs,cachedir=/local/mycache,backfstype=nfs 
merlin:/docs

Maintaining a Cached File System Task Map

Maintaining the Cache

After you set up the cache, you can perform the following maintenance tasks on it:

• Modify file systems in the cache (by unmounting, deleting, recreating, and remounting the cache)

• Display cache information

• Check cache consistency

• Delete a file system from the cache

• Check cached file system integrity

  ---

  Note -

  If you are using the /etc/vfstab file to mount file systems, you modify the cache by editing the file systems options in the /etc/vfstab file. If you are using AutoFS, you modify the cache by editing the file systems options in the AutoFS maps.

  ---

How to Modify File Systems in a Cache

For information on how to modify specific options of a file system, refer to Chapter 28, Mounting and Unmounting File Systems (Tasks). When you modify a file system in the cache, you need to delete the cache and then recreate it. You may also need to reboot your machine in single user mode, depending on how your file systems are shared and accessed.

The following example shows some of the steps involved in this procedure.

Example--Modifying File Systems in a Cache

In the following example, the cache is deleted, then re-created, and then mounted again with the demandconst option specified for the file system /docs. This example shows the steps including rebooting to single user mode. You may have other commands you prefer to use to accomplish some of the tasks shown in this example.

$ su
password:
 
# shutdown -g30 -y
.
.
.
Type Cntrl-d to proceed with normal startup,
(or give root password for system maintenance):
# enter password:
.
.
.
Here is where you may be prompted from system to run fsck on the 
file system where the cache is located.
 
# fsck /local
# mount /local
# cfsadmin -d all /local/mycache
# cfsadmin -c /local/mycache
# init 6
.
.
.
console login:
password:
# mount -F cachefs -o backfstype=nfs,cachedir=/local/cache1, demandconst merlin:/docs /docs 
#

If you did not successfully remount the file system in the cache, the system displays an error message similar to the following:

cachefsstat: /doc: not a cachefs mount point

How to Display Information About Cached File Systems

1. Become superuser.

2. Display information about all file systems cached under a specified cache.

   # cfsadmin -l cache-directory

   cache-directory is the name of the directory where the cache resides.

Example--Displaying Information About Cached File Systems

The following example shows information about the cache directory named /local/mycache. In this example, the file system /docs is cached in /local/mycache. The last line displays the name of the cached file system.

# cfsadmin -l /local/mycache
cfsadmin: list cache FS information
   maxblocks     90%
   minblocks      0%
   threshblocks  85%
   maxfiles      90%
   minfiles       0%
   threshfiles   85%
   maxfilesize    3MB
merlin:_docs:_docs
#

How to Specify Consistency Checking on Demand

1. Become superuser.

2. Mount the file system in the cache specifying the demandconst option of the mount command, as follows:

   # mount -F cachefs -o backfstype=nfs,cachedir=/directory,demandconst server:/file-system /mount-point

3. To initiate consistency checking on a specific cached file system, use the cfsadmin command with the -s option as follows:

   # cfsadmin -s /mount-point

   For more information about consistency checking, see "Consistency Checking of Cached File Systems With the Back File System".

How to Delete a Cached File System

1. Become superuser.

2. Unmount the cached file system.

   # umount mount-point

   mount-point specifies the cached file system that you want to delete.

3. Determine the cache ID from the cfsadmin -l output, as follows:

   # cfsadmin -l cache-directory cfsadmin: list cache FS information maxblocks 90% minblocks 0% threshblocks 85% maxfiles 90% minfiles 0% threshfiles 85% maxfilesize 3MB cache-ID #

4. Delete a cached file system from a specified cache.

   # cfsadmin -d cache-id cache-directory

   cache-id	Indicates the name of the cached file system, which is the last line of the cfsadmin -l output. See "How to Display Information About Cached File Systems" for more information. You can delete all the cached file systems in a particular cache by specifying all for cache-id.
   cache-directory	Specifies the directory where the cache resides.

5. Verify that the file system has been deleted.

   The cache ID of the file system you just deleted should be missing from the output of the following command. Refer to cfsadmin(1M) for more information about the fields specified in the command output.

   # cfsadmin -l cache-directory cfsadmin: list cache FS information maxblocks 90% minblocks 0% threshblocks 85% maxfiles 90% minfiles 0% threshfiles 85% maxfilesize 3MB #

Examples--Deleting a Cached File System

The following example unmounts a cached file system and deletes the cached file system from the cache.

# umount /docs
# cfsadmin -d merlin:_docs:_docs /local/mycache

The following example deletes all the cached file systems in the /local/mycache cache. This also deletes the cache.

# cfsadmin -d all /local/mycache

How to Check the Integrity of Cached File Systems

Use the fsck command to check the integrity of cached file systems. The CacheFS version of fsck automatically corrects problems without requiring user interaction. You should not need to run fsck manually for cached file systems; fsck is run automatically at boot time or when the file system is mounted. If you want to manually check the integrity, you can use the following procedure.

See fsck_cachefs(1M) for more information.

1. Become superuser.

2. Check the cached file systems under a specified cache.

   # fsck -F cachefs [-m] [-o noclean] cache-directory

   -m	Causes fsck to check the cached file systems without making any repairs.
   -o noclean	Forces a check on the cached file systems only. Does not make any repairs.
   cache-directory	Indicates the name of the directory where the cache resides.

Example--Checking the Integrity of Cached File Systems

The following example checks the cached file systems that are part of the /local/mycache cache.

# fsck -F cachefs /local/mycache
#

Managing Your Cache File Systems With cachefspack

For general use, CacheFS operates automatically, without requiring any action from the user. Files are cached on a most recently used basis. With the packing feature, you can take a more active role in managing your cache by ensuring that certain files or directories are always updated in the cache.

Packing enables you to specify files and directories to be loaded in the cache. It ensures that current copies of these files are available in the cache.

The packing list contains the names of specific files and directories. It can also contain other packing lists. This saves you having to specify individual files and directories in case you have many items to pack in your cache.

The cachefspack command provides you with added control of your CacheFS file systems, employing the packing functionality.

How to Pack Files in the Cache

Pack files in the cache using the cachefspack command.

$ cachefspack -p filename

Examples--Packing Files in the Cache

The following example shows the file projects specified to be packed in the cache.

$ cachefspack -p projects

The following example shows several files specified to be packed in the cache.

$ cachefspack -p projects updates master_plan 

The following example shows a directory specified to be packed in the cache.

$ cachefspack -p /usr/openwin/bin

Packing Lists

One of the features of the cachefspack command is the ability to pack packing lists. This saves the time of having to specify each individual file that you want packed in the cache.

A packing list contains files or directories to be packed in the cache. If a directory is in the packing list, all of its subdirectories and files will also be packed.

How to Create a Packing List

To create a packing list, open a file by using vi or the editor of your choice. The packing list file format uses the same format as the filesync command. See filesync(1) for more information.

Example--Creating a Packing List

The following example shows the contents of a packing list file.

BASE /home/ignatz
LIST plans
LIST docs
IGNORE *.ps

• The path identified with the BASE statement is the directory where you have items you wish to pack.

• The two LIST statements identify specific files within that directory to pack.

• The IGNORE statement identifies the file type of .ps, which you do not wish to pack.

How to Pack Files in the Cache as Specified in a Packing List

To pack files using the packing list, use the cachefspack -f command, as follows:

$ cachefspack -f packing-list

This means you want the software to read the packing list and pack files based on the information specified in the packing list.

Example--Packing Files in the Cache as Specified in a Packing List

This examples uses the list.pkg file as the packing list for the cachefspack command.

$ cachefspack -f list.pkg

How to Specify Files in the Packing List to be Treated as Regular Expressions

To specify that one or more files in the packing list should be treated as regular expressions (not as literal file names), use the -r option with the -f option of the cachefspack command. The -r option cannot be used alone.

$ cachefspack -rf packing_list

where packing_list contains a LIST command defined as follows:

LIST *.doc

Example--Specifying Files in the Packing List to be Treated as Regular Expressions

The following example shows the packing list list.pkg specified to be packed in the cache. list.pkg contains a LIST command that defines a regular expression.

$ cachefspack -rf list.pkg

The software will pack the file list.pkg into the cache and treat the file names defined in the LIST command as regular expressions, and not as literal file names.

How to Pack Files From a Shared Directory

1. To pack files from a shared directory, and to ensure that you pack only those files that you own, define the LIST command within the packing list file as follows:

   LIST !find . -user your_user_name -print

2. Pack the packing list in the cache using the cachefspack -sf command.

   $ cachefspack -sf packing_list

   -s	Adjusts the output of the find command to be suitable for the packing list.
   -f	Specifies a packing list to read.
   filename	Specifies the name of the packing list to read.

   ---

   Note -

   The -s option must be used with the -f option. The -s option cannot be used alone.

   ---

Example--Packing Files From a Shared Directory

The following example shows how to define a LIST command in the packing list to pack only the files from the base directory that you own:

LIST !find . -user jones -print

The following example shows how you would then specify packing the packing list.

$ cachefspack -sf /projects/proj_1

Unpacking Files

You may need to remove, or unpack, a file from the cache. Perhaps you have some files or directories that are a higher priority than others, so you need to unpack the less critical files. For example, you finished up a project and have archived the files associated with that project. You are now working on a new project, and therefore, a new set of files.

How to Unpack Files or Packing Lists From the Cache

Unpack files or packing lists from the cache using the -u or -U option of the cachefspack command.

$ cachefspack -u filename | -U cache-directory

Examples--Unpacking Files or Packing Lists From the Cache

The following example shows the file /usr/openwin/bin/xlogo specified to be unpacked from the cache.

$ cachefspack -u /usr/openwin/bin/xlogo

The following example shows several files specified to be unpacked from the cache.

$ cd /usr/openwin/bin
$ cachefspack -u xlogo xview xcolor

You can also unpack a packing list, which is a file that contains the path to a directory of files, as follows:

$ cachefspack -uf list.pkg

The following example uses the -U option to specify all files in a cache directory to be unpacked.

$ cachefspack -U /local/mycache

You cannot unpack a cache that does not have at least one file system mounted. With the -U option, if you specify a cache that does not contain mounted filesystems, you will see output similar to the following:

$ cachefspack -U /local/mycache
cachefspack: Could not unpack cache /local/mycache, no mounted
filesystems in the cache.

Displaying Packed Files Information

You may want to view information about the files that you've specified to be packed, and what their packing status is.

How to Display Packed Files Information

To display packed files information, use cachefspack -i command.

$ cachefspack -i[v] cached-filename-or-directory

Example--Displaying Packed Files Information

The following example shows that a file called doc_file is successfully packed.

$ cachefspack -i doc_file
cachefspack: file doc_file marked packed YES, packed YES

The following example shows a directory called /usr/openwin, which contains a subdirectory bin. The subdirectory bin has three files: xterm, textedit, and resize. Although the files xterm and resize are specified to be packed, they are not. The file textedit is successfully packed.

$ cd /usr/openwin
$ cachefspack -i bin
.
.
.
cachefspack: file /bin/xterm marked packed YES, packed NO
cachefspack: file /bin/textedit marked packed YES,
packed YES
cachefspack: file /bin/resize marked packed YES,
packed NO
.
.
.

If you use the -v option in combination with the -i option, you will get additional information as to whether or not the file or directory specified has been flushed from the cache. For example:

$ cd /usr/openwin
$ cachefspack -iv bin
.
.
.
cachefspack: file /bin/xterm marked packed YES, packed NO,
nocache YES
cachefspack: file /bin/textedit marked packed YES,
packed YES, nocache NO
cachefspack: file /bin/resize marked packed YES,
packed NO
nocache NO
.
.
.

The last line of the example above shows that the directory contents have not been flushed from the cache.

Viewing Help on the cachefspack Command

You can print out a brief help summary of all the cachefspack options and what they mean by using the -h option as follows:

$ cachefspack -h
Must select 1 and only 1 of the following 5 options
-d Display selected filenames
-i Display selected filenames packing status
-p Pack selected filenames
-u Unpack selected filenames
-U Unpack all files in directory 'dir'
 
-f Specify input file containing rules
-h Print usage information
-r Interpret strings in LIST rules as regular expressions
-s Strip './' from the beginning of a pattern name
-v Verbose option
files - a list of filenames to be packed/unpacked

cachefspack Errors

You may see the following error messages when you use the cachefspack command.

cachefspack: pathname - can't open directory: permission denied

cachefspack: pathname - can't open directory: no such file or
directory

cachefspack: pathname - can't open directory: stale NFS file handle

cachefspack: pathname - can't open directory: interrupted system
call

cachefspack: pathname - can't open directory: I/O error

cachefspack: error opening dir

cachefspack: unable to get shared objects

cachefspack: filename - can't pack file: permission denied

cachefspack: filename - can't pack file: no such file or directory

cachefspack: filename - can't pack file: stale NFS file handle

cachefspack: filename - can't pack file: interrupted system call

cachefspack: filename - can't pack file: I/O error

cachefspack: filename - can't pack file: no space left on device.

cachefspack: filename - can't unpack file: permission denied

cachefspack: filename - can't unpack file: no such file or directory

cachefspack: filename - can't unpack file: stale NFS file handle

cachefspack: filename - can't unpack file: interrupted system call

cachefspack: filename - can't unpack file I/O error

cachefspack: only one `d', `i', `p', or `u' option allowed

cachefspack: can't find environment variable.

cachefspack: skipping LIST command - no active base

CacheFS Statistics

CacheFS statistics enable you to:

• Determine an appropriate cache size

• Observe the performance of the cache

These two pieces of information will help you determine the trade-off between your cache size and the desired performance of the cache.

The CacheFS statistics consist of three commands:

The CacheFS statistics commands can be issued from any directory. You must be superuser to issue the cachefswssize(1M) command.

The statistics begin accumulating when you create the log file. When the work session length of time is up, stop the logging by using the cachefslog -h command, as described in "How to Stop the Logging Process".

Prerequisites for Setting Up and Viewing the CacheFS Statistics

Before using the CacheFS statistics commands, you must:

• Set up your cache using the cfsadmin(1M) command.

• Decide on an appropriate length of time to allow statistical information to collect in the log file you create. The length of time should equal a typical work session; for example, a day, a week, or a month.

• Select a location or path for the log file. Make sure there is enough space to allow for the growth of the log file. The longer you intend to allow statistical information to collect in the log file, the more space you will need.

The following procedures are presented in a recommended order. The order is not required.

Setting Up CacheFS Statistics Task Map

Table 29-3 shows the steps involved in setting up CacheFS statistics.

CacheFS Logging

This section describes how to set up and view CacheFS logging.

How to Set Up the Logging Process

1. Set up the logging process with the cachefslog command.

   $ cachefslog -f log-file-path mount-point

   -f	Sets up the logging process.
   log-file-path	Specifies the location of the log file. The log file is a standard file you create with an editor, such as vi.
   mount-point	Designates the mount point (cached file system) for which statistics are being collected.

2. Verify that you set up the log file correctly by using the cachefslog command, as follows:

   $ cachefslog mount-point

Example--Setting Up the Logging Process

The following example sets up the log file samlog to collect statistics about /home/sam. The location of samlog is /var/tmp/samlog.

$ cachefslog -f /var/tmp/samlog /home/sam
  /var/tmp/samlog: /home/sam

How to Locate the Log File

You can also use the cachefslog(1M) command with no options to locate a log file for a particular mount point.

$ cachefslog mount-point 

Examples--Locating the Log File

The following example shows what you would see if a log file has been set up. The location of the log file is /var/tmp/stufflog.

$ cachefslog /home/stuff
	 /var/tmp/stufflog: /home/stuff

The following example shows that no log file has been set up for the specified file system.

$ cachefslog /home/zap
	not logged: /home/zap 

How to Stop the Logging Process

Use the -h option of the cachefslog(1M) command to stop the logging process.

$ cachefslog -h mount-point

Example--Stopping the Logging Process

The following example halts logging on /home/stuff.

$ cachefslog -h /home/stuff
not logged: /home/stuff

If you get a system response other than the one specified in the above example, you did not successfully stop the logging process. Check to see if you are using the correct log file name and mount point.

Viewing the Cache Size

You may want to check if you need to increase the size of the cache or determine what the ideal cache size is based on your activity since you last used the cachefslog(1M) command for a particular mount point.

How to View the Working Set (Cache) Size

1. Become superuser.

2. View the current and highest logged cache size with the cachefswssize(1M) command.

   # cachefswssize log-file-path

Example--Viewing the Working Set (Cache) Size

In the following example, the end size is the size of the cache at the time you issued the cachefswssize command. The high water size is the largest size of the cache during the time frame in which logging has occurred.

# cachefswssize /var/tmp/samlog
 
    /home/sam
	       end size:  10688k
	high water size:  10704k
 
    /
	       end size:   1736k
	high water size:   1736k
 
    /opt
	       end size:    128k
	high water size:    128k
 
    /nfs/saturn.dist
	       end size:   1472k
	high water size:   1472k
 
    /usr/openwin
	       end size:   7168k
	high water size:   7168k
 
    /nfs/venus.svr4
	       end size:   4688k
	high water size:   5000k
 
    /usr
	       end size:   4992k
	high water size:   4992k
 
    total for cache
	   initial size: 110960k
	       end size:  30872k
	high water size:  30872k

Viewing the Statistics

You may want to view certain information about a specific cached file system. The following table explains the terminology displayed in the statistics output.

How to View Cache Statistics

View the statistics with the cachefsstat(1M) command. You can do this at any time. For example, you do not have to set up logging in order to view the statistics.

$ cachefsstat mount-point

If you do not specify the mount point, statistics for all mounted CacheFS file systems will be displayed.

Example--Viewing Cache Statistics

$ cachefsstat /home/sam
	    cache hit rate: 73% (1234 hits, 450 misses)
	consistency checks: 700 (650 pass, 50 fail)
	          modifies: 321
garbage collection:  0

The Cache Structure and Behavior

Each cache has a set of parameters that determines how it behaves and its structure. The parameters are set to default values which are listed in Table 29-5. The default values specify that the entire front file system is used for caching, which is the recommended method of caching file systems.

Typically, you should not change any of these parameter values. They are set to default values to achieve optimal cache behavior. However, you may want to modify the maxblocks and maxfiles settings if you have some room in the front file system that is not used by the cache, and you wish to use it for some other file system. You do this using the cfsadmin(1M) command. For example:

$ cfsadmin -o maxblocks=60

Consistency Checking of Cached File Systems With the Back File System

To ensure that the cached directories and files are kept up to date, CacheFS periodically checks consistency of files stored in the cache. To check consistency, CacheFS compares the current modification time to the previous modification time. If the modification times are different, all data and attributes for the directory or file are purged from the cache and new data and attributes are retrieved from the back file system.

When a user requests an operation on a directory or file, CacheFS checks if it is time to verify consistency. If it is, CacheFS obtains the modification time from the back file system and performs the comparison.

Consistency Checking on Demand

By specifying the demandconst option of the mount(1M) command, consistency checks can be performed only when you explicitly request them for file systems mounted with this option. After specifying the demandconst option when you mount a file system in a cache, you use the cfsadmin(1M) command with the -s option to request a consistency check. By default, consistency checking is performed file by file as the files are accessed. If no files are accessed, no checks are performed. Use of the demandconst option will avoid the situation where the network is flooded with consistency checks. For more information about consistency checking on demand, refer to the cfsadmin command.

Chapter 30 Configuring Additional Swap Space (Tasks)

This is a list of the overview conceptual information and step-by-step instructions in this chapter.

• "Swap Space and Virtual Memory"

• "Swap Space and the TMPFS File System"

• "How Do I Know If I Need More Swap Space?"

• "How Swap Space Is Allocated"

• "Planning for Swap Space"

• "Monitoring Swap Resources"

• "Adding More Swap Space"

• "Removing a Swap File From Use"

About Swap Space

This section provides a conceptual overview of swap space and briefly discusses the differences between the SunOS 4.0/4.1 and the SunOS 5.7 swap requirements. If you are already familiar with the SunOS 5.7 swap mechanism, proceed to the section called "Planning for Swap Space".

It is important for administrators to understand the features of the SunOS 5.7 swap mechanism in determining:

• Swap space requirements

• The relationship with the TMPFS file system

• Recovery from error messages related to swap space

Swap Space and Virtual Memory

The SunOS 5.7 system software uses some disk slices for temporary storage rather than for file systems. These slices are called swap slices. Swap slices are used as virtual memory storage areas when the system does not have enough physical memory to handle current processes.

The SunOS 5.7 virtual memory system maps physical copies of files on disk to virtual addresses in memory. Physical memory pages which contain the data for these mappings can be backed by regular files in the file system, or by swap space. If the memory is backed by swap space it is referred to as anonymous memory because the user doesn't know the names of the files backing the memory.

SunOS 4.0/4.1 anonymous memory pages are mapped using randomly assigned names from the system's swap space pool. These memory pages are used for:

• Private copies of data created during copy-on-write operations

• Process and stack segments

• The TMPFS file system storage resources

The limitations of the SunOS 4.0/4.1 anonymous memory implementation are:

• Physical storage (disk-backed swap) must always be reserved for anonymous memory mappings even if the application doesn't use it.

  For example, applications with large data segments must be configured with lots of swap space even if the pages are not written out to physical storage.

• The formula used to associate an anonymous memory page with physical storage is limited and inflexible because the backing store is chosen at random and can never be changed.

The SunOS 5.7 software environment introduces the concept of virtual swap space, a layer between anonymous memory pages and the physical storage (or disk-backed swap space) that actually back these pages. A system's virtual swap space is equal to the sum of all its physical (disk-backed) swap space plus a portion of the currently available physical memory.

Virtual swap space has these advantages:

• The need for large amounts of physical swap space is reduced because virtual swap space does not necessarily correspond to physical (disk) storage.

• A pseudo file system called SWAPFS provides addresses for anonymous memory pages. Because SWAPFS controls the allocation of memory pages, it has greater flexibility in deciding what happens to a page. For example, it may change the page's requirements for disk-backed swap storage.

Swap Space and the TMPFS File System

The TMPFS file system is activated automatically in the SunOS 5.7 environment by an entry in the /etc/vfstab file. The TMPFS file system stores files and their associated information in memory (in the /tmp directory) rather than on disk, which speeds access to those files. This results in a major performance enhancement for applications such as compilers and DBMS products that use /tmp heavily.

The TMPFS file system allocates space in the /tmp directory from the system's swap resources. This means that as you use up space in /tmp, you are also using up swap space. So if your applications use /tmp heavily and you do not monitor swap space usage, your system could run out of swap space.

Use the following if you want to use TMPFS but your swap resources are limited:

• Mount the TMPFS file system with the size option (-o size) to control how much of the swap resources TMPFS can use.

• If you are close to running out of swap space, you can use your compiler's TMPDIR environment variable to point to a larger temporary directory.

  Using your compiler's TMPDIR variable only controls whether the compiler is using /tmp or not. It has no effect on other programs' use of /tmp.

How Do I Know If I Need More Swap Space?

This section lists several possible error messages displayed when you run out of swap space.

Swap-Related Error Messages

These messages indicate that an application was trying to get more anonymous memory and there was no swap space left to back it.

application is out of memory
 
malloc error O
 
WARNING: Sorry, no swap space to grow stack for pid

TMPFS-Related Error Messages

directory: File system full, swap space limit exceeded

This message is displayed if a page could not be allocated when writing a file. This can occur when TMPFS tries to write more than it is allowed or if currently executed programs are using a lot of memory.

directory: File system full, memory allocation failed

This messages means TMPFS ran out of physical memory while attempting to create a new file or directory.

See TMPFS(7FS) for information on recovering from the TMPFS-related error messages.

How Swap Space Is Allocated

Initially, swap space is allocated as part of the Solaris installation process. If you use the installation program's automatic layout of disk slices and do not manually change the size of the swap slice, the Solaris installation program allocates default swap slices as shown in Table 30-1.

The /etc/vfstab File

After the system is installed, swap slices and files are listed in the /etc/vfstab file and are activated by the /sbin/swapadd script when the system is booted.

An entry for a swap device in the /etc/vfstab file contains:

• The full path name of the swap slice or file

• File system type of swap

Because the file system containing a swap file must be mounted before the swap file is activated, make sure that the entry that mounts the file system comes before the entry that activates the swap file in the /etc/vfstab file.

Planning for Swap Space

The most important factors in determining swap space size are the requirements of the system's software applications. For example, large applications such as computer-aided-design simulators, database-management products, transaction monitors, and geologic analysis systems can consume as much as 200-1000 Mbytes of swap space in very large memory systems.

Consult your application vendor for swap space requirements for any application whose data files typically exceed 10-20 Mbytes in size.

If you are unable to determine swap space requirements from the application vendor, use the following guidelines to allocate swap space:

• To support your applications, allocate:

  • 1 Mbyte per trivial application such as xterm.

  • 2-3 Mbytes per lightweight application such as a calendar or mail application.

  • 20-50 Mbytes for large applications such as desktop publishing software.

• To save crash dumps, allocate 100% of physical memory to save a worst-case crash dump.

• If you are unsure of system or application requirements, allocate 50 to 100% of the system's physical memory. For example, allocate 16-32 Mbytes of swap space for a system with 32 Mbytes of physical memory. This will provide 48-64 Mbytes of total virtual swap space.

• Determine whether large applications (like compilers) will be using the /tmp directory. Then allocate additional swap space to be used by TMPFS. See "Swap Space and the TMPFS File System" for information about TMPFS.

Monitoring Swap Resources

The /usr/sbin/swap command is used to manage swap areas. Two options, -l and -s, are used to display information about swap resources.

Use the swap -l command to identify a system's swap areas. Activated swap devices or files are listed under the swapfile column.

# swap -l
swapfile           dev  swaplo blocks   free
/dev/dsk/c0t2d0s1 32,17      8 205624 192704

Use the swap -s command to monitor swap resources.

# swap -s
total: 10492k bytes allocated + 7840k reserved = 18332k used, 21568k available

The used plus available figures equals total swap space on the system, which includes a portion of physical memory and swap devices (or files).

You can use the amount of swap space available and used (in the swap -s output) as a way to monitor swap space usage over time. If a system's performance is good, use swap -s to see how much swap space is available. When the performance of a system slows down, check the amount of swap space available to see if it has decreased. Then you can identify what changes to the system might have caused swap space usage to increase.

Keep in mind when using this command that the amount of physical memory available for swap usage changes dynamically as the kernel and user processes lock down and release physical memory.

The swap -l command displays swap space in 512-byte blocks and the swap -s command displays swap space in 1024-byte blocks. If you add up the blocks from swap -l and convert them to Kbytes, it will be less than used + available (in the swap -s output) because swap -l does not include physical memory in its calculation of swap space.

The output from the swap -s command is summarized in Table 30-2.

Adding More Swap Space

As system configurations change and new software packages are installed, you might need to add more swap space. The preferred way to add more swap space is to use the mkfile and swap commands to designate a part of an existing UFS or NFS file system as a supplementary swap area. These commands, described below, enable you to add more swap space without repartitioning a disk.

An alternative way to add more swap space is to repartition a disk. See Chapter 21, Disk Management (Overview) for information on how to repartition a disk.

Creating a Swap File

The following general steps are involved in creating a swap file:

• Creating a swap file using the mkfile command.

• Activating the swap file with the swap command.

• Adding an entry for the swap file in the /etc/vfstab file so that it's activated automatically when the system is booted.

The mkfile Command

The mkfile command creates a file that is suitable for use either as an NFS-mounted or local swap area. The sticky bit is set, and the file is padded with zeros. You can specify the size of the swap file in bytes (the default) or in kilobytes, blocks, or megabytes using the k, b, or m suffixes, respectively.

Table 30-3 shows the options to the mkfile command.

Use the -n option only when creating an NFS swap file.

How to Create a Swap File and Make It Available

1. Become superuser.

   You can create a swap file without root permissions, but it is a good idea for root to be the owner of the swap file to avoid accidental overwriting.

2. Create the swap file.

   # mkfile nnn[k|b|m] filename

   The swap file of the size nnn (in Kbytes, bytes, or Mbytes) and name you specify is created.

3. Activate the swap file.

   # /usr/sbin/swap -a /path/filename

   You must use the absolute path name to specify the swap file. The swap file is added and available until the file system is unmounted or the system is rebooted.

4. Add an entry for the swap file to the /etc/vfstab file that specifies the full path name of the file, and designates swap as the file system type, like this:

   /path/filename - - swap - no -

5. Verify that the swap file is added.

   /usr/sbin/swap -l

Example--Creating a Swap File and Making It Available

The following examples shows how to create a 24 Mbyte swap file called /files/swapfiles.

# mkdir /files
# mkfile 24m /files/swapfile
# swap -a /files/swapfile
# vi /etc/vfstab
(An entry is added for the swap file):
/files/swapfile   -      -       swap     -     no     -
# swap -l
swapfile             dev  swaplo blocks   free
/dev/dsk/c0t2d0s1   32,17      8 205624 192704
/files/swapfile       -        8  40952  40952

Removing a Swap File From Use

If the user no longer needs the extra swap space, you can remove it.

How to Remove Extra Swap Space

1. Become superuser.

2. Use the swap -d command to remove swap space.

   # /usr/sbin/swap -d /path/filename

   The swap file name is removed from the list so that it is no longer available for swapping. The file itself is not deleted.

3. Edit the /etc/vfstab file and delete the entry for the swap file.

4. Recover the disk space so that you can use it for something else.

   # rm swap-filename

   If the swap space is a file, remove it. Or, if the swap space is on a separate slice and you are sure you will not need it again, make a new file system and mount the file system.

   See Chapter 28, Mounting and Unmounting File Systems (Tasks) for more information.

Example--Removing Extra Swap Space

The following examples shows how to delete the /files/swapfile swap file.

# swap -d /files/swapfile
# swap -l
swapfile             dev  swaplo  blocks   free
/dev/dsk/c0t2d0s1   32,17      8  205624  192720
 

Chapter 31 Checking File System Integrity

This is a list of the conceptual information and step-by-step instructions in this chapter.

• "Understanding How the File System State Is Recorded"

• "What fsck Checks and Tries to Repair"

• "Modifying Automatic Boot Checking"

• "Interactively Checking and Repairing a UFS File System"

• "Restoring a Bad Superblock"

• "Syntax and Options for the fsck Command"

See "Troubleshooting File System Problems" in System Administration Guide, Volume II for information about fsck error messages.

The UFS file system relies on an internal set of tables to keep track of inodes used and available blocks. When these internal tables are not properly synchronized with data on a disk, inconsistencies result and file systems need to be repaired.

File systems can be damaged or become inconsistent because of abrupt termination of the operating system in these ways:

• Power failure

• Accidental unplugging of the system

• Turning the system off without proper shutdown procedure

• A software error in the kernel

File system corruption, while serious, is not common. When a system is booted, a file system consistency check is automatically performed (with the fsck program). Most of the time, this file system check repairs problems it encounters.

This chapter describes what the fsck program checks, and repairs and the fsck options. It also describes the following tasks:

• How to modify the automatic checking done during booting

• How to find out if a file system needs to be checked

• How to check and repair a UFS file system interactively

• How to restore a bad superblock

• How to fix a UFS file system that fsck cannot repair

The fsck error messages are covered in "Troubleshooting File System Problems" in System Administration Guide, Volume II.

The fsck program places files and directories that are allocated but unreferenced in the lost+found directory. The inode number of each file is assigned as the name. If the lost+found directory does not exist, fsck creates it. If there is not enough space in the lost+found directory, fsck increases its size.

Understanding How the File System State Is Recorded

The fsck command uses a state flag, which is stored in the superblock, to record the condition of the file system. This flag is used by the fsck command to determine whether or not a file system needs to be checked for consistency. The flag is used by the /sbin/rcS script during booting and by the fsck command when run from a command line using the -m option. If you ignore the result from the -m option to fsck, all file systems can be checked regardless of the setting of the state flag.

The possible state flag values are described in Table 31-1.

Table 31-2 shows how the state flag is modified by the fsck command, based on its initial state.

What fsck Checks and Tries to Repair

This section describes what happens in the normal operation of a file system, what can go wrong, what problems fsck (the checking and repair utility) looks for, and how it corrects the inconsistencies it finds.

Why Inconsistencies May Occur

Every working day hundreds of files may be created, modified, and removed. Each time a file is modified, the operating system performs a series of file system updates. These updates, when written to the disk reliably, yield a consistent file system.

When a user program does an operation to change the file system, such as a write, the data to be written is first copied into an internal in-core buffer in the kernel. Normally, the disk update is handled asynchronously; the user process is allowed to proceed even though the data write may not happen until long after the write system call has returned. Thus at any given time, the file system, as it resides on the disk, lags behind the state of the file system represented by the in-core information.

The disk information is updated to reflect the in-core information when the buffer is required for another use or when the kernel automatically runs the fsflush daemon (at 30-second intervals). If the system is halted without writing out the in-core information, the file system on the disk will be in an inconsistent state.

A file system can develop inconsistencies in several ways. The most common causes are operator error and hardware failures.

Problems may result from an unclean halt, if a system is shut down improperly, or when a mounted file system is taken offline improperly. To prevent unclean halts, the current state of the file systems must be written to disk (that is, "synchronized") before halting the CPU, physically taking a disk pack out of a drive, or taking a disk offline.

Inconsistencies can also result from defective hardware. Blocks can become damaged on a disk drive at any time, or a disk controller can stop functioning correctly.

The UFS Components That Are Checked for Consistency

This section describes the kinds of consistency checks the fsck applies to these UFS file system components: superblock, cylinder group blocks, inodes, indirect blocks, and data blocks.

Superblock

The superblock stores summary information, which is the most commonly corrupted item in a UFS file system. Each change to the file system inodes or data blocks also modifies the superblock. If the CPU is halted and the last command is not a sync command, the superblock will almost certainly be corrupted.

The superblock is checked for inconsistencies in:

• File system size

• Number of inodes

• Free-block count

• Free-inode count

File System and Inode List Size

The file system size must be larger than the number of blocks used by the superblock and the number of blocks used by the list of inodes. The number of inodes must be less than the maximum number allowed for the file system. The file system size and layout information are the most critical pieces of information for fsck. Although there is no way to actually check these sizes, because they are statically determined when the file system is created, fsck can check that the sizes are within reasonable bounds. All other file system checks require that these sizes be correct. If fsck detects corruption in the static parameters of the primary superblock, it requests the operator to specify the location of an alternate superblock.

Free Blocks

Free blocks are stored in the cylinder group block maps. fsck checks that all the blocks marked as free are not claimed by any files. When all the blocks have been accounted for, fsck checks to see if the number of free blocks plus the number of blocks claimed by the inodes equal the total number of blocks in the file system. If anything is wrong with the block allocation maps, fsck rebuilds them, leaving out blocks already allocated.

The summary information in the superblock contains a count of the total number of free blocks within the file system. The fsck program compares this count to the number of free blocks it finds within the file system. If the counts do not agree, fsck replaces the count in the superblock with the actual free-block count.

Free Inodes

The summary information in the superblock contains a count of the free inodes within the file system. The fsck program compares this count to the number of free inodes it finds within the file system. If the counts do not agree, fsck replaces the count in the superblock with the actual free inode count.

Inodes

The list of inodes is checked sequentially starting with inode 2 (inode 0 and inode 1 are reserved). Each inode is checked for inconsistencies in:

• Format and type

• Link count

• Duplicate block

• Bad block numbers

• Inode size

Format and Type of Inodes

Each inode contains a mode word, which describes the type and state of the inode. Inodes may be one of six types:

• Regular

• Directory

• Block special

• Character special

• FIFO (named-pipe)

• Symbolic link

Inodes may be in one of three states:

• Allocated

• Unallocated

• Partially allocated

When the file system is created, a fixed number of inodes are set aside, but they are not allocated until they are needed. An allocated inode is one that points to a file. An unallocated inode does not point to a file and, therefore, should be empty. The partially allocated state means that the inode is incorrectly formatted. An inode can get into this state if, for example, bad data is written into the inode list because of a hardware failure. The only corrective action fsck can take is to clear the inode.

Link Count

Each inode contains a count of the number of directory entries linked to it. The fsck program verifies the link count of each inode by examining the entire directory structure, starting from the root directory, and calculating an actual link count for each inode.

Discrepancies between the link count stored in the inode and the actual link count as determined by fsck may be of three types:

• The stored count is not 0 and the actual count is 0.

  This condition can occur if no directory entry exists for the inode. In this case, fsck puts the disconnected file in the lost+found directory.

• The stored count is not 0 and the actual count is not 0, but the counts are unequal.

  This condition can occur if a directory entry has been added or removed but the inode has not been updated. In this case, fsck replaces the stored link count with the actual link count.

• The stored count is 0 and the actual count is not 0.

  In this case fsck changes the link count of the inode to the actual count.

Duplicate Blocks

Each inode contains a list, or pointers to lists (indirect blocks), of all the blocks claimed by the inode. Because indirect blocks are owned by an inode, inconsistencies in indirect blocks directly affect the inode that owns the indirect block.

The fsck program compares each block number claimed by an inode to a list of allocated blocks. If another inode already claims a block number, the block number is put on a list of duplicate blocks. Otherwise, the list of allocated blocks is updated to include the block number.

If there are any duplicate blocks, fsck makes a second pass of the inode list to find the other inode that claims each duplicate block. (A large number of duplicate blocks in an inode may be caused by an indirect block not being written to the file system.) It is not possible to determine with certainty which inode is in error. The fsck program prompts you to choose which inode should be kept and which should be cleared.

Bad Block Numbers

The fsck program checks each block number claimed by an inode to see that its value is higher than that of the first data block and lower than that of the last data block in the file system. If the block number is outside this range, it is considered a bad block number.

Bad block numbers in an inode may be caused by an indirect block not being written to the file system. The fsck program prompts you to clear the inode.

Inode Size

Each inode contains a count of the number of data blocks that it references. The number of actual data blocks is the sum of the allocated data blocks and the indirect blocks. fsck computes the number of data blocks and compares that block count against the number of blocks the inode claims. If an inode contains an incorrect count, fsck prompts you to fix it.

Each inode contains a 64-bit size field. This field shows the number of characters (data bytes) in the file associated with the inode. A rough check of the consistency of the size field of an inode is done by using the number of characters shown in the size field to calculate how many blocks should be associated with the inode, and then comparing that to the actual number of blocks claimed by the inode.

Indirect Blocks

Indirect blocks are owned by an inode. Therefore, inconsistencies in an indirect block affect the inode that owns it. Inconsistencies that can be checked are:

• Blocks already claimed by another inode

• Block numbers outside the range of the file system

The consistency checks are also performed for indirect blocks.

Data Blocks

An inode can directly or indirectly reference three kinds of data blocks. All referenced blocks must be of the same kind. The three types of data blocks are:

• Plain data blocks

• Symbolic-link data blocks

• Directory data blocks

Plain data blocks contain the information stored in a file. Symbolic-link data blocks contain the path name stored in a symbolic link. Directory data blocks contain directory entries. fsck can check the validity only of directory data blocks.

Directories are distinguished from regular files by an entry in the mode field of the inode. Data blocks associated with a directory contain the directory entries. Directory data blocks are checked for inconsistencies involving:

• Directory inode numbers pointing to unallocated inodes

• Directory inode numbers greater than the number of inodes in the file system

• Incorrect directory inode numbers for "." and ".." directories

• Directories disconnected from the file system

Directory Unallocated

If the inode number in a directory data block points to an unallocated inode, fsck removes the directory entry. This condition can occur if the data blocks containing the directory entries are modified and written out but the inode does not get written out. This condition can occur if the CPU is halted without warning.

Bad Inode Number

If a directory entry inode number points beyond the end of the inode list, fsck removes the directory entry. This condition can occur when bad data is written into a directory data block.

Incorrect "." and ".." Entries

The directory inode number entry for "." must be the first entry in the directory data block. It must reference itself; that is, its value must be equal to the inode number for the directory data block.

The directory inode number entry for ".." must be the second entry in the directory data block. Its value must be equal to the inode number of the parent directory (or the inode number of itself if the directory is the root directory).

If the directory inode numbers for "." and ".." are incorrect, fsck replaces them with the correct values. If there are multiple hard links to a directory, the first one found is considered the real parent to which ".." should point. In this case, fsck recommends you have it delete the other names.

Disconnected Directories

The fsck program checks the general connectivity of the file system. If a directory is found that is not linked to the file system, fsck links the directory to the lost+found directory of the file system. (This condition can occur when inodes are written to the file system but the corresponding directory data blocks are not.)

Regular Data Blocks

Data blocks associated with a regular file hold the contents of the file. fsck does not attempt to check the validity of the contents of a regular file's data blocks.

Modifying Automatic Boot Checking

During boot up, a preliminary check on each file system to be mounted from a hard disk is run using the boot script /sbin/rcS, which checks the root (/) and /usr file systems. The other rc shell scripts then use the fsck command to check each additional file system sequentially. They do not check file systems in parallel. File systems are checked sequentially during booting even if the fsck pass numbers are greater than one.

The /etc/vfstab File

When you run the commands for checking and mounting file systems without specifying a file system directly, the commands step through the file system table (/etc/vfstab) using the information specified in the various fields. The fsck pass field specifies information for file system checking. The mount at boot field specifies information for mounting the file system at boot time.

When you create new file systems, add entries to /etc/vfstab indicating whether they are to be checked and mounted at boot time. See Chapter 28, Mounting and Unmounting File Systems (Tasks) for more information about adding entries to the /etc/vfstab file.

Information in the /etc/vfstab file is specific for the slices and file systems for each system. Here is an example of an /etc/vfstab file:

$ more /etc/vfstab
#device         device          mount           FS      fsck    mount    mount
#to mount       to fsck         point           type    pass    at boot  options
#/dev/dsk/c1d0s2 /dev/rdsk/c1d0s2 /usr          ufs     1       yes     -
/proc           -               /proc           proc    -       no      -
fd              -               /dev/fd         fd      -       no      -
swap            -               /tmp            tmpfs   -       yes     -
 
/dev/dsk/c0t0d0s0 /dev/rdsk/c0t0d0s0 /          ufs     1       no      -
/dev/dsk/c0t0d0s1 -                  -          swap    -       no      -
/dev/dsk/c0t0d0s6 /dev/rdsk/c0t0d0s6 /usr       ufs     2       no      -
/dev/dsk/c0t0d0s7 /dev/rdsk/c0t0d0s7 /opt       ufs     3       yes     -
pluto:/export/svr4/man -    /usr/man        nfs     no      yes     -
$

Table 31-3 describes the function of the fsck pass field.

In preen mode, fsck allows only one active file system check per disk, starting a new check only after the previous one is completed. fsck automatically uses the major and minor numbers of the devices on which the file systems reside to determine how to check file systems on different disks at the same time.

When the fsck pass number is 1, file systems are checked sequentially, in the order they appear in the /etc/vfstab file. Usually, the root (/) file system has the fsck pass set to 1.

fsck does not use the fsck pass number to determine the sequence of file system checking.

How to Modify Automatic Checking Done During Booting

1. Become superuser.

2. Edit /etc/vfstab entries in the fsck pass field, and save the changes.

   The next time the system is booted, the new values are used.

Interactively Checking and Repairing a UFS File System

You may need to interactively check file systems:

• When they cannot be mounted

• When they develop problems while in use

When an in-use file system develops inconsistencies, error messages may be displayed in the console window or the system may crash.

Before using fsck, you may want to refer to "Syntax and Options for the fsck Command" and "Troubleshooting File System Problems" in System Administration Guide, Volume II for more information.

How to See If a File System Needs Checking

1. Become superuser.

2. Check the file system.

   # fsck -m /dev/rdsk/device-name

   In this command, the state flag in the superblock of the file system you specify is checked to see whether the file system is clean or requires checking.

   If you omit the device argument, all the UFS file systems listed in /etc/vfstab with a fsck pass value greater than 0 are checked.

Example--Seeing If a File System Needs Checking

The following example shows that the file system needs checking.

# fsck -m /dev/rdsk/c0t0d0s6
** /dev/rdsk/c0t0d0s6
ufs fsck: sanity check: /dev/rdsk/c0t0d0s6 needs checking

How to Check File Systems Interactively

1. Become superuser.

2. Unmount the local file systems except root (/) and /usr.

   # umountall -l

3. Check the file system.

   # fsck

   All file systems in the /etc/vfstab file with entries in the fsck pass field greater than zero are checked. You can also specify the mount point directory or /dev/rdsk/device-name as arguments to fsck. Any inconsistency messages are displayed. See "Troubleshooting File System Problems" in System Administration Guide, Volume II for information about how to respond to the error message prompts to interactively check one or more UFS file systems.

4. If you corrected any errors, type fsck and press Return.

   fsck may not be able to fix all errors in one execution. If you see the message FILE SYSTEM STATE NOT SET TO OKAY, run the command again. If that does not work, see "How to Fix a UFS File System fsck Cannot Repair".

5. Rename and move any files put in the lost+found directory.

   Individual files put in the lost+found directory by fsck are renamed with their inode numbers. If possible, rename the files and move them where they belong. You may be able to use the grep command to match phrases with individual files and the file command to identify file types. When whole directories are dumped into lost+found, it is easier to figure out where they belong and move them back.

Example--Checking File Systems Interactively

The following example checks /dev/rdsk/c0t0d0s6 and corrects the incorrect block count.

# fsck /dev/rdsk/c0t0d0s6
checkfilesys: /dev/rdsk/c0t0d0s6
** Phase 1 - Check Block and Sizes
INCORRECT BLOCK COUNT I=2529 (6 should be 2)
CORRECT? y
 
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Cylinder Groups
929 files, 8928 used, 2851 free (75 frags, 347 blocks, 0.6%
fragmentation)
/dev/rdsk/c0t0d0s6 FILE SYSTEM STATE SET TO OKAY
 
***** FILE SYSTEM WAS MODIFIED *****

Preening UFS File Systems

The preen option to fsck (fsck -o p) checks UFS file systems and automatically fixes the simple problems that normally result from an unexpected system halt. It exits immediately if it encounters a problem that requires operator intervention. The preen option also permits parallel checking of file systems.

You can run fsck with the -o p option to preen the file systems after an unclean halt. In this mode, fsck does not look at the clean flag and does a full check. These actions are a subset of the actions that fsck takes when it runs interactively.

How to Preen a File System

1. Become superuser.

2. Unmount the file system.

   # umount mount-point

3. Check a UFS file system with the preen option.

   # fsck -o p /dev/rdsk/device-name

   You can preen individual file systems by using mount-point or /dev/rdsk/device-name as arguments to fsck.

Example--Preening a File System

The following example preens the /usr file system.

# fsck -o p /usr

Restoring a Bad Superblock

When the superblock of a file system becomes damaged, you must restore it. fsck tells you when a superblock is bad. Fortunately, redundant copies of the superblock are stored within a file system. You can use fsck -o b to replace the superblock with one of the copies.

How to Restore a Bad Superblock

1. Become superuser.

2. Change to a directory outside the damaged file system.

3. Unmount the file system.

   # umount mount-point

   ---

   Caution -

   Be sure to use the -N option with newfs in the next step. If you omit the -N option, you will create a new, empty file system.

   ---

4. Display the superblock values with the newfs -N command.

   # newfs -N /dev/rdsk/device-name

   The output of this command displays the block numbers that were used for the superblock copies when newfs created the file system.

5. Provide an alternative superblock with the fsck command.

   # fsck -F ufs -o b=block-number /dev/rdsk/device-name

   fsck uses the alternative superblock you specify to restore the primary superblock. You can always try 32 as an alternative block, or use any of the alternative blocks shown by newfs -N.

Example--Restoring a Bad Superblock

The following example restores the superblock copy 5264 for the /files7 file system:

# cd /
# umount /files7
# newfs -N /dev/rdsk/c0t3d0s7
/dev/rdsk/c0t3d0s7: 163944 sectors in 506 cylinders of 9 tracks, 36 sectors
 83.9MB in 32 cyl groups (16 c/g, 2.65MB/g, 1216 i/g)
super-block backups (for fsck -b #) at:
 32, 5264, 10496, 15728, 20960, 26192, 31424, 36656, 41888,
 47120, 52352, 57584, 62816, 68048, 73280, 78512, 82976, 88208,
 93440, 98672, 103904, 109136, 114368, 119600, 124832, 130064, 135296,
 140528, 145760, 150992, 156224, 161456,
# fsck -F ufs -o b=5264 /dev/rdsk/c0t3d0s7
Alternate superblock location: 5264.
** /dev/rdsk/c0t3d0s7
** Last Mounted on
** Phase 1 - Check Blocks and Sizes
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Check Cyl groups
36 files, 867 used, 75712 free (16 frags, 9462 blocks, 0.0% fragmentation)
/dev/rdsk/c0t3d0s7 FILE SYSTEM STATE SET TO OKAY
 
***** FILE SYSTEM WAS MODIFIED *****
# 

If the superblock in the root (/) file system becomes damaged and you cannot boot the system, reinstall /kernel/unix and rebuild the root (/) file system with newfs. Because a superblock is created by the newfs command, you do not need to restore it.

How to Fix a UFS File System fsck Cannot Repair

Sometimes you need to run fsck a few times to fix a file system because problems corrected on one pass may uncover other problems not found in earlier passes. fsck does not keep running until it comes up clean, so you must rerun it manually.

Pay attention to the information displayed by fsck. It may help you fix the problem. For example, the messages may point to a bad directory. If you delete the directory, you may find that fsck runs cleanly.

If fsck still cannot repair the file system, you can try to use the fsdb, ff, clri, and ncheck commands to figure out and fix what is wrong. See fsdb(1M), ff(1M), clri(1M), and ncheck(1M) for information about how to use these commands. You may, ultimately, need to re-create the file system and restore its contents from backup media. See Chapter 35, Restoring Files and File Systems (Tasks) for information about restoring complete file systems.

If you cannot fully repair a file system but you can mount it read-only, try using cp, tar, or cpio to retrieve all or part of the data from the file system.

If hardware disk errors are causing the problem, you may need to reformat and divide the disk into slices again before re-creating and restoring file systems. Hardware errors usually display the same error again and again across different commands. The format command tries to work around bad blocks on the disk. If the disk is too severely damaged, however, the problems may persist, even after reformatting. See format(1M) for information about using the format command. See Chapter 23, SPARC: Adding a Disk (Tasks) or Chapter 24, x86: Adding a Disk (Tasks) for information about installing a new disk.

Syntax and Options for the fsck Command

The fsck command checks and repairs inconsistencies in file systems. It has four options:

• Checks only whether a file system can be mounted (fsck -m)

• Interactively asks for confirmation before making repairs (fsck)

• Assumes yes or no response for all repairs (fsck -y)

• Noninteractively preens the file system, fixing all expected (innocuous) inconsistencies, but exiting when a serious problem is encountered (fsck -o p)

Generic fsck Command Syntax, Options, and Arguments

The fsck command has two components: a generic component and a component specific to each type of file system. The generic commands apply to most types of file systems, while the specific commands apply to only one type of file system. You should always use the generic command, which calls the file system-specific command, as needed.

Usually, you must be superuser to run fsck. You can run the fsck command without being superuser; but to make repairs, you should unmount the file system and you must have read permission for the raw device file for the slice (a potential security hole).

The generic fsck command goes through /etc/vfstab to see what file systems to check. It runs the appropriate file system-specific fsck command on each file system listed, except those excluded by an fsck pass number of - or 0 (UFS only).

The generic fsck command has the following syntax:

/usr/sbin/fsck [-F type] [-V] [-m] [special]
/usr/sbin/fsck [-F type] [-V] -[y|Y]|[n|N] [-o specific-options][special]

Table 31-4 describes the options and arguments to the generic fsck command.

Chapter 32 File System Reference

This is a list of the reference information in this chapter.

• "Default Directories for root (/) and /usr File Systems"

• Table 32-2

• "The Structure of UFS File System Cylinder Groups"

• "Deciding on Custom File System Parameters"

• "Commands for Creating a Customized File System"

Default Directories for root (/) and /usr File Systems

Starting with the Solaris 2.5 release, kernel modules and commands that are platform dependent have moved to new locations. The /kernel directory now contains only platform-independent objects, including a platform-independent kernel, genunix. See Table 32-2 for a description of /platform and /usr/platform, the platform-dependent directories.

Table 32-1 describes all the directories contained in the default root (/) and /usr file systems.

The Platform-Dependent Directories

Table 32-2 describes the platform-dependent objects in the /platform and /usr/platform directories.

The Structure of UFS File System Cylinder Groups

When you create a UFS file system, the disk slice is divided into cylinder groups, which is made up of one or more consecutive disk sylinders. The cynlinder groups are then further divided into addressable blocks to control and organize the structure of the files within the cylinder group. Each type of block has a specific function in the file system. A UFS file system has these four types of blocks:

• Boot block - Used to store information used when booting the system

• Superblock - Used to store much of the information about the file system

• Inode - Used to store all information about a file except its name

• Storage or data block - Used to store data for each file

This section provides additional information about the organization and function of these blocks.

The Boot Block

The boot block stores the procedures used in booting the system. If a file system is not to be used for booting, the boot block is left blank. The boot block appears only in the first cylinder group (cylinder group 0) and is the first 8 Kbytes in a slice.

The Superblock

The superblock stores much of the information about the file system. A few of the more important things it contains are:

• Size and status of the file system

• Label (file system name and volume name)

• Size of the file system logical block

• Date and time of the last update

• Cylinder group size

• Number of data blocks in a cylinder group

• Summary data block

• File system state: clean, stable, or active

• Path name of the last mount point

The superblock is located at the beginning of the disk slice, and is replicated in each cylinder group. Because the superblock contains critical data, multiple superblocks are made when the file system is created. Each of the superblock replicas is offset by a different amount from the beginning of its cylinder group. For multiple-platter disk drives, the offsets are calculated so that a superblock appears on each platter of the drive. That way, if the first platter is lost, an alternate superblock can always be retrieved. Except for the leading blocks in the first cylinder group, the leading blocks created by the offsets are used for data storage.

A summary information block is kept with the superblock. It is not replicated, but is grouped with the first superblock, usually in cylinder group 0. The summary block records changes that take place as the file system is used, and lists the number of inodes, directories, fragments, and storage blocks within the file system.

Inodes

An inode contains all the information about a file except its name, which is kept in a directory. An inode is 128 bytes. The inode information is kept in the cylinder information block, and contains:

• The type of the file

  • Regular

  • Directory

  • Block special

  • Character special

  • Symbolic link

  • FIFO, also known as named pipe

  • Socket

• The mode of the file (the set of read-write-execute permissions)

• The number of hard links to the file

• The User ID of the owner of the file

• The Group ID to which the file belongs

• The number of bytes in the file

• An array of 15 disk-block addresses

• The date and time the file was last accessed

• The date and time the file was last modified

• The date and time the file was created

The array of 15 disk addresses (0 to 14) point to the data blocks that store the contents of the file. The first 12 are direct addresses; that is, they point directly to the first 12 logical storage blocks of the contents of the file. If the file is larger than 12 logical blocks, the 13th address points to an indirect block, which contains direct block addresses instead of file contents. The 14th address points to a double indirect block, which contains addresses of indirect blocks. The 15th address is for triple indirect addresses, if they are ever needed. Figure 32-1 shows this chaining of address blocks starting from the inode.

Figure 32-1 The File System Address Chain in a UFS System

Data Blocks

The rest of the space allocated to the file system is occupied by data blocks, also called storage blocks. The size of these data blocks is determined at the time a file system is created. Data blocks are allocated, by default, in two sizes: an 8-Kbyte logical block size, and a 1-Kbyte fragmentation size.

For a regular file, the data blocks contain the contents of the file. For a directory, the data blocks contain entries that give the inode number and the file name of the files in the directory.

Free Blocks

Blocks not currently being used as inodes, as indirect address blocks, or as storage blocks are marked as free in the cylinder group map. This map also keeps track of fragments to prevent fragmentation from degrading disk performance.

To give you an idea of the appearance of a typical UFS file system, Figure 32-2 shows a series of cylinder groups in a generic UFS file system.

Figure 32-2 A Typical UFS File System

Deciding on Custom File System Parameters

Before you choose to alter the default file system parameters assigned by the newfs command, you need to understand them. This section describes each of these parameters:

• Block size

• Fragment size

• Minimum free space

• Rotational delay

• Optimization type

• Number of files

Logical Block Size

The logical block size is the size of the blocks that the UNIX kernel uses to read or write files. The logical block size is usually different from the physical block size (usually 512 bytes), which is the size of the smallest block that the disk controller can read or write.

You can specify the logical block size of the file system. After the file system is created, you cannot change this parameter without rebuilding the file system. You can have file systems with different logical block sizes on the same disk.

By default, the logical block size is 8192 bytes (8 Kbytes) for UFS file systems. The UFS file system supports block sizes of 4096 or 8192 bytes (4 or 8 Kbytes). 8 Kbytes is the recommended logical block size.

To choose the best logical block size for your system, consider both the performance desired and the available space. For most UFS systems, an 8-Kbyte file system provides the best performance, offering a good balance between disk performance and use of space in primary memory and on disk.

As a general rule, to increase efficiency, use a larger logical block size for file systems where most of the files are very large. Use a smaller logical block size for file systems where most of the files are very small. You can use the quot -c file-system command on a file system to display a complete report on the distribution of files by block size.

Fragment Size

As files are created or expanded, they are allocated disk space in either full logical blocks or portions of logical blocks called fragments. When disk space is needed to hold a data for a file, full blocks are allocated first, and then one or more fragments of a block are allocated for the remainder. For small files, allocation begins with fragments.

The ability to allocate fragments of blocks to files, rather than just whole blocks, saves space by reducing fragmentation of disk space resulting from unused holes in blocks.

You define the fragment size when you create a UFS file system. The default fragment size is 1 Kbyte. Each block can be divided into 1, 2, 4, or 8 fragments, which results in fragment sizes from 8192 bytes to 512 bytes (for 4-Kbyte file systems only). The lower bound is actually tied to the disk sector size, typically 512 bytes.

The upper bound may equal the full block size, in which case the fragment is not a fragment at all. This configuration may be optimal for file systems with very large files when you are more concerned with speed than with space.

When choosing a fragment size, look at the trade-off between time and space: a small fragment size saves space, but requires more time to allocate. As a general rule, to increase storage efficiency, use a larger fragment size for file systems where most of the files are large. Use a smaller fragment size for file systems where most of the files are small.

Minimum Free Space

The minimum free space is the percentage of the total disk space held in reserve when you create the file system. The default reserve is ((64 Mbytes/partition size) * 100), rounded down to the nearest integer and limited between 1% and 10%, inclusively. Free space is important because file access becomes less and less efficient as a file system gets full. As long as there is an adequate amount of free space, UFS file systems operate efficiently. When a file system becomes full, using up the available user space, only root can access the reserved free space.

Commands such as df report the percentage of space that is available to users, excluding the percentage allocated as the minimum free space. When the command reports that more than 100 percent of the disk space in the file system is in use, some of the reserve has been used by root.

If you impose quotas on users, the amount of space available to the users does not include the free space reserve. You can change the value of the minimum free space for an existing file system by using the tunefs command.

Rotational Delay (Gap)

The rotational delay is the expected minimum time (in milliseconds) it takes the CPU to complete a data transfer and initiate a new data transfer on the same disk cylinder. The default delay depends on the type of the disk, and is usually optimized for each disk type.

When writing a file, the UFS allocation routines try to position new blocks on the same disk cylinder as the previous block in the same file. The allocation routines also try to optimally position new blocks within tracks to minimize the disk rotation needed to access them.

To position file blocks so they are "rotationally well-behaved," the allocation routines must know how fast the CPU can service transfers and how long it takes the disk to skip over a block. Using options to the mkfs command, you can indicate how fast the disk rotates and how many disk blocks (sectors) it has per track. The allocation routines use this information to figure out how many milliseconds it takes to skip a disk block. Then using the expected transfer time (rotational delay), the allocation routines can position or place blocks so that the next block is just coming under the disk head when the system is ready to read it.

It is not necessary to specify the rotational delay (-d option to newfs) for some devices.

Place blocks consecutively only if your system is fast enough to read them on the same disk rotation. If the system is too slow, the disk spins past the beginning of the next block in the file and must complete a full rotation before the block can be read, which takes a lot of time. You should try to specify an appropriate value for the gap so that the head is located over the appropriate block when the next disk request occurs.

You can change the value of this parameter for an existing file system by using the tunefs command. The change applies only to subsequent block allocation, not to blocks already allocated.

Optimization Type

The optimization type is either space or time.

• Space - When you select space optimization, disk blocks are allocated to minimize fragmentation and disk use is optimized.

• Time - When you select time optimization, disk blocks are allocated as quickly as possible, with less emphasis on their placement. When there is enough free space, it is relatively easy to allocate disk blocks effectively, without resulting in too much fragmentation. The default is time.

  You can change the value of the optimization type parameter for an existing file system using the tunefs command.

Number of Files

The number of inodes determines the number of files you can have in the file system: one inode for each file. The number of bytes per inode determines the total number of inodes created when the file system is made: the total size of the file system divided by the number of bytes per inode. Once the inodes are allocated, you cannot change the number without recreating the file system.

The default number of bytes per inode is 2048 bytes (2 Kbytes), which assumes the average size of each file is 2 Kbytes or greater. Most files are larger than 2 Kbytes. If you have a file system with many symbolic links, they can lower the average file size. If your file system is going to have many small files, you can give this parameter a lower value. Note, however, that having too many inodes is much better than running out of them. If you have too few inodes, you could reach the maximum number of files on a disk slice that is practically empty.

Commands for Creating a Customized File System

This section describes the two commands you use to create a customized file system:

• newfs

• mkfs

The newfs Command Syntax, Options, and Arguments

The newfs command is a friendlier version of the mkfs command that is used to create file systems. The newfs command is located in the /usr/sbin directory.

The syntax is:

newfs [-Nv] [mkfs_options] raw_device

Table 32-3 describes the options and arguments to the newfs command.