Overview of UFS Logging

UFS file systems are checked at boot time because unscheduled system downtime can interrupt file system updates. These partially completed updates can leave inconsistences in a file system. Mounting a file system without first checking it and repairing any inconsistencies can cause panics or data corruption. Checking consistency for large file systems can be a time consuming process. With the UFS logging feature, file systems do not have to be checked at boot time because the changes from unfinished system calls are discarded.

A pseudo device, called the metatrans device, is responsible for managing the contents of the log. Like other metadevices, the metatrans device behaves the same as an ordinary disk partition. The metatrans device is made up of two subdevices: the logging device and the master device. These can be disk partitions, metadevices, or metamirrors, but not metatrans devices.

The logging device can be shared by several file systems. The logging device contains the log. This log is a sequence of records, each of which describes a change to a file system. The master device contains the file system itself. The master device can either contain a file system initially, or you can create a file system on the metatrans device. Logging begins automatically when the metatrans device is mounted.

Setting Up UFS Logging

You set up and configure a metatrans device using the standard DiskSuite utilities. The configuration of the device and other state information is stored in the metadevice state database. DiskSuite's dynamic concatenation facility provides dynamic concatenation of both the master and logging devices.

Metatrans devices can be defined either from the command line or in the /etc/opt/SUNWmd/md.tab file, and are given names such as /dev/md/dsk/d1. This is the same naming convention used for other metadevices.

After a metatrans device is configured, it can be used just as if it were a physical partition. This means it can be used as a device (up to one terabyte). A file system can be created on the metatrans device if the master device doesn't already have a file system. Most UNIX disk utilities will work normally on metatrans devices, with the exception of format(1M).

In addition, all usual file system operations can be performed on a metatrans device. The following list offers examples of file system operations:

• mount(1M) the metatrans device on a directory
• umount(1M) a mounted metatrans device
• Copy files to the metatrans device
• Read and write files from and to the metatrans device
• ufsdump(1M) and ufsrestore(1M) the metatrans device

The following sections provide answers to some of the questions you'll need to resolve before you begin setting up UFS logging on your system.

How Much Log Space is Required?

The minimum size for a logging device is 1 Mbyte of disk space. Larger logs allow for greater concurrency (more simultaneous file system operations per second). As a general rule, you need about 1Mbyte of log space for every 100 Mbyte of file system space being logged.

---

Note - Logs larger than 64 Mbyte are a waste of disk space.

---

Which File Systems Should Be Logged?

It is possible to log any UFS file system with the exception of root (/). The root file system cannot be a metatrans device. In addition, it is probably not necessary to log small file systems with mostly read activity.

---

Warning - When you are logging /usr, /var, /opt, or any other system file systems used during a Solaris upgrade/installation, logging must be disabled before you can perform a Solaris upgrade/installation.

---

In general, you will want to log your largest UFS file systems and the UFS file systems whose data is changed most frequently.

All logged file systems can share the same log. For performance considerations, however, the file systems with the heaviest loads should have separate logs.

---

Note - It is strongly recommended that you mirror all logs. Losing the data in a log to device errors can leave a file system in a corrupt state.

---

Where Should the Log Be Located?

Before you begin the procedures for setting up UFS logging, you should determine where you want to place the logs. You have two options for placement of logs:

• On unused partitions
• On the partitions containing the state databases

The second of these options can be a practical solution if you are unable to commit an unused partition to logging. See Chapter 8, "Disksets," for further information on using the state database with DiskSuite and Chapter 2, "Installation and Setup" for information on creating space for metadevice state database replicas.

How To Set Up UFS Logging

After you have determined which file systems you want to log and where the log will be located, follow the steps in this section to set up UFS logging.

There are two methods of defining a metatrans device:

• Edit the md.tab file to define the metatrans device, then run the metainit(1M)command; or
• Include the definition of the metatrans device on the command line with the metainit(1M)command.

For a complete discussion of the md.tab file, refer to Appendix A, "Solstice DiskSuite Files."

In the following example, the metatrans device is defined from the command line. For the purpose of this example, we'll assume that the partition you've selected for logging is /dev/dsk/c2t2d0s1 and you want to enable logging on /abcfs. Assume the /etc/vfstab entry for /abcfs is:

/dev/dsk/c0t2d0s6 /dev/rdsk/c0t2d0s6 /abcfs ufs 5 yes --

In this case, you would do the following to set up UFS logging on /abcfs:

1. As root, use the umount command to unmount /abcfs:

