Mac OS X Server 1.x: Why, When, and How to Run fsck for File System Maintenance

The fsck utility is used to perform routine maintenance and recovery on a Mac OS X system hard disk that has either become unbootable or will not start to multi-user mode due to events or occurrences such as improper shutdown, forced restart, power outage, an accidentally disconnected power cord, and so forth.

There are several possible situations that may cause a Mac OS X system drive to fail to boot properly into the full Mach/BSD environment. Common causes of this issue include improper shutdown, power outage, pilot or visitor error such as kicking a power cord, UPS failure, improper use of front-panel buttons, or a full system disk. Yes, Mac OS X does permit the command-control-Power key restart, but don't do it!

Improper shutdown or a forced power cycle are always valid reasons to run the fsck utility to repair the system drive.

There are two environments from which fsck may be run. Normally, after an improper shutdown, workspace manager stops responding, or other untoward event, the system will do a partial boot, and pause in a command line environment following basic hardware initialization. Under these circumstances, there will usually be an error message, such as 'file system dirty, run fsck', followed by a new line with a # (pound-sign) prompt. In this event, fsck can be run directly, with no other maneuvering required.

In severe situations, the system information may be sufficiently unusable that the system will not get as far as the # prompt. Under these circumstances, it is necessary to boot from some other Unix-style system and manually specify the system drive as the target for fsck.

Usually, you'll know you need to do this, because when you started your system, it would only go as far as the single-user shell (the # <pound sign> prompt, as detailed above).

If the system realizes that the file system is dirty, there will be a message saying so, and what to do about it.

If the system doesn't boot up as far as the # prompt, then it will be necessary to start from some other volume, such as the Mac OS X Server Installer CD, in single-user mode. If this is your plight, skip down to the section "How To Run fsck From The Mac OS X Installer CD" below.

How To Run fsck From The Startup Disk

1. Using the System Disks application, select the Mac OS X Server partition of the hard disk as the boot device.

2. Check the "Show Diagnostic Info During Boot" option (this adds the -v flag to your Open Firmware boot command), and in the 'Other Options' field, add 's', for single-user mode. (Do not put quotes around the letter s in the 'Other Options' field.)
You may also click the 'Advanced Options' button and manually edit the boot command to read:
0 bootr -v -s
If you add the -s, it should be unnecessary to hold down the 's' key as described in Step 3.

