Ok, so this one did not take me hours, but I did have to go read a manual because no one seems to explain these settings – everyone just says “hey! these settings worked for me, plug em in.” That was my cue to try and understand it better.

Turns out that the Linux PAM system administrators guide was not really that bad and had some very useful explanations of how things work.

One thing I was looking to find out what the new bracket “[]” syntax for PAM config files works. Most admins will probably have seen this example somewhere:

auth [success=1 default=ignore] pam_ldap.so
auth required pam_unix.so try_first_pass
auth required pam_permit.so

What is up with those brackets? Turns out its pretty simple. According to the docs, the value=action control values are just a way of telling PAM what to do with the result of the rule (In this case, the rule is go check pam_unix.so and tell me what it said).

The value for the control can be set to any of the return values of the rule – success being rather obvious, default meaning anything that I didnt explicitly write. The action for the control can be ignore, bad, die, ok, done, reset or a number – the number just means skip the next N rules (the PAM SAG explains the config syntax fully).

In the above case, PAM is being instructed, in the common-auth config file to check LDAP first, ignore its failure if it cant find a username:password pair in the directory, or skip the next rule if it does find the pair. If it fails, it falls back to local accounts, if it succeeds iit jumps to the pam_permit.so rule which just permits anything it gets (keep in mind that if any required rule fails, the whole block fails, so thats why pam_permit.so cant permit something that pam_unix.so fails).

Thats it – pretty thought out by those clever PAM people. I hope I’ve explained it well enough here to help out. For a more in depth read, check out the Linux PAM system administrators guide.

My – aww man, do I really have to read this manual – pain, your gain.