Troubleshooting Tools: AppleJack

Dan Frakes

Today marks the first installment of our monthly Troubleshooting Tools column, penned by MacFixIt Contributing Editor Dan Frakes. Each month, Dan will talk about one or two products that can help you maintain -- and, if necessary, fix -- your Mac.

For the most part, Mac OS X doesn't need a lot of day to day maintenance -- it crashes less than the "classic" Mac OS, and individual application problems are less likely to affect other applications and the operating system itself, so most users will find that serious file, drive, and directory damage are fairly rare. Granted, we've all heard nightmare stories from fellow users -- a month's worth of MacFixIt reader mail is sure to contain a few -- but the truth is that Mac OS X is, on the whole, pretty darned reliable.

That being said, don't forget Murphy's law -- eventually something will go wrong. When it does, you may as well be prepared, so it's a good idea to have the right tools handy and to polish up on your troubleshooting skills. You can kill a number of these birds with a single stone using the handy utility AppleJack.

But before I get to AppleJack itself, let's talk about some of the most important troubleshooting skills an informed user of Mac OS X can learn:

• How to repair your startup volume   If your startup volume is having problems, you may experience odd application or system behavior, problems starting up, or even data loss. You can verify your drive and, if necessary, repair many such problems using Disk Utility, included with Mac OS X. To repair the startup disk, you need to boot from another OS X volume or from your Mac OS X Install disc, launch Disk Utility, select your normal startup volume from the list of volumes, and then click the Repair Disk button. Alternatively, more experienced users know that you can perform the same repairs at startup via single-user mode, accessible by holding down Command S at startup until you see a Terminal-like, text-based prompt. Once the prompt appears, you type the appropriate command and let the command-line version of Disk Utility do its thing. (What's the command? It's actually provided on the screen, but read on -- you may not need it after finishing this article.)
• How to "repair" permissions   As a Unix-based operating system, system-level files and folders need to have the correct permissions or else problems can occur. If you're experiencing problems, you can use Disk Utility to verify and repair these system-level permissions: Just launch Disk Utility -- there's no need to reboot from another volume or the Install disc -- select your startup volume, and click the Repair Disk Permssions button. It's also possible to perform this function in single-user mode, but the process is a bit more complicated.
• Understanding preference and cache files   Applications, and Mac OS X itself, use preference files to store settings. Cache files are used by applications and the operating system to speed up processes that rely on frequently-access data; by storing such data in caches, the data can be accessed more quickly than the time it would take to find it again or generate it from scratch. However, because both preference files and cache files are accessed so frequently, they have a greater risk of becoming corrupt (due to a crash, for example), and corrupt preferences and cache files are common causes of problems. One of the first steps many troubleshooters take when experiencing issues is to delete cache files and/or to check preference files for damage using a tool such as Preferential Treatment.

These procedures aren't limited to reactive troubleshooting; many users like to perform them as proactive maintenance. For example, long-time readers know that MacFixIt generally recommends that you check your hard drive for problems before installing a major system update, and that afterwards you run Disk Utility's Repair Disk Permissions function.

Unfortunately, if you don't spend your days, like me, studying OS X and keeping track of obscure commands, remembering how to perform all of these tasks can be a pain. On top of that, if you don't have a second startup disk, or an OS X Install disc, on hand -- especially important if you're traveling with your PowerBook or iBook -- you may not be able to perform some of these tasks (which, if you're experiencing problems, could mean not being able to start up your computer at all). Many users have longed for an easier way to perform such maintenance and repairs -- or, at the very least, to consolidate them so they don't require so many different sequences and restarts.

An easier way?

Thankfully, there is an easier way: The "donationware" utility AppleJack. My colleague Ted Landau briefly mentioned AppleJack in a column last year, but it deserves a closer look.

AppleJack is a command-line utility that makes a number of troubleshooting procedures available via single-user mode at startup. And, perhaps more importantly to the typical user, it makes these procedures easy to perform. After installing AppleJack -- you should print out the ReadMe file during installation so you have a copy handy -- it simply becomes part of the single-user mode interface: In addition to the usual textual information on the screen, you'll also see the following:

For troubleshooting assistance, just type 'applejack' at the prompt

Type applejack and press return; after seeing some instructional and informational text, you're presented with the following:

Enter the associated number or letter to select the next task.
It is strongly recommended you do them in the order listed!

[a] auto pilot. Script will do all tasks in sequence.

[1] repair disks
[2] repair permissions
[3] cleanup cache files
[4] validate preferences files
[5] remove swap files

Your choice (Just hit return to quit):

As the text explains, you simply press the appropriate key (number or bolded letter) and press return to execute that task. Here's a quick summary of what these tasks do:

