Technical: Mac OS X Permissions Issues - ACL

Today I've spent much of the day cleaning up my computer (which had started stalling and doing other sorts of strange things indicating that it was unhappy). I sorted through all the files that had accumulated in random places during the made rush of first work and then traveling which left me with little time (and more importantly little emotional energy) for the process of sorting them. Then I attempted to back everything up.

This went well up until the time I attempted to made an image of my Documents folder. This is the place where I keep all of the important non-media (e.g., non-picture, song, or movie) files. I keep this in a separate hard-drive partition so I don't have to recopy it everytime I want to swap the OS in and out. However, it is important to keep at least one, preferably more backup copies of this very important directory kept elsewhere.

But here I ran into a problem. When using the Mac OS X Disk Utility program to make an image of the directory (from folder), I kept receiving errors along the line of "unable to create Documents: permission denied". Now this was quite irritating, so I went and checked the permissions on the directory. Permissions are essentially just a bunch of data about your file stored along with your file (metadata) that tell you what different groups of users are allowed or prohibited from doing with your files. User groups include: you, everyone, and custom groups of users that are more than yourself but less than everyone. Actions include things like reading, writing, and executing the contents of a file.

Being fairly familiar with permissions from over a decade of *nix experience, I expected to solve this quite easily but reseting everything to some reasonable default (e.g., chmod -R 770 Documents - which means me and other special folks can do everything and people who aren't us can't do anything) but strangely this didn't work. So I had to search.

What I found was that Mac OS X uses an extended permissions system called ACL, which in theory is probably really nice, but in practice seems to be mostly a pain-in-the-ass.

To explain: regular permissions look something like the below.
The first character lets you know of the file is special, e.g. d (a directory), l (a link), or - (normal).
The next 3 sets of three characters lets you know if the file is readable r, writeable w, and executable e, respectively. The first set is for the owner, the second for the group and the last for everyone (else).
drwx------ 4 reich staff 136 Apr 10 02:34 Desktop
The stuff on the line following this lets you know who the owner of the file is, the group of the file, it's name and other identifying info.
Here is a slightly more complicated entry for a symbolic link
lrwxr-xr-x 1 root staff 27 May 11 2008 Documents -> /Volumes/storage/Documents/

Not too complicated (although perhaps a bit daunting for the beginner), but in systems using ACL some entires might have a + symbol after the 10 character permissions string. This indicates that the file has extended ACL permissions as well. To actually see these permissions one types
ls -el
(technically only the e is need to see the ACL stuff, but I like to use l as well to get a more complete picture)
Here's an example of what you might see:
drwxr-xr-x@ 6 reich staff 204 Oct 7 2008 Movies
0: group:everyone deny delete
also you might notice that instead of the 11th character being a + it is a @.
This indicates that not only does this file use ACL, but its using some type of extended attributes thing. My suspicion is that the @ symbol doesn't necessarily imply the + symbol, but that when both apply the @ wins but I'm too lazy to find out right now.

Anyway it turns out for reasons I haven't bothered to discover that Mac OS X sometimes decides to do weird things to the file permissions - giving them special ACL-based restrictions - that cause the type of errors I experienced. So the quick solution is to kill all of these irritating ACL metadata (no guarantees that it won't cause your computer to explode, but I've not had any negative reactions from doing this)
Each ACL permission that is attached to your file will have a number indicating which rule it is.
All my problem have come from rules that look like
0: group:everyone deny delete
so you want to delete rules with these numbers (in this case rule 0)
chmod -R -a# 0 username
and after that things should be much more hunky dory.
Good luck!