# umount /abcfs

2. Use the metainit command to create the metatrans device:

# metainit d64 -t c0t2d0s6 c2t2d0s1

This creates the metatrans device /dev/md/dsk/d64. This metatrans device is composed of the master device c0t2d0s6 and the logging device c2t2d0s1.

3. Edit the /etc/vfstab file to include the new metatrans device. In this case, you would change the line:

/dev/dsk/c0t2d0s6 /dev/rdsk/c0t2d0s6 /abcfs ufs 5 yes --

to read:

/dev/md/dsk/d64 /dev/md/rdsk/d64 /abcfs ufs 5 yes --

4. Use the mount command to mount /abcfs:

# mount /abcfs

/abcfs is now a logging file system. When you reboot the system, fsck will notice that this is a logging file system and will not check it. Instead, fsck will display:

/dev/md/rdsk/d64: is logging.

How to Share a Log Between File Systems

It may be practical in your situation to share a log among several or all file systems. This section provides the procedure for sharing a log between file systems.

In this example, we'll assume that you have set up /abcfs as described in the previous section and you want to set up /xyzfs to share the same log as /abcfs. Assume that the entry in the /etc/vfstab file for /xyzfs is:

/dev/dsk/c0t2d0s4 /dev/rdsk/c0t2d0s4 /xyzfs ufs 5 yes --

In this case, you would do the following to set up /xyzfs to share the same log with /abcfs:

1. Use the umount command to unmount /xyzfs.

# umount /xyzfs

2. Use the metainit command to create the metatrans device:

# metainit d63 -t c0t2d0s4 c2t2d0s1

This creates the metatrans device /dev/md/dsk/d63. This metatrans device is composed of the master device c0t2d0s4 and the now shared logging device c2t2d0s1.

3. Edit the /etc/vfstab file to include the new metatrans device. In this case, you would change the line:

/dev/dsk/c0t2d0s4 /dev/rdsk/c0t2d0s4 /xyzfs ufs 5 yes --

to read:

/dev/md/dsk/d63 /dev/md/rdsk/d63 /xyzfs ufs 5 yes --

4. Use the mount command to mount /xyzfs:

# mount /xyzfs

5. /xyzfs is now a logging file system. When you reboot the system, fsck will notice that /abcfs and /xyzfs are logging file systems and will not check them. Instead, fsck will display:

/dev/md/rdsk/d64: is logging. /dev/md/rdsk/d63: is logging.

Removing UFS Logging

If you decide you want to remove UFS logging from a particular file system, use the steps in this section to complete the procedure.

Assume that the current /etc/vfstab entry for /abcfs is as follows:

/dev/md/dsk/d64 /dev/md/rdsk/d64 /abcfs ufs 5 yes --

To remove UFS logging from /abcfs, you would do the following:

1. Use the umount command to unmount /abcfs:

# umount /abcfs

2. Use the metaclear command to clear the metatrans device:

# metaclear d64

This clears the metatrans device /dev/md/dsk/d64. Any information pertaining to the master device is rolled from the log prior to clearing the device.

3. Edit the /etc/vfstab file to remove the metatrans device information. In this case, you would change the line:

/dev/md/dsk/d64 /dev/md/rdsk/d64 /abcfs ufs 5 yes --

to read:

/dev/dsk/c0t2d0s6 /dev/rdsk/c0t2d0s6 /abcfs ufs 5 yes --

4. Because /abcfs is no longer a logging file system, you must run fsck before you can mount it. The following output is generated when you run fsck:

# fsck /dev/rdsk/c0t2d0s6 FILE SYSTEM STATE IN SUPERBLOCK IS WRONG; FIX? y

The correct response for this output is "y".

5. Mount /abcfs using the mount command:

# mount /abcfs

The /abcfs file system is no longer logging.

Logging a File System That Cannot Be Unmounted

You may want to log a file system that cannot be unmounted. An example of this is /usr.

Using the /abcfs example from the previous section on setting up logging, use the following procedure to set up logging on a file system that cannot be unmounted. In this example, we'll assume that /abcfs cannot be unmounted.

1. Use the metainit command to create the metatrans device:

# metainit d64 -t c0t2d0s6 c2t2d0s1

This creates the metatrans device /dev/md/dsk/d64. This metatrans device is composed of the master device c0t2d0s6 and the logging device c2t2d0s1.

2. Edit the /etc/vfstab file to include the new metatrans device. In this case, you would change the line:

