---
name: "pam.d"
section: "5"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/pam.conf/5"
---

# pam.d(5)

PAM policy file format

Part of [pam.conf(5)](/pam.conf/5.md).

## NAME

**pam.conf** – PAM policy file format

## DESCRIPTION

The PAM library searches for policies in the following files, in decreasing order of preference:

1. */etc/pam.d/**service-name*

2. */etc/pam.conf*

3. */usr/local/etc/pam.d/**service-name*

4. */usr/local/etc/pam.conf*

If none of these locations contains a policy for the given service, the “other” policy is used instead, if it exists.

Entries in per-service policy files must be of one of the two forms below:

```
[-]facility control-flag module-path [arguments ...]
[-]facility include other-service-name
```

Entries in *pam.conf*-style policy files are of the same form, but are prefixed by an additional field specifying the name of the service they apply to.

In both cases, blank lines and comments introduced by a ‘#’ sign are ignored, and the normal shell quoting rules apply. The precise details of how the file is tokenized are described in [openpam\_readword(3)](/openpam_readword/3.md).

The *facility* field specifies the facility the entry applies to, and is one of:

- **auth**

  Authentication functions( [pam\_authenticate(3)](/pam_authenticate/3.md), [pam\_setcred(3)](/pam_setcred/3.md))

- **account**

  Account management functions ([pam\_acct\_mgmt(3)](/pam_acct_mgmt/3.md))

- **session**

  Session handling functions( [pam\_open\_session(3)](/pam_open_session/3.md), [pam\_close\_session(3)](/pam_close_session/3.md))

- **password**

  Password management functions ([pam\_chauthtok(3)](/pam_chauthtok/3.md))

The *facility* field may optionally be preceded by a dash (‘-’), which indicates that failure to load the specified module (or policy if the *control-flag* *is* **include**) should not be considered a fatal error. This is intended for situations where it is desirable to share a single policy across multiple systems, but certain additional modules or policies may only be present on some of them.

The *control-flag* field determines how the result returned by the module affects the flow of control through (and the final result of) the rest of the chain, and is one of:

- **required**

  If this module succeeds, the result of the chain will be success unless a later module fails. If it fails, the rest of the chain still runs, but the final result will be failure regardless of the success of later modules.

- **requisite**

  If this module succeeds, the result of the chain will be success unless a later module fails. If the module fails, the chain is broken and the result is failure.

- **sufficient**

  If this module succeeds, the chain is broken and the result is success. If it fails, the rest of the chain still runs, but the final result will be failure unless a later module succeeds.

- **binding**

  If this module succeeds, the chain is broken and the result is success. If it fails, the rest of the chain still runs, but the final result will be failure regardless of the success of later modules.

- **optional**

  If this module succeeds, the result of the chain will be success unless a later module fails. If this module fails, the result of the chain will be failure unless a later module succeeds.

There are two exceptions to the above: **sufficient** and **binding** modules are treated as **optional** by [pam\_setcred(3)](/pam_setcred/3.md), and in the PAM\_PRELIM\_CHECK phase of [pam\_chauthtok(3)](/pam_chauthtok/3.md).

The *module-path* field specifies the name or full path of the module to call. If only the name is specified, the PAM library will search for it in the following locations:

1. */usr/lib*

2. */usr/local/lib*

The remaining fields, if any, are passed unmodified to the module if and when it is invoked.

The **include** form of entry causes entries from a different chain (specified by *other-system-name*) to be included in the current one. This allows one to define system-wide policies which are then included into service-specific policies. The system-wide policy can then be modified without having to also modify each and every service-specific policy.

Take care not to introduce loops when using **include** rules, as there is currently no loop detection in place.

## MODULE OPTIONS

Some PAM library functions may alter their behavior when called by a service module if certain module options were specified, regardless of whether the module itself accords them any importance. One such option is **debug**, which causes the dispatcher to enable debugging messages before calling each service function, and disable them afterwards (unless they were already enabled). Other special options include:

- **authtok\_prompt**=*prompt*, **oldauthtok\_prompt**=*prompt*, **user\_prompt**=*prompt*

  These options can be used to override the prompts used by [pam\_get\_authtok(3)](/pam_get_authtok/3.md) and [pam\_get\_user(3)](/pam_get_user/3.md).

- **echo\_pass**

  This option controls whether [pam\_get\_authtok(3)](/pam_get_authtok/3.md) will allow the user to see what they are typing.

- **try\_first\_pass**, **use\_first\_pass**

  These options control [pam\_get\_authtok(3)](/pam_get_authtok/3.md)'s use of cached authentication tokens.

## SEE ALSO

[pam(3)](/pam/3.md)

## STANDARDS

*X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules*, June 1997.

## AUTHORS

The OpenPAM library was developed for the FreeBSD Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS research program.

The OpenPAM library is maintained by Dag-Erling Smørgrav ⟨*des@des.dev*⟩.