Home folder permissions repair in OS X

The home folder permissions in OS X are set up in such a way as to provide you access to your files, but only allow other users to see certain shared folders in your account. Every now and then people will come across situations where the home folder permissions are not working properly, and sometimes this can prevent them from logging in to their account and accessing files.

Unfortunately, running a permissions fix on the hard drive with Disk Utility will not check or fix the permissions of user accounts, and instead will only tackle faults with system file and application access.

If you are unable to log in to your account because of permissions problems (this can happen for various reasons including restoring from backup or migrating to a new computer), there is a simple procedure you can do to set the permissions on your account so you can access it. First, boot into Single User mode by restarting and holding the Command-S keys. This will drop you to the command prompt where you will have full "root" access to the system.

From here, run the following commands to set the desired account's files and folders to be accessible (change "username" in the command to the short name of the specified account):

1. Strip ACLs on all account items

   chmod -R -N /Users/username

   (optionally replace "-N" with "-E" in this command to "erase" ACL entries instead of remove them)

   Explanation: ACLs are "Access Control Lists", which are a more elaborate and thorough way of assigning permissions than the older POSIX permissions and may be appended to files and folders (sometimes inadvertently) by numerous programs and system commands. There are many configuration details to ACLs that are not directly editable in OS X, such as assigning unique permissions to more than one specific user without using groups, or even having multiple entries of different permissions for the same user. This can cause confusion and can prevent access to files even though they appear with proper permissions in the Finder. Because ACLs are not required for setting up the basic OS X account permissions and because they can actually prevent access to the account if set up incorrectly, you can remove them.

2. Change ownership and group on all items

   chown -R username:staff /Users/username

   Explanation: This step will ensure that all files in the home directory (/Users/username/), including the directory itself are "owned" by the account specified by the name "username." This will ensure that user has primary access to the files so permissions for that user are unique and are not included in those for a specific group or "everyone." All files in the user's account folder should be owned by that user. The group, denoted by ":staff" is set to "staff" here because this allows permissions to be set for administrators in the system (admins are members of the "staff" group); however, in this procedure setting the group will not affect much since we are going to be setting the group's permissions to "no access" in the next step.

3. Set read and write access to only the owner on all items

   chmod -R 600 /Users/username

   Explanation: This command is the "meat" of the procedure, and is what will actually change permissions. Once we've set up all files so permissions can be uniquely set for the specific account holder (the "owner"), this command will grant access to all files in the directory only to that owner, and set the files' group associations (the "group" and "everyone") to "no access". The "600" in the command is a bitwise designation of permissions to the file's "owner" (first digit, or "6" in this case), to the "group" (second digit, or "0" in this case), and to "everyone" (the third digit). The specific numbers will designate the permissions for those groups:

   0 = no access
   1 = execute only
   2 = write only
   3 = write and execute
   4 = read only
   5 = read and execute
   6 = read and write
   7 = read, write, and execute
   

   You can use alternate "symbolic" means for specifying permissions with chmod, and also use chmod to edit ACLs directly but this is beyond the scope of this tutorial. For more information on how to set permissions with "chmod" you can search for the command on Google or enter "man chmod" in the Terminal.

When these commands have been run, type "reboot" and press enter and the system will restart normally.

At this point, the owner for the account should be able to log in and be the only one with access to any files in the account. This includes those that could hold shared files and folders like Web sites or drop boxes; however, you should now be able to set read or write access to these items by using the Finder's "Get Info" window on items in the user's account.

Keep in mind this is a very rough way to grant access to the user's home directory and lock out other users from accessing it. It should not hurt the account to do this, but it may break some small features like shared folder setups that will have their own custom permissions. These will need to be set again, but can be done using the "Get Info" window on the specific folders in question.

If you can log in to your account but have a hard time accessing specific folders because of permissions problems, though the above procedure will work, a better alternative may be to use Apple's "Reset Home Folder Permissions" routine that is available on the OS X installation DVD, if one is available. Boot to the DVD and select your language, and then choose "Reset Password" from the "Utilities" menu. In this utility, you can reset the permissions on your home directory to be as they are on a default OS X installation--allowing the account owner full access and restricting other accounts to shared "Public" and Web-sharing folders.

Questions? Comments? Have a fix? Post them below or e-mail us!
Be sure to check us out on Twitter and the CNET Mac forums.