/dev/dsk/c0t2d0s6 /dev/rdsk/c0t2d0s6 /abcfs ufs 5 yes --

to read:

/dev/md/dsk/d64 /dev/md/rdsk/d64 /abcfs ufs 5 yes --

3. Reboot the system.

   fsck will not notice that /abcfs is a logging file system until the system is rebooted again.

Removing Logging from a File System That Cannot be Unmounted

Using the /abcfs file system example from above, use the following procedure to remove logging on a file system that cannot be unmounted. Again in this example, we'll assume that /abcfs cannot be unmounted.

1. Use the metadetach command to detach the logging device:

# metadetach d64

2. Reboot the system

3. Edit the /etc/vfstab file to remove the metatrans device. In this case, you would change the line:

/dev/md/dsk/d64 /dev/md/rdsk/d64 /abcfs ufs 5 yes --

to read:

/dev/dsk/c0t2d0s6 /dev/rdsk/c0t2d0s6 /abcfs ufs 5 yes --

4. Reboot the system.

5. Use the metaclear command to clear the metatrans device:

# metaclear d64

This clears the metatrans device /dev/md/dsk/d64. Any information pertaining to the master device is rolled from the log prior to clearing the device.

Creating Metatrans Namespace for Exported File Systems

Even if you don't have a spare partition available for a logging device, you can still set up your metatrans devices without a logging device. This is a useful feature if you plan to enable logging on exported file systems, but do not have a spare partition available for the logging device.

To do this, you set up all the metatrans devices and then reboot your clients once. You have to reboot your clients because the device number changes when you convert the master device into a metatrans device. The changed device number results in ESTALE errors being returned to your clients when they attempt to reference files on the converted file system.

The following procedure creates a metatrans device without a logging device. For the purpose of this example, we'll assume the selected file system is /abcfs, the master device is /dev/dsk/c0t2d0s3, and the metatrans device is d64.

1. Unmount the selected file system:

# umount /abcfs

2. Use the metainit command to create the metatrans device:

# metainit d64 -t c0t2d0s3

3. Edit the /etc/vfstab file to include the new metatrans device. In this case, you would change the line:

/dev/dsk/c0t2d0s3 /dev/rdsk/c0t2d0s3 /abcfs ufs 5 yes --

to read:

/dev/md/dsk/d64 /dev/md/rdsk/d64 /abcfs ufs 5 yes --

4. Remount the file system:

# mount /abcfs

Left as is, the metatrans device you've created has no logging capabilities. You can add a logging device later using the metattach command when you have a spare partition.

How DiskSuite Commands Relate to Logging

After you have set up the UFS logging facility on your system, you'll notice some minor differences in how some of the DiskSuite commands function.

• metaclear rolls every applicable change from the log and to the master device before clearing the metatrans device.
• metastat reports the current status of the metatrans device, the status of the metatrans' master device, and the status of the metatrans' logging device.
• metainit creates metatrans devices when the -t option is used.
• metattach attaches a log to a metatrans device. If the metatrans device is mounted, the log is actually attached when the file system is unmounted or when the system is rebooted.
• metadetach removes a log from a metatrans device. If the metatrans device is mounted, the log is actually detached when the file system is unmounted or when the system is rebooted. All of the changes in the log for this master device are rolled forward before the log is detached.

For a complete description and the usage for each of these commands refer to Appendix E, "Using Solstice DiskSuite 4.0 with the SPARCstorage Array 100."

Using Metadevices and Metamirrors

A logging device and/or a master device can be a physical component or a metadevice. Physical components have been used as logging and master devices in the example procedures provided in this chapter. See Chapter 4, "Concatenating and Striping" and Chapter 5, "Mirroring" for examples of how to set up metadevices.

For the sake of reliability and availability, it is strongly recommended that you use metamirrors for logging devices. A device error on the logging device that is a physical component could cause a significant loss of the file system's data.

Using metadevices for logging or master devices can increase performance and provides you with more configuration options. For example, a striped logging or master device may improve performance. You might want to expand the master device and grow its file system while the metatrans device is still mounted and in use. You could also expand the logging device.

Even if you are unable to mirror the logging and master devices, it is recommended that you configure the logging and master devices as one-way mirrors.

In the example from the section, "How To Set Up UFS Logging" on page 112, in which the logging device was c2t2d0s1 and the master device was c0t2d0s6, we used the metainit command as follows:

# metainit d64 -t c0t2d0s6 c2t2d0s1

