I've been reading everything I can find on PAM (e.g. http://wpollock.com/AUnix2/PAM-Help.htm), however I'm still confused about how precisely the advanced options are supposed to work. For example, every reference says this:

Each of the four control-flag keywords (required, requisite, sufficient, and
optional) have an equivalent expression in terms of the [...] syntax:

    [success=ok new_authtok_reqd=ok ignore=ignore default=bad]

My understanding is that modules can return a variety of tokens, and that the action associated with each token is described in the configuration file. Based on that understanding, what does


have to do with the required control flag? What's the meaning/purpose of

ignore=ignore ?

This alone:


is what I would think matches the required behavior, but does


mean that if the module returns any other action token, the module fails? Is the action=value token success=ok overruled by default=bad, or vice versa? Which takes precendence? It's not clear from anything I've read.

More generally, suppose I have something like

[success=done default=die]

What happens if the module returns success and one other token?

Finally, I can't find the answer to this question, either: can every value ok, done, bad, die, ignore, reset, N be associated with any action? What would it even mean to say

[default=done] ?

2 Answers 2


PAM modules have over 30 different return values that are mapped to either pass or fail of the whole PAM stack as stated by the configuration.

It is noteworthy that a PAM module may behave different depending on the context (auth, account, password, session) that it is called in.

The pairs of value=action in square brackets describe which action to take for each possible return value of the PAM module.

A good explanation of values and actions can be found by carefully reading the above mentioned page to the end.

  • success=ok the module has returned success, this will be honored in the evaluation of the whole PAM stack, if no preceding module has failed, consider pass for the whole stack up to this point.
  • new_authtok_reqd=ok a new authentication token is required. E.g. in session context this might make the user change her/his password.
  • ignore=ignore the PAM module wants its result to be ignored, so we ignore it.
  • default=bad all other results make the PAM stack fail (but don't stop processing subsequent modules)

What happens if the module returns success and one other token?

PAM modules return only a single value.

Finally, I can't find the answer to this question, either: can every value ok, done, bad, die, ignore, reset, N be associated with any action? What would it even mean to say

[default=done] ?

This means: any token not mentioned here (i.e. every possible token) ends processing of the PAM stack and returns the result so far.

  • Thanks for your response. I'm still confused. success=ok gives a pass for the whole stack, default=bad gives a fail for the whole stack, but they're both listed in the same [ ] control value set. These seem like contradictory outcomes -- which one takes precedence? (not to mention ignore=ignore provides yet another contradictory outcome to the pass/fail question).
    – pgoetz
    Nov 14, 2014 at 16:23
  • The term success=ok sounds in fact a little misleading. It reads: the PAM module has returned success and the security policy of the system is set ok, accept this value. Like with the control-flag required is the overall result of the whole PAM stack only pass if all modules have returned success. default=bad within the same square brackets is not contradictory, it just says “consider every other return of the PAM module as bad”. An additional ignore=ignore means “if the PAM module wants to be ignored, ignore it”. Otherwise the PAM stack would return fail by default.
    – ua2b
    Nov 14, 2014 at 23:49

First of all, ua2b provided the critical answer which was causing my confusion:

PAM modules can only return a single status value per invocation

Since modules can only return one status code, it's clear that the action for any bracketed set of value/action pairs is unambiguous. I thought that a module could return several status codes at once (based on reading various documents), hence my confusion. It boggles my mind that no reference I could find, including the official documentation, is capable of stating this clearly. Instead, one finds comments like this :

"One or more status codes are returned by each PAM-API routine."

This to me sounds like a module can return several status codes. It was only after reading through the PAM module developer's guide that I realized that status codes are returned as a single integer which maps to the possible status code values as described here (Yes, the same reference!)

My next question had to do with equating the older style control flag keyword required with this square bracket syntax:

[success=ok new_authtok_reqd=ok ignore=ignore default=bad]

This equivalence is repeated all over the place, for example here.

It turns out that this is complete and utter nonsense. The status codes returned by any particular module can differ, and differ again depending on the management group type (e.g. auth vs. account).

Take for example, the pam_securetty module. This module only provides the auth type, and has the following possible status code return values:


The ignore=ignore value/action mapping consequently appears to be useless, as this module doesn't ever return ignore. In this case, you might want to consider using user_unknown=ignore if in fact you do want to ignore the outcome if the user can't be found.

  • How can I force PAM to return success? I disabled systemd-user-sessions.service, now I cant login, it says "system is booting up. see pam_nologin(8)". another weird things is that it seems to be no nologin file in /etc
    – yinon
    Jan 20, 2016 at 23:22
  • I ran across this while trying to get pam_pwdfile.so to only care about success, it turns out that auth_err isn't included in the 'default' list. Thus I had to be a lot more specific (giving success a number apparently causes skip, which is required if pam_deny.so is mid-stack): [success=3(NUMSKIP) new_authtok_reqd=done default=ignore auth_err=ignore authinfo_unavail=ignore user_unknown=ignore] Feb 19, 2019 at 18:42

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .