Project:PAM/Service files

Simple documentation about the format of PAM service configuration files.

Introduction
A PAM service configuration file is a simple ASCII text file installed in, describing the chain of modules to load and call to be able to fullfill one of four possible management facilities (account validation, authentication, password changing, and session handling). The comments, as often happens with Unix configuration files, are prefixed with a hash mark (#).

Every non-comment line of a PAM service file is composed of at least three elements: the management facility, the control directive and the parameter of this last one (always a module with the exclusion of the  directive, that instead takes another service name) following these three elements there are optional parameters to pass to the module (they are not supported for   ). When a single element needs to contain spaces, it can be quoted in between square parenthesis ( [ ] ), we'll see later where this is used.

The four facilities
The four management facilities are specified with a shortened version of their name: The order of each chain is related to the order in which the modules are listed in the configuration file; when you use the  directive, the lines declaring and configuring the modules for that facility are read from the specified service file and expanded in the place of the   line. The order of the four facilities is ignored, you can mix them.

The control directives
The control directives - beside, that as we have seen just loads the content of the homologous chain in another file - tell PAM what to do when the module fails or succeeds. This is important because you usually want to treat failures and successes of the modules in different ways depending on the chain and on the semantic of the module. The directives for this are: In addition to those, Linux-PAM also provides a more flexible way to define the behaviour of the modules, albeit quite more complex: you can decide what PAM will do in the various case (missing module, failure in loading the module, error in the call to the module's functions, failure of the implementation). To set this up, you need to pass a compless directive, quoted in square parenthesis ( [ ] ) as the second token of the line, and in it pass  couples, separated by commas, as needed. As this syntax is limited to Linux-PAM, and is usually more useful to advanced users than for default configurations, please refrain to use this syntax for the PAM service files installed by ebuilds.

Module name and parameters
The following token in the line is the module name; As modules are shared objects, they have the name. A common mistake is to use the full path of the module for this token; although this works on basic setups, it is suboptimal for multilib architectures (like AMD64), where it breaks for the non-default ABI. So please always use just the base name of the library.

After these three tokens, there are the parameters to pass to the modules. Each parameter is separated by whitespace, and as we said, if it contains spaces it should be quoted through square parenthesis ( [ ] ); this is the case for the SQL queries used together with the frontend modules for MySQL or PostgreSQL.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:
 * Diego Pettenò