3. Restart the system, holding down just the letter 's' to force single-user mode (if you didn't add it to the boot options).

4. Start (or restart) the machine in single-user mode. At the # prompt, type:
fsck -y
The fsck utility will go through five 'phases' and then return information about the disk's utilization and fragmentation. If the utility reports any errors or other conditions that it fixes or salvages, you must run it again until no errors are reported. This is because additional disk problem may be uncovered as a result of the first-pass repairs.

How To Run fsck From The Mac OS X Installer CD

Maintenance can be done on a Mac OS X formatted hard drive that won't start up by performing the following steps:

1. Boot system under Mac OS with the Mac OS X Installation CD in the CD-ROM drive. Booting from the CD is acceptable.

2. Using the System Disks application, select the Mac OS X Server partition of the Installation CD as the boot device.

3. Check the "Show Diagnostic Info During Boot" option (this adds the -v flag to your Open Firmware boot command), and in the 'Other Options' field, add 's' (for single-user mode).
Do not put quotes around the letter 's' in the 'Other Options' field.
You may also click the 'Advanced Options' button, click the checkbox to the right of "boot command" and manually edit the boot command so that it reads:
0 bootr -v -s
If you add the -s, it should be unnecessary to hold down the 's' key as described in Step 4.

4. Restart the system, holding down just the letter 's' to force single-user mode (if you didn't add it to the boot options).

5. The Mac OS X Server system should start up from CD, and after registering the attached hardware, will give a short warning and stop at the root # prompt. At the # prompt type:
fsck -y
The -y flag tells fsck that you want to answer 'yes' to all questions about fixing, repairing, or salvaging things. This is the right approach, as answering 'no' to any question will cause fsck to stop; you cannot determine that all necessary repairs have been made until fsck completes and gives its final report.
The fsck utility will go through five phases, and then return information about the disk's utilization and fragmentation. If the utility reports any errors or other conditions that it fixed or salvaged, you must run it again until no errors are reported. This is because occasionally an additional disk problem will be uncovered as a result of the first-pass repairs.

What To Do If fsck Doesn't Execute As Expected

There are two relatively common reasons why fsck might not run, even if you follow the above directions.

1. If fsck Cannot Determine The File System Type Of The Target Disk
The fsck utility may not be able to determine the filesystem type (UFS) if the directory structure is unusable, or if Mach/BSD isn't sure where the disk is located in your system.
Directory issues are not necessarily a big problem, as Mach/BSD maintains multiple copies on disk of critical directory information (called "mirrors" of the master superblocks. For more information, see the man pages for the 'disk' command by entering 'man disk' at the command line prompt, or in a terminal window.)
This sort of directory issue is most often encountered after a sudden loss of power, a front-panel or keyboard forced restart, or kicked power plug. Adding the -b16 flag, followed by an argument indicating a location of a superblock mirror, will probably do the trick. Try:
fsck -y -b16
where -y means "answer all the questions with 'yes'" and the -b16 indicates that fsck should use the superblock image at block 16.
Note that use of the -b flag will always modify the file system (because you have told it to do so by using a mirror of the master superblocks). Since fsck must be run repeatedly until the system appears to be clean and no repairs are made, using -b16 will always require at least one additional run of fsck, even if no repairs were made (other than moving in the mirror superblocks).

2. If fsck Says "Filesystem Clean; Skipping Checks"
If fsck returns a message such as "filesystem is clean; skipping checks", it isn't necessarily so. Most Unix-style systems can at times be shut down improperly in such a way that the file system may appear to be clean. If this happens (that is, you know the system was restarted or turned off improperly, or that there has been a power outage), you should force the fsck utility to run by adding the 'f' flag:
fsck -y -f

Other Possible Reasons fsck Might Not Run

Mach/BSD Doesn't Know Path To Device Driver

If for some reason Mach/BSD isn't sure on which drive the startup software resides, it may help to include the entire path to the command and to the target device driver:
/sbin/fsck -y /dev/hda0a
This is correct for an internal ATAPI drive 0, with the Mac OS X Server on the first partition.
/sbin/fsck -y /dev/sd1a
This is the syntax to designate a SCSI drive with ID=1.
At the # prompt (single-user command line mode), utilities and commands such as rm, mv, vi, cd, find, disk and so forth will run just fine, and won't need the full path; the startup drive may be assumed for some, such as fsck.

Master Superblocks Missing Or Unusable

If problems are encountered reading the master superblocks, the first alternate superblocks may be read instead, by adding the -b16 argument:
fsck -y -b16 /dev/hd0a
This can be useful if the system lost power when changed directory information was cached but not yet written back to disk before the system went down.

Run It Again, Sam

Note: If anything is altered, repaired or fixed during a file system check by the fsck utility, the message:
***** FILE SYSTEM WAS MODIFIED *****
will appear at the end of execution, just prior to a return to the root prompt (#). If this result occurs, it indicates that changes were made to the filesystem. It is important to run fsck again, until this message no longer appears. If the -b16 argument is used, this message will always appear, so by definition, if the -b16 argument is used, fsck must always be run again without the -b16 as a verification that all is well.

To Continue...

Once fsck runs without error, you may continue your use of the computer with one of the following commands:
exit (the single-user shell)
reboot (restarts and proceeds through a normal boot)
shutdown (powers the computer off)

Disk Too Full For Scratch Area

Note: If the system disk is full (showing no or very few free blocks) fsck may fail to run properly. If the disk really is full (full in this sense means less than 5% free disk space), you must mount the root file system by following the instructions printed just before the single-user prompt (#) is displayed:
/sbin/mount -uw /
and then use the 'rm' command to remove a few files to make a little space on the hard disk. Any core-dump files in /cores will be of substantial size, and if not needed for diagnostics are quite expendable. Careful consideration should be given as to which files are to be discarded, as there is no 'undelete' available in Unix-style operating systems.
rm /cores/[filename]
rm /Local/Users/[username]/Library/OmniWeb/Bookmarks.html
For more information on removal of files from command line, see the man pages on 'rm', rmdir', 'disk', and 'rmdir'.

Other Information About Most Commands Abounds In The man Pages

Man pages are available in single user mode only if the '/' file system is mounted, because the pages must be written to disk temporarily.
man rm
man rmdir
man fsck
man disk
Remember, viewing man pages in single-user mode requires that the root file system be mounted (see 'Disk Too Full...' above).