Troubleshooting permissions issues in Mac OS X
Learn about the concept of permissions (or "privileges") in Mac OS X, issues that can arise due to incorrect permissions settings, and how to troubleshoot them.
Mac OS installation/setup (any version)
Using the Repair Privileges Utility
Most users of Mac OS X have not intentionally modified privileges and simply need a utility to reset system privileges to their correct default values. If you have Mac OS X 10.2 and later, this utility is included in the operating system. If you have Mac OS X 10.1 you can download it. For versions 10.0 to 10.1.4, you must update to version 10.1.5 first.
For Mac OS X 10.2 or later, open Disk Utility (/Applications/Utilities/). Select your Mac OS X startup volume in the column on the left of the Disk Utility window, then click the First Aid tab. Click the Repair Disk Permissions button. You may see an erroneous message.
If you have modified the contents of the folder /Library/Receipts, the Repair Permissions feature won't work as expected. Repairing permissions requires receipts for Apple-installed software. Additionally, the utilities only repair Apple-installed software and folders (which does not include users' home folders).
For more information, see "About Disk Utility's Repair Disk Permissions feature (Mac OS X 10.2, 10.3)".
The remainder of this document contains more advanced information.
Note: In Mac OS X 10.5 and later, while started up ("booted") from the Mac OS X 10.5 installation disc, a user's home directory permissions can be reset using the Reset Password utility.
Warning: This document describes how you may modify permission settings by entering commands in the Terminal application. Users unfamiliar with Terminal and UNIX-style environments should proceed with caution. The entry of incorrect commands may result in data loss and/or unusable system software. Improper alteration of permissions can result in reduced system security and/or exposure of private data.
Mac OS X incorporates a subsystem based on a UNIX-style operating system that uses permissions in the file system. Every file and folder on your hard disk has an associated set of permissions that determines who can read, write to, or execute it. Using the AppleWorks application and one of its documents as an example, this is what the permissions mean:
- Read (r--)
You can open an AppleWorks document if you have the read permission for it.
- Write (-w-)
You can save changes to an AppleWorks document if you have the write permission for it.
- Execute (--x)
You can open the AppleWorks application if you have the execute permission for it.
Also note that you must have execute permission for any folder that you can open; thus File Sharing requires execute permission set for other, world, and everyone for the ~/Public folder, while Web Sharing requires the same setting for the ~/Sites folder.
When you can do all three, you have "rwx" permission. Permissions for a folder behave similarly. With read-only permission to a folder containing documents, you can open and read documents but not save changes or add new documents to the folder. Read-only (r--) permission is common for sharing files with guest access, for example.
Owner, Group, Others
Abbreviations like "rwx" and "r-x" describe the permission for one user or entity. The permissions set for each file or folder defines access for three entities: owner, group, and others.
- Owner - The owner is most often the user who created the file. Almost all files and folders in your home directory will have your username listed as the owner.
- Group - Admin users are members of the groups called "staff" and "admin". The super user "root" is a member of these and several other groups. Non-admin users are members of "staff" only. Typically, all files and folders are assigned to either "staff," "admin," or "wheel".
- Others - Others refers to all other users that are not the owner or part of the group for a file or folder.
Since each entity has its own permission, an example of a complete permission set could look like "-rwxrw-r--". The leading hyphen designates that the item is a file and not a folder. Folder privileges appear with leading "d," such as "drwxrw-r--". The "d" stands for directory, which is what a folder represents. Figure 2, below, depicts how this looks in the Terminal application.
Abbreviating permissions as numerals
After a while, you might think that "-rwxrwxr-x" is a lot to type. And you'd be right. That's why there's a simple way to abbreviate permissions as numerals, ranging from 777 (-rwxrwxrwx) down to 000 (no access). An "rwx" becomes a 7, the sum of 1, 2, and 4, where 4=Read, 2=Write, and 1=Execute. A zero means no access. Each of the three numerals is the sum of permissions for Owner, Group, and Other, respectively. Thus our example of "-rwxrwxr-x" becomes 775.
Example: Creating a TextEdit document
Suppose you create a TextEdit document and save it in the Documents folder of your home directory. The document has privileges of "-rw-r--r--", so you can read and write to the file; but the assigned group and any other users can only read it. Because you saved the file in your Documents folder (drwx------), the group and other users cannot even see your file. The enclosing folder's permissions effectively supersede the file's own permissions. This is how the home directory structure of Mac OS X provides privacy. If you drag the file to your Public folder (drwxr-xr-x) and log out, another user could log in to the computer and read your public file.
Default settings for new files and folders
- User is the user that creates the new file or folder.
- Group is default group of the user who created the file or folder.
- Folders or directories: drwxr-xr-x
- Files: -rw-r--r--
Root: The "Super User"
In Mac OS X, a super user named "root" is created at time of system installation. The root user has complete access to all files and folders on the computer, as well as additional administrative access that a normal user does not have. In normal day-to-day usage of your computer, you do not need to log in as the root user. In fact, the root user is disabled by default.
Issues Related to Permissions
Incorrect permission settings may cause unexpected behavior. Here are several examples with troubleshooting suggestions:
- Application installers, Applications folder
A third-party application installer incorrectly sets permissions on the files it installs, or even the entire Applications folder. Symptoms of the Application folder's permissions being set incorrectly include applications appearing in the dock as question marks, and/or not being able to connect to the Internet. It is also possible that software installed while logged in as one user will be inaccessible when logged in as another. To avoid this, make sure you are logged in with your normal user account when installing software that you wish to use with that account.
- Files created in Mac OS 9
Files created in Mac OS 9 may appear in Mac OS X with root ownership. When you start up in Mac OS 9 on a computer that also has Mac OS X installed, you can see, move, and delete all files, giving you the equivalent of root access. For this reason it's a good idea not to move or open unfamiliar files or folders when started up in Mac OS 9.
- Power interruption
The file system may be affected by a power interruption (improper shutdown) or when it stops responding (a "hang" or "freeze"). This could affect permissions. You may need to use fsck.
- Software access=user access
Most applications executed by a user only have access to the files that the user has access to. Backup software, for example, may not back up Mac OS X system files that have root ownership.
- Emptying the Trash
In some circumstances, folders for which you do not have write permission can end up in the Trash; and you will not be able to delete them or the files contained in them. Remember that in Mac OS X there is not a single Trash folder. Instead, each user has a Trash folder in their home directory (named ".Trash"). There is also a Trash folder for the startup volume, and Trash folders for other volumes or disks. When a user throws away a file on a local non-startup volume, the name of the folder on that volume is "/.Trashes/UID", where UID is the user ID number of the user (which may be seen in NetInfo Manager). In either case, all Trash folders are hidden from the user in the Finder. In these situations you can either start up into Mac OS 9 to locate the files and delete them, or you can use the Terminal application. Issues with emptying the Trash are much less likely to occur in Mac OS X 10.2 or later, since the Finder empties the Trash as the root user. However, issues may still occur with files on remote volumes for which your local root user has no special privileges.
Warning: Typographical error or misuse of the "rm -rf" command can result in data loss. Insertion of a space in the wrong place could result in the complete deletion of data on your hard disk, for example. You may wish to copy and paste the commands below into a text editor to verify spacing. Follow these steps to delete Trash for the logged-in user:
- Open the Terminal application.
- Type: sudo rm -rf
Note: Type a space after "-rf". The command does not work without the space. Do not press Return until Step 6.
- Open your Trash.
- Choose Select All from the Edit menu.
- Drag all of your Trash into the Terminal window. This causes the Terminal window to automatically fill in the name and location of each item in your Trash.
- Press Return.
All of the items in your Trash are deleted. As an alternative method, you may execute these commands. The second and third commands will delete Trash belonging to other users. The commands are:
Warning: Typographical error or misuse of the "rm -rf" command can result in data loss. Insertion of a space in the wrong place could result in the complete deletion of data on your hard disk, for example. You may wish to copy and paste the commands below into a text editor to verify spacing.
Important: There is no space between "/" and ".Trash" or ".Trashes" below.
sudo rm -rf ~/.Trash/
sudo rm -rf /.Trashes/
sudo rm -rf /Volumes/<volumename>/.Trashes/
Note: To end the sudo session, you should either execute the exit command, or log out of Mac OS X and then log back in.
Respectively, this permanently deletes all files in the current user's Trash, the startup volume Trash, and the Trash for other volumes (if any). These commands cannot delete locked files. You have to unlock them first.
Note: The sudo command can be used to temporarily obtain super user status and change permissions on files that otherwise could not be changed. However, it is only available if you are logged in with an administrator account, and it requires an administrator account user password for authentication.
How to View and Change Permissions in the Finder's Info Window
The Mac OS X Finder can be used to inspect and modify permissions settings for some files and folders. You can only change permissions for files and folders of which you are the owner. This can aid in troubleshooting permissions-related issues. To view and change permissions in the Info window, follow these steps:
- Select a file or folder in the Finder.
- From the File menu, choose Show.
- Choose Privileges from the pop-up menu in the Info window.
- Using the pop-up menus, change permissions settings as necessary (Figure 1).
- Optional: If you are changing permissions for a folder and you want the changes to apply to enclosed folders as well, click Apply. Apply only appears when you show info for folders.
Note: Changes made using the Info window take effect as soon as they are made, even before closing the window.
Figure 1 Privileges in the Info window
Viewing and Changing Permissions With Terminal
The Terminal application is located in the Utilities folder in the Applications folder. You can use Terminal to inspect or change permissions. Unlike the Finder's Info window, the sudo command gives you the convenience of root access without having to log out and back in as root.
Warning: Basic knowledge of the command line is required to utilize this tool. Data loss and/or unusable system software may result if the Terminal application is used improperly.
To determine the permissions settings for files or folders, open Terminal and navigate to the directory where the file or folder is located. Then execute the command "ls -l". The output resembles that in Figure 2.
Figure 2 Viewing permissions with Terminal
In the Figure 2 example, any user can read "File Name1.ext", because the read bit (r) is set for others. But the file is only changeable by root because the write bit (w) is only enabled for the owner, which is root. If the file is not a system file and you would like to be able to modify it from your normal account, you could change the owner with the following command:
sudo chown yourusername "File Name1.ext"
The file is owned by root, not by the user logged in, so the "sudo" command gives you temporary root access. Replace yourusername with your account's short name.
Space syntax: Be careful when typing spaces in file paths within the Terminal. In the example, the filename is enclosed in quotation marks because it contains a space. Alternatively, you can replace spaces with a backslash followed by a space. Without the quotation marks, the same command would be typed as:
sudo chown yourusername File\ Name1.ext
For more information on changing ownership, groups, and permissions, see the man (manual) pages for chown, chgrp, and chmod. You access man pages by executing "man <command_name>". For example:
By default, man pages are displayed one at a time. To read the next page, press the Space bar. To exit the man page, press Q.