to create the metatrans device /dev/md/dsk/d64. If the logging device were the metamirror or metadevice /dev/md/dsk/d12, you would use the metainit command as follows:

# metainit d64 -t c0t2d0s6 d12

Likewise, if the master device were the metamirror or metadevice /dev/md/dsk/d5, the metainit command would be:

# metainit d64 -t d5 d12

See Chapter 5, "Mirroring" for information on how to create metamirrors.

Metatrans Device States

You can determine the state of a metatrans device or a logging device by running the metastat(1M) command. The following is a list of the possible states for metatrans and logging devices:

• Okay -- The device is functioning properly. If mounted, the file system is logging and will not be checked at boot.
• Hard Error -- A device error or file system panic has occured while the device was in use. An EIO is returned for every read or write until the device is closed or unmounted. The first open causes the device to transition to the Error state.
• Error -- The device can be read and written. The file system can be mounted read-only. However, an EIO is returned for every read or write that actually gets a device error. The device does not transition back to the Hard Error state, even when a later device error or file system panic occurs. Successfully completing fsck or newfs will transition the device into the Okay state. When the device is in the Hard Error or Error state, fsck automatically checks and repairs the file system at boot time. newfs will destroy whatever data may be on the device.
• Detached -- The metatrans device does not have a logging device. All benefits from UFS logging are disabled. fsck automatically checks the device at boot time. See the manual reference page for metadetach (1M) for complete information.
• Detaching -- The logging device will be detached from the metatrans device when the metatrans device is closed or unmounted. When this occurs, the device transitions to the Detached state. See the manual reference page for metadetach (1M) for complete information.
• Attaching -- The logging device will be attached to the metatrans device when the metatrans device is closed or unmounted. When this occurs, the device transitions to the Okay state. See the manual reference page for metattach (1M) for complete information.

Recovering from Device Errors

Device errors can cause data loss. Read errors occuring on a logging device can cause significant data loss. For this reason, it is strongly recommended that you mirror the logging device.

If a device error occurs on either the master device or the logging device while the metatrans device is processing logged data, the device will transition from the Okay state to the Hard Error state. If running the metastat (1M) command shows that the device is in the Hard Error or Error state, either a device error has occured or the file system has detected an error in its data and panic'ed. In either case, the recovery process is the same.

To transition the device back into the Okay state, use the following steps:

1. Unmount the affected file system.

   To determine the affected file system, run the lockfs (1M) command. lockfs will display the affected file system's lock type as hard.

   Every file system sharing the same logging device will be hard locked. You can unmount these file systems even if they were in use when the error occured. If the affected processes try to access an opened file or directory on the hard locked or unmounted file system, an EIO error will be returned.

2. Backup any accessable data.

   Before attempting to fix the device error, you may want to recover as much data as possible. If your backup procedure requires a mounted file system (such as tar or cpio), you can mount the file system read-only. If your backup procedure does not require a mounted file system (such as dump or volcopy), you can access the metatrans device directly.

3. Fix the device error.

   At this point, any attempt to open or mount the metatrans device for read/write access will start rolling all accessable data on the logging device to the appropriate master device(s). Any data that cannot be read or written is discarded. However, if you open or mount the the metatrans device for read-only access, the log is simply rescanned and not rolled forward to the master device(s). In other words, all of the data on the master and logging devices remains unchanged until the first read/write open or mount.

4. Repair the file system with fsck (1M) or newfs(1M). After successfully repairing the file system, fsck will automatically transition the file system back to the Okay state.

   The newfs command will also transition the file system back to the Okay state, but will destroy all of the data on the file system. newfs is generally used when you plan to restore file systems from backup.

---

Warning - newfs will destroy all existing files and directories currently on the file system.

---

---

Note - The fsck or newfs commands must be run on all of the metatrans devices sharing the same logging device before these devices revert back to the Okay state.

---

Recovering from File System Panics

If a file system detects any internal inconsistencies while it's in use, it will panic the system. If the file system is logging, it will notify the metatrans device that it needs to be checked at reboot. The metatrans device transitions itself to the Hard Error state. All other metatrans devices sharing the same logging device also go into the Hard Error state.

At reboot, fsck checks and repairs the file system and transitions the file system back to the Okay state. fsck does this for all metatrans devices listed in the vfstab file for the affected logging device.

If fsck cannot repair one of the file systems, then fsck must be run manually on each of the metatrans devices whose file systems were sharing the affected logging device. Only after all of the affected metatrans devices have been checked and successfully repaired will fsck reset the state of the errored metatrans device to Okay.