• repair disks   Running this task is equivalent to using the /sbin/fsck -yf command in single-user mode (which is the basically the same as running Disk Utility's Repair Disk function when booted from another volume or the Mac OS X Install disc). You'll see an onscreen report of the results of the process, including any repairs that were made. If repairs were made, you should run this task again, and repeat until no problems are found.
• repair permissions   This is the same as running Disk Utility's Repair Disk Permissions function. You'll see the same onscreen report of repairs as you would if you had used Disk Utility.
• cleanup cache files   This command deletes most of the contents of /Library/Caches. It also removes several cache-like files in /var/db, as well as the two kernel extension cache files in /System/Library. As theses tasks occur, a list of affected files is shown onscreen so you can see exactly what has been deleted. After this is finished, you're given the option to "clean" the cache files of a specific user account; this is a useful procedure if your Mac can boot fine but you're having problems with just a particular user account.
• validate preferences files   This tests the preferences files in /Library/Preferences for damage using the command-line utility plutil. If "bad" preferences are found, they're moved to a folder called Preferences (Corrupt) inside /Library; you can later inspect the moved files and decide what to do with them. You also have the option of examining the Preferences folder for any specific user. However, note that plutil isn't perfect -- it only checks to see if preferences files conform to two specific formats. If a developer uses a different format, plutil may think that the preferences file is bad and move it to the Corrupt folder even if it's really OK. So I personally only use this command if I suspect that a problem I'm having really is due to a corrupt preferences file; otherwise I skip it.
• remove swap files   This command removes the temporary virtual memory swap files created by Mac OS X. Note that these files should normally be removed automatically when you restart your Mac, but AppleJack makes sure.
• auto pilot   Automatically executes all five of the above tasks, in sequence. Although this can be helpful if you know you want to run all the tasks, one advantage to running them individually is that the options to check user-level items are only available in interactive (single-task) mode. (In addition, as I mentioned above, I prefer to skip the preferences file validation step.)

You can view AppleJack's log file at /var/log/AppleJack.log to check out the results of recent actions. You also have a few other options:

By typing applejack auto restart, AppleJack will perform the auto pilot sequence, automatically restarting when finished. Alternatively, typing applejack auto shutdown will shut down your Mac afterwards.

By typing applejack AUTO (note the all-caps) AppleJack will perform the auto pilot sequence using "deep cleaning" mode: During the cache cleaning step, it will delete all cache files, including the Launch Services database. You should use this option only if the standard mode doesn't fix a problem you're experiencing, as deleting the Launch Services cache files has two significant consequences: It resets any custom file associations (which applications open which files) you've configured; and it resets the security dialogs that pop up the first time you launch an application via double-clicking one of its documents.

Caveats

Because AppleJack is doing some serious things, a few caveats and warnings are in order:

• WARNING   Do not use AppleJack in Terminal when your Mac is started up normally; doing so will likely cause problems, up to and including a full system crash and possibly data loss. It's designed for use only in single-user mode at startup.
• As mentioned above, I recommend printing out the AppleJack ReadMe file during installation; it will come in handy if you ever need to use AppleJack at startup.
• If you're a "power user" who has moved their virtual memory swap files from the default location, be sure to read the AppleJack ReadMe for details on an extra step you need to take before using the "remove swap files" or "auto" functions.
• Although these processes can take a few minutes, you probably want to stick around and see them through, for both security and noise reasons. When booted into single-user mode, anyone can mount your hard drive and access files. (Granted, there are plenty of other security concerns if someone has physical access to your computer -- too many to get into here -- but why make it easier?) In addition, Mac OS X's fan management software isn't loaded in single-user mode, so on some Macs -- especially Power Mac G5 models -- your fans will start to ramp up to full, jet-engine levels. Although this isn't harmful -- your Mac is just ensuring that it doesn't overheat -- your coworkers or neighbors will likely appreciate the cacophony ending sooner rather than later.
• I've heard very few reports of problems with AppleJack, but those I have heard have almost all been from people who have enabled FileVault for their user account. The developers of AppleJack note that the current version (1.3.2) fixes these FileVault-related issues, but I recommend holding off using AppleJack with FileVault enabled until more reports come in.

Those caveats aside, AppleJack has become a utility I install on all of my Macs. It won't replace more advanced disk utilities such as DiskWarrior or TechTool Pro, but it makes it easy to perform most of the basic Mac OS X repair procedures without having to carry around an "emergency" disc or hard drive or having to remember various procedures and commands.

To provide feedback on this column, or to suggest utilities for future columns, drop Dan an email at his @MacFixIt.com address: dfrakes.

Resources