Utility software

Repairing permissions: What you need to know

When it comes to Mac OS X troubleshooting and maintenance, Repairing permissions may be the most frequently recommended course of action. It’s also easily the most maligned.

The procedure has taken its (rightful) place in the Pantheon of Overused Procedures, next to “zapping the PRAM,” “rebuilding the Desktop,” and “performing a clean install,” with some users acting as if it’s a cure-all for any and every issue anyone might have with a Mac, and something that should be done every day to prevent problems from ever occurring. Conversely, a vocal camp claims that the procedure is worthless —even harmful—and that those who use it regularly are no better than tool-using primates on the evolutionary scale.

The truth about repairing permissions lies somewhere in between. We’re here to help you find it by taking a closer look at repairing permissions—what the function is, what it does, when you should do it, and when you shouldn’t.

What are permissions?

Every file and folder on a Mac OS X hard drive has a set of permissions —settings that determine which user(s) have access to each item, and exactly what that access is. For example, permissions dictate whether or not a particular user can open and edit a particular file. But permissions also determine which items the operating system—or specific parts of it—can access and modify, and which files are accessible by applications. (Brian Tanaka offers more details about various types of permissions in this excerpt from his Take Control of Permissions in Mac OS X ebook .)

What does repairing permissions do?

The Repair Disk Permissions function—the process that actually performs the task of repairing permissions—examines certain files and folders on your Mac’s hard drive to see if their current permissions settings are what Mac OS X expects them to be; if discrepancies are found, the offending permissions are changed to match the expected settings.

(In Mac OS X 10.3 and later, repairing permissions also performs one other, unrelated, task: If the invisible /tmp symbolic link—which is linked to the /private/tmp directory—is missing, the link will be recreated.)

Why is it necessary to repair permissions?

If permissions on particular files are “incorrect”—i.e., not what Mac OS X expects them to be or not what they need to be for your Mac’s normal operation—you can experience problems when the operating system tries to access or modify those files. For example, you may have trouble logging in to your account, printing, launching applications, or even starting up your Mac. Similarly, if an application—from Apple or a third-party developer—needs access to a particular file or folder to function, and the permissions on that item have changed in a way that prevents such access, the application may not function properly (or at all). The Repair Disk Permissions function can fix such problems by ensuring that certain files have the correct permissions.

There’s also a security element here: Many system-level files have permissions set a particular way so that applications or users that shouldn’t be meddling with those files can’t. If the permissions on certain system-level files somehow get changed so that access to those files is no longer restricted, you’ve got the potential for a major security issue. Repairing permissions can resolve such issues by resetting permissions on those files to prevent unauthorized access.

How do I repair permissions?

The Repair Disk Permissions function is part of Apple’s Disk Utility (in /Applications/Utilities). After launching Disk Utility, select the desired disk—generally your startup disk—in the list to the left, then click the First Aid tab. At the bottom of the First Aid panel, click the Repair Disk Permissions button. (You could instead use the Verify Disk Permissions option to preview any potential repairs before performing them, but for most users there’s little benefit from this extra step.)

Permissions can also be repaired via the shell (Terminal) by using the command

sudo diskutil repairPermissions /
. However, it’s unlikely that the typical user will ever need to perform the task in this manner. It’s useful if for some reason Disk Utility itself won’t launch, or for repairing permissions on a remote Mac when connected via Remote Login (SSH), but otherwise you’re just as well served using Disk Utility.

How does the Repair Disk Permissions function know what the “correct” permissions are?

When you use Apple’s Installer utility to install software (such as Mac OS X itself or an OS X update), the installation package (the .pkg file you double-click to begin installation, or that Software Update downloads in the background for an automatic installation) generally leaves behind a receipt —a smaller Mac OS X package that includes information about every file installed, including the permissions each file should have. This receipt is placed in /Library/Receipts. When you run the Repair Disk Permissions function, it examines the receipts in the /Library/Receipts directory of the disk being repaired —which means the feature works only on volumes with Mac OS X installed—and compares the information in the receipt with the actual files on your drive. If the Repair Disk Permissions function finds a file with permissions that differ from what a receipt claims they should be, that file’s permissions are reset to their receipt-specified values. (If you’re curious about the information contained in a receipt, the easiest way to view it is to use the utility Pacifist [   ; August 2006 ]; simply drag and drop the appropriate receipt into the Pacifist window and you’ll be presented with a list of all files installed by the similarly-named installation package, along with each file’s original permissions.)

It’s worth noting here that although the function is called “ Repair Disk Permissions,” what is actually happening is that files’ permissions are being reset or restored to a particular state. It’s possible—though not common—for a particular file’s permissions to differ from what a receipt claims they should be without those permissions actually being “broken.”

Are all files affected by Repair Disk Permissions?

