PIM

PIM

NAME

PIM - pluggable identification modules

SYNOPSIS

[u:|g:] [<options>] <plugin name> [<plugin arguments>]

DESCRIPTION

This manual page documents the PIM services configuration file format. General information about PIM is available in the section 7 of the manual.

OVERVIEW

A PIM service configuration file is a set of directives PIM will follow in turn when trying to perform an identification. Blank lines and lines whose first non blank character is a hash are ignored. Other lines are directives.

The format of such a directive is the following:

[u:|g:] [{<options>}] <plugin name> [<plugin arguments>]

If the line begins with u:, then the directive only applies to user management operations (getpwnam, getpwuid, getpwent, setpwent, endpwent calls). If it begins with g:, then the directive only applies to group management operations (getgrnam, getgrgid, getgrent, setgrent, endgrent calls). Otherwise, the directive applies to both types of operations.

Then, a comma separated list of options may be enclosed in brackets (see the OPTIONS section for a list of available options).

Then comes the plugin name. Currently, it is the path to the plugin .so file. It may be a complete path, otherwise, the file will be looked for in the plugins directory (/lib/pim), whose value may be specified in the PIM_MODULES environment variable. How the plugin performs its management operations depends exclusively on the module and is specified in its documentation.

At last, comes a module-specific arguments string, that will modify the module's behaviour.

PIM OPERATION

When performing an identification, PIM uses each directive in the order in which they appear in the configuration file. Whenever a plugin finds an entry for the requested item (username, user id, group name, or group id), PIM sends the result back to the application. If the plugin does not find the requested item, then the following plugin, as defined in the configuration file is called. If an errors occurs in a plugin, the lookup is immediately stopped.

This behaviour may be modified with the options field. Currently available options are:

• blacklist: if the requested item has been found by the plugin, act as if it hadn't;
• errorhandler: apply this directive only if one of the plugins already called during this lookup has raised an error, this option implies the safe option;
• mandatory: if the lookup does not succeed for this directive, or if an error occurs in the associated plugin, act as if no lookup had succeeded so far;
• mayfail: if an error occurs when applying this directive, still continue the lookup with further directives that use the safe option;
• overridable: if the lookup performed for this directive succeeds (which means a user or group entry has been found), don't return immediately, still perform other lookups, and override the current result with theirs when they succeed (or forget the current result when they succeed and are blacklisted); if the blacklist option is used in conjunction with overridable, and if the lookup succeeds, PIM acts as if it had failed and was not blacklisted;
• safe: if a preceding plugin call has raised an error, but the lookup still continues because the mayfail option was used, don't ignore this directive;
• weak: don't apply this directive if a preceding, non blacklisting lookup has succeeded.

AVAILABLE PIM MODULES

• pim_dumb_group: this module performs group identification and only knows about a single group. Its argument is a line that has the same format than a line in /etc/group.
• pim_dumb_user: this module performs user identification and only knows about a single user. Its argument is a line that has the same format than a line in /etc/passwd.
• pim_unix_group: this module provides group identification based on a traditionnal Unix /etc/group file. Its only argument is the path to the file.
• pim_unix_user: this module provides user identification based on a traditionnal Unix /etc/passwd file. Its only argument is the path to the file.
• pim_linux_nss: this module provides user and group identification based on NSS modules from the glibc Linux uses. It is able to call identification functions from these modules. This enables one to do with PIM whatever the NSS library is able to do. Its only argument is the path to the NSS module that has to be used (for instance, /usr/lib/libnss_files.so in order to use the traditionnal /etc/passwd and /etc/group files).

SECURITY CONSIDERATIONS

As in most cases, PIM services will be security sensitive, administrators should be aware that someone who is able to modify their configuration is in most cases able to compromise the system's security policy.

EXAMPLES

The following PIM service configuration file will provide the same functionality than traditional Unix systems (identification through /etc/passwd and /etc/group):

u: pim_unix_user /etc/passwd
g: pim_unix_group /etc/group

Lines may be added to this file, so that the root user will always be able to identify itself, and the wheel group will always exist, this yields:

u: {mayfail} pim_unix_user /etc/passwd
g: {mayfail} pim_unix_group /etc/group
u: {errorhandler} pim_dumb_user root:x:0:0:wheel:/root:/bin/sh
g: {errorhandler} pim_dumb_group wheel:x:0:

Or, one may want to override /etc/passwd settings for the foobar user, which yields:

u: {overridable} pim_unix_user /etc/passwd
u: pim_dumb_user foobar:x:12:42:foogroup:/foohome:/fooshell
g: pim_unix_group /etc/group

BUGS

The length of a line in the configuration files is currently limited to 8191 characters.

SEE ALSO

pim(7), pim(3)

AUTHOR

Brieuc "BBP" Jeunhomme (<bbp@via.ecp.fr>)