No. As you may have inferred from the above description, only those files installed using OS X’s Installer utility and whose installation packages leave behind a proper receipt in /Library/Receipts are affected by the Repair Disk Permissions function. This means that most of the files affected by the Repair Disk Permissions function are system-level files, application files, or system add-ons—not applications installed by drag-and-drop, and not your documents or other user-level files. (See the next section for information about third-party software.)

But beyond that, only certain receipts are referenced, all of them associated with OS-X-related software. This limitation of the Repair Disk Permissions function has been debated around the Web, but you can confirm it yourself with a bit of Terminal savvy: By using the

fs_usage
command with the appropriate options, you can see exactly which receipt files are accessed when the Repair Disk Permissions function runs. The following is the list of such receipts on my Mac running Mac OS X 10.4:

  • AdditionalAsianFonts.pkg
  • AdditionalEssentials.pkg
  • AdditionalFonts.pkg
  • AddressBook.pkg
  • ApplicationsServer.pkg
  • Automator.pkg
  • BaseSystem.pkg
  • BrotherPrinterDrivers.pkg
  • BSD.pkg
  • BSDSDK.pkg
  • CanonPrinterDrivers.pkg
  • CommonAccessCard.pkg
  • CommonCriteriaTools.pkg
  • DevDocumentation.pkg
  • DeveloperTools.pkg
  • DevExamples.pkg
  • DevFatLibraries.pkg
  • DevInternal.pkg
  • DevSDK.pkg
  • ElectronicsForImagingPrinterDrivers.pkg
  • EpsonPrinterDrivers.pkg
  • Essentials.pkg
  • FatLibraries.pkg
  • GimpPrintPrinterDrivers.pkg
  • HewlettPackardPrinterDrivers.pkg
  • iCal.pkg
  • iChat.pkg
  • Internal.pkg
  • iTunes.pkg
  • Java.pkg
  • LexmarkPrinterDrivers.pkg
  • Mail.pkg
  • MicrosoftIE.pkg
  • MigrationAssistant.pkg
  • OxfordDictionaries.pkg
  • QuickTimeStreamingServer.pkg
  • RicohPrinterDrivers.pkg
  • Safari.pkg
  • ServerAdminTools.pkg
  • ServerEssentials.pkg
  • ServerFatLibraries.pkg
  • ServerInternal.pkg
  • ServerSetup.pkg
  • X11SDK.pkg
  • X11User.pkg
  • XeroxPrinterDrivers.pkg
  • These receipts are all from installations related to Mac OS X or Apple’s Xcode/Developer Tools. Given that files not listed in the above receipts won’t be affected by the Repair Disk Permissions function, this means that repairing permissions is mainly a tool for fixing permissions-related problems with OS-level Apple software .

    Why does the Repair Disk Permissions function look at only these receipts?

    These receipts are explicitly listed within the code of DiskManagementTool , the component of OS X that actually performs the task of repairing permissions. You can verify this by using the following command in Terminal:

    	
    strings /System/Library/PrivateFrameworks/DiskManagement.framework/Versions/A/Resources/DiskManagementTool | grep Receipts

    (I’ve placed the command in a scrolling box so it wouldn’t be broken incorrectly. The output from that command is a list of all receipts included in the code of DiskManagementTool.)

    Does repairing permissions affect third-party application files?

    Apple’s description of the Repair Disk Permissions function seems to imply that any software, including third-party software, installed using Installer and accompanied by a receipt in /Library/Receipts is affected by repairing permissions. However, we know from the previous answer that this isn’t the case. The only third-party software affected by repairing permissions is software included with Mac OS X and installed by the Mac OS X Installer; for example, the Flash browser plug-in (/Library/Internet Plug-Ins/flashplayer.xpt) and—in older versions of Mac OS X—Microsoft’s Internet Explorer browser.

    It’s easy to verify that third-party software isn’t affected. For example, I changed the permissions on the file NuFile.plugin , a third-party contextual menu plugin, from their original values. Since NuFile.plugin was installed using OS X’s Installer utility and a receipt, NuFileInstaller1-8.pkg , is present in /Library/Receipts, you might expect that the Repair Disk Permissions function would restore NuFile.plugin’s permissions to their original values. It doesn’t. I performed a similar test on the TiVoDesktop System Preferences pane with similar results.

    Although some might argue that restricting the Repair Disk Permissions function to Apple-installed software is a limitation, it’s also good security. If third-party receipts were used as references when repairing permissions, a piece of malware could leave behind a receipt designed to maliciously change permissions on system-level files—for example, to assign more-accessible permissions on normally secure files and directories. This could be a major security risk.

    That said, keep in mind that many third-party software products rely on components of Mac OS X. So although repairing permissions may not directly affect third-party software, if a permissions-related glitch with OS X’s own files is causing a problem with third-party software, the Repair Disk Permissions function could affect that software by fixing the underlying cause of the problem.

    Subscribe to the Help Desk Newsletter

    Comments