The Linux-PAM System Administrators' Guide <author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt> <date>DRAFT v0.71 1999/11/8 <abstract> This manual documents what a system-administrator needs to know about the <bf>Linux-PAM</bf> library. It covers the correct syntax of the PAM configuration file and discusses strategies for maintaining a secure system. </abstract>  <toc>  <sect>Introduction <bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a suite of shared libraries that enable the local system administrator to choose how applications authenticate users. In other words, without (rewriting and) recompiling a PAM-aware application, it is possible to switch between the authentication mechanism(s) it uses. Indeed, one may entirely upgrade the local authentication system without touching the applications themselves. Historically an application that has required a given user to be authenticated, has had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character ``salt'', is encrypted (with crypt(3)). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the <tt>/etc/passwd</tt> file). On such systems, most if not all forms of privileges are granted based on this single authentication scheme. Privilege comes in the form of a personal user-identifier (<tt/uid/) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the <tt>/etc/group</tt> file. Unfortunately, increases in the speed of computers and the widespread introduction of network based computing, have made once secure authentication mechanisms, such as this, vulnerable to attack. In the light of such realities, new methods of authentication are continuously being developed. It is the purpose of the <bf/Linux-PAM/ project to separate the development of privilege granting software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a system file, <tt>/etc/pam.conf</tt> (or a series of configuration files located in <tt>/etc/pam.d/</tt>) to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory <tt>/usr/lib/security</tt> and take the form of dynamically loadable object files (see <tt/dlopen(3)/). <sect>Some comments on the text<label id="text-conventions"> Before proceeding to read the rest of this document, it should be noted that the text assumes that certain files are placed in certain directories. Where they have been specified, the conventions we adopt here for locating these files are those of the relevant RFC (RFC-86.0, see <ref id="see-also-sec" name="bibliography">). If you are using a distribution of Linux (or some other operating system) that supports PAM but chooses to distribute these files in a diferent way (Red Hat is one such distribution), you should be careful when copying examples directly from the text. As an example of the above, where it is explicit, the text assumes that PAM loadable object files (the <em/modules/) are to be located in the following directory: <tt>/usr/lib/security/</tt>. However, Red Hat Linux, in agreement with the Linux File System Standard (the FSSTND), places these files in <tt>/lib/security</tt>. Please be careful to perform the necessary transcription when using the examples from the text. <sect>Overview<label id="overview-section"> For the uninitiated, we begin by considering an example. We take an application that grants some service to users; <em/login/ is one such program. <em/Login/ does two things, it first establishes that the requesting user is whom they claim to be and second provides them with the requested service: in the case of <em/login/ the service is a command shell (bash, tcsh, zsh, etc.) running with the identity of the user. Traditinally, the former step is achieved by the <em/login/ application prompting the user for a password and then verifying that it agrees with that located on the system; hence verifying that the so far as the system is concerned the user is who they claim to be. This is the task that is delegated to <bf/Linux-PAM/. From the perspective of the application programmer (in this case the person that wrote the <em/login/ application), <bf/Linux-PAM/ takes care of this authentication task -- verifying the identity of the user. The flexibility of <bf/Linux-PAM/ is that <em/you/, the system administrator, have the freedom to stipulate which authentication scheme is to be used. You have the freedom to set the scheme for any/all PAM-aware applications on your Linux system. That is, you can authenticate from anything as naive as <em/simple trust/ (<tt/pam_permit/) to something as paranoid as a combination of a retinal scan, a voice print and a one-time password! To illustrate the flexibility you face, consider the following situation: a system administrator (parent) wishes to improve the mathematical ability of her users (children). She can configure their favorite ``Shoot 'em up game'' (PAM-aware of course) to authenticate them with a request for the product of a couple of random numbers less than 12. It is clear that if the game is any good they will soon learn their <em/multiplication tables/. As they mature, the authentication can be upgraded to include (long) division! <bf/Linux-PAM/ deals with four separate types of (management) task. These are: <em/authentication management/; <em/account management/; <em/session management/; and <em/password management/. The association of the preferred management scheme with the behavior of an application is made with entries in the relevant <bf/Linux-PAM/ configuration file. The management functions are performed by <em/modules/ specified in the configuration file. The syntax for this file is discussed in the section <ref id="configuration" name="below">. Here is a figure that describes the overall organization of <bf/Linux-PAM/. <tscreen> <verb> +----------------+ | application: X | +----------------+ / +----------+ +================+ | authentication-[---->--\--] Linux- |--<--| PAM config file| | + [----<--/--] PAM | |================| |[conversation()][--+ \ | | | X auth .. a.so | +----------------+ | / +-n--n-----+ | X auth .. b.so | | | | __| | | _____/ | service user | A | | |____,-----' | | | V A +----------------+ +------|-----|---------+ -----+------+ +---u-----u----+ | | | | auth.... |--[ a ]--[ b ]--[ c ] +--------------+ | acct.... |--[ b ]--[ d ] +--------------+ | password |--[ b ]--[ c ] +--------------+ | session |--[ e ]--[ c ] +--------------+ </verb> </tscreen> By way of explanation, the left of the figure represents the application; application X. Such an application interfaces with the <bf/Linux-PAM/ library and knows none of the specifics of its configured authentication method. The <bf/Linux-PAM/ library (in the center) consults the contents of the PAM configuration file and loads the modules that are appropriate for application-X. These modules fall into one of four management groups (lower-center) and are stacked in the order they appear in the configuaration file. These modules, when called by <bf/Linux-PAM/, perform the various authentication tasks for the application. Textual information, required from/or offered to the user, can be exchanged through the use of the application-supplied <em/conversation/ function. <sect1>Getting started The following text was contributed by Seth Chaiklin: <tscreen> <verb> To this point, we have described how PAM should work in an ideal world, in which all applications are coded properly. However, at the present time (October 1998), this is far from the case. Therefore, here are some practical considerations in trying to use PAM in your system. Why bother, is it really worth all the trouble? If you running Linux as a single user system, or in an environment where all the users are trusted, then there is no real advantage for using PAM. </verb> </tscreen> <BF>Ed:</BF> there is actually an advantage since you can <em/dummy down/ the authentication to the point where you don't have any... Almost like Win95. In a networked environment, it is clear that you need to think a little more about how users etc., are authenticated:] <tscreen> <verb> If you are running Linux as a server, where several different services are being provided (e.g., WWW with areas restricted by password control, PPP), then there can be some real and interesting value for PAM. In particular, through the use of modules, PAM can enable a program to search through several different password databases, even if that program is not explicitly coded for that particular database. Here are some examples of the possibilities that this enables. o Apache has a module that provides PAM services. Now authentication to use particular directories can be conducted by PAM, which means that the range of modules that are available to PAM can be used, including RADIUS, NIS, NCP (which means that Novell password databases can be used). o pppd has a PAMified version (available from RedHat) Now it is possible to use a series of databases to authenticate ppp users. In addition to the normal Linux-based password databases (such as /etc/passwd and /etc/shadow), you can use PAM modules to authenticate against Novell password databases or NT-based password databases. o The preceding two examples can be combined. Imagaine that the persons in your office/department are already registered with a username and password in a Novell or NT LAN. If you wanted to use this database on your Linux server (for PPP access, for web access, or even for normal shell access), you can use PAM to authenticate against this existing database, rather than maintain a separate database on both Linux and the LAN server. Can I use PAM for any program that requires authentication? Yes and no. Yes, if you have access to the source code, and can add the appropriate PAM functions. No, if you do not have access to the source code, and the binary does not have the PAM functions included. In other words, if a program is going to use PAM, then it has to have PAM functions explicitly coded into the program. If they are not, then it is not possible to use PAM. How can I tell whether a program has PAM coded into it or not? A quick-and-dirty (but not always reliable) method is to ldd <programname> If libpam and libpam_misc are not among the libraries that the program uses, then it is not going to work with PAM. However, it is possible that the libraries are included, but there are still problems, because the PAM coding in the program does not work as it should. So a more reliable method is to make the follow tests. In the /etc/pam.d directory, one needs to make a configuration file for the program that one wants to run. The exact name of the configuration file is hard-coded into the program. Usually, it is the same name as the program, but not always. For sake of illustration, let's assume that the program is named "pamprog" and the name of the configuration file is /etc/pam.d/pamprog. In the /etc/pam.d/pamprog put the following two lines: auth required pam_permit.so auth required pam_warn.so Now try to use pamprog. The first line in the configuration file says that all users are permitted. The second line will write a warning to your syslog file (depending on whether your syslog is writing messages). If this test succeeds, then you know that you have a program that can understand pam, and you can start the more interesting work of deciding how to stack modules in your /etc/pam.d/pamprog file. </verb> </tscreen> <sect>The Linux-PAM configuration file <label id="configuration"> <bf/Linux-PAM/ is designed to provide the system administrator with a great deal of flexibility in configuring the privilege granting applications of their system. The local configuration of those aspects of system security controlled by <tt/Linux-PAM/ is contained in one of two places: either the single system file, <tt>/etc/pam.conf</tt>; or the <tt>/etc/pam.d/</tt> directory. In this section we discuss the correct syntax of and generic options respected by entries to these files. <sect1>Configuration file syntax The reader should note that the <bf/Linux-PAM/ specific tokens in this file are case <em/insensitive/. The module paths, however, are case sensitive since they indicate a file's <em/name/ and reflect the case dependence of typical Linux file-systems. The case-sensitivity of the arguments to any given module is defined for each module in turn. In addition to the lines described below, there are two <em/special/ characters provided for the convenience of the system administrator: comments are preceded by a `<tt/#/' and extend to the next end-of-line; also, module specification lines may be extended with a `<tt/\/' escaped newline. A general configuration line of the <tt>/etc/pam.conf</tt> file has the following form: <tscreen> <verb> service-name module-type control-flag module-path arguments </verb> </tscreen> Below, we explain the meaning of each of these tokens. The second (and more recently adopted) way of configuring <bf/Linux-PAM/ is via the contents of the <tt>/etc/pam.d/</tt> directory. Once we have explained the meaning of the above tokens, we will describe this method. <descrip> <tag><tt/service-name/</tag> The name of the service associated with this entry. Frequently the service name is the conventional name of the given application. For example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ . There is a special <tt/service-name/, reserved for defining a default authentication mechanism. It has the name `<tt/OTHER/' and may be specified in either lower or upper case characters. Note, when there is a module specified for a named service, the `<tt/OTHER/' entries are ignored. <tag><tt/module-type/</tag> One of (currently) four types of module. The four types are as follows: <itemize> <item> <tt/auth/; this module type provides two aspects of authenticating the user. Firstly, it establishes that the user is who they claim to be, by instructing the application to prompt the user for a password or other means of identification. Secondly, the module can grant <tt/group/ membership (independently of the <tt>/etc/groups</tt> file discussed above) or other privileges through its <em/credential/ granting properties. <item> <tt/account/; this module performs non-authentication based account management. It is typically used to restrict/permit access to a service based on the time of day, currently available system resources (maximum number of users) or perhaps the location of the applicant user---`<tt/root/' login only on the console. <item> <tt/session/; primarily, this module is associated with doing things that need to be done for the user before/after they can be given service. Such things include the logging of information concerning the opening/closing of some data exchange with a user, mounting directories, etc. . <item> <tt/password/; this last module type is required for updating the authentication token associated with the user. Typically, there is one module for each `challenge/response' based authentication (<tt/auth/) module-type. </itemize> <tag><tt/control-flag/</tag> The control-flag is used to indicate how the PAM library will react to the success or failure of the module it is associated with. Since modules can be <em/stacked/ (modules of the same type execute in series, one after another), the control-flags determine the relative importance of each module. The application is not made aware of the individual success or failure of modules listed in the `<tt>/etc/pam.conf</tt>' file. Instead, it receives a summary <em/success/ or <em/fail/ response from the <bf/Linux-PAM/ library. The order of execution of these modules is that of the entries in the <tt>/etc/pam.conf</tt> file; earlier entries are executed before later ones. As of Linux-PAM v0.60, this <em/control-flag/ can be defined with one of two syntaxes. The simpler (and historical) syntax for the control-flag is a single keyword defined to indicate the severity of concern associated with the success or failure of a specific module. There are four such keywords: <tt/required/, <tt/requisite/, <tt/sufficient/ and <tt/optional/. The Linux-PAM library interprets these keywords in the following manner: <itemize> <item> <tt/required/; this indicates that the success of the module is required for the <tt/module-type/ facility to succeed. Failure of this module will not be apparent to the user until all of the remaining modules (of the same <tt/module-type/) have been executed. <item> <tt/requisite/; like <tt/required/, however, in the case that such a module returns a failure, control is directly returned to the application. The return value is that associated with the <em/first/ <tt/required/ or <tt/requisite/ module to fail. Note, this flag can be used to protect against the possibility of a user getting the opportunity to enter a password over an unsafe medium. It is conceivable that such behavior might inform an attacker of valid accounts on a system. This possibility should be weighed against the not insignificant concerns of exposing a sensitive password in a hostile environment. <item> <tt/sufficient/; the success of this module is deemed `<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this module-type has succeeded in its purpose. In the event that no previous <tt/required/ module has failed, no more `<em/stacked/' modules of this type are invoked. (Note, in this case subsequent <tt/required/ modules are <bf/not/ invoked.). A failure of this module is not deemed as fatal to satisfying the application that this <tt/module-type/ has succeeded. <item> <tt/optional/; as its name suggests, this <tt/control-flag/ marks the module as not being critical to the success or failure of the user's application for service. In general, <bf/Linux-PAM/ ignores such a module when determining if the module stack will succeed or fail. However, in the absence of any definite successes or failures of previous or subsequent stacked modules this module will determine the nature of the response to the application. One example of this latter case, is when the other modules return something like <tt/PAM_IGNORE/. </itemize> The more elaborate (newer) syntax is much more specific and gives the administrator a great deal of control over how the user is authenticated. This form of the control flag is delimeted with square brackets and consists of a series of <tt/value=action/ tokens: <tscreen> <verb> [value1=action1 value2=action2 ...] </verb> </tscreen> Here, <tt/valueI/ is one of the following <em/return values/: <tt/success/; <tt/open_err/; <tt/symbol_err/; <tt/service_err/; <tt/system_err/; <tt/buf_err/; <tt/perm_denied/; <tt/auth_err/; <tt/cred_insufficient/; <tt/authinfo_unavail/; <tt/user_unknown/; <tt/maxtries/; <tt/new_authtok_reqd/; <tt/acct_expired/; <tt/session_err/; <tt/cred_unavail/; <tt/cred_expired/; <tt/cred_err/; <tt/no_module_data/; <tt/conv_err/; <tt/authtok_err/; <tt/authtok_recover_err/; <tt/authtok_lock_busy/; <tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/; <tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; <tt/conv_again/; <tt/incomplete/; and <tt/default/. The last of these (<tt/default/) can be used to set the action for those return values that are not explicitly defined. The <tt/actionI/ can be a positive integer or one of the following tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and <tt/reset/. A positive integer, <tt/J/, when specified as the action, can be used to indicate that the next <em/J/ modules of the current type will be skipped. In this way, the administrator can develop a moderately sophisticated stack of modules with a number of different paths of execution. Which path is taken can be determined by the reactions of individual modules. <itemize> <item><tt/ignore/ - when used with a stack of modules, the module's return status will not contribute to the return code the application obtains. <item><tt/bad/ - this action indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack. <item><tt/die/ - equivalent to <tt/bad/ with the side effect of terminating the module stack and PAM immediately returning to the application. <item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this return code should contribute directly to the return code of the full stack of modules. In other words, if the former state of the stack would lead to a return of <tt/PAM_SUCCESS/, the module's return code will override this value. Note, if the former state of the stack holds some value that is indicative of a modules failure, this 'ok' value will not be used to override that value. <item><tt/done/ - equivalent to <tt/ok/ with the side effect of terminating the module stack and PAM immediately returning to the application. <item><tt/reset/ - clear all memory of the state of the module stack and start again with the next stacked module. </itemize> Just to get a feel for the power of this new syntax, here is a taste of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of client plug-in agents was introduced. This is something that makes it possible for PAM to support machine-machine authentication using the transport protocol inherent to the client/server application. With the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible for an application to be configured to support binary prompts with compliant clients, but to gracefully fall over into an alternative authentication mode for older, legacy, applications. Flexible eh? <tag> <tt/module-path/</tag> The path-name of the dynamically loadable object file; <em/the pluggable module/ itself. If the first character of the module path is `<tt>/</tt>', it is assumed to be a complete path. If this is not the case, the given module path is appended to the default module path: <tt>/usr/lib/security</tt> (but see the notes <ref id="text-conventions" name="above">). <tag> <tt/args/</tag> The <tt/args/ are a list of tokens that are passed to the module when it is invoked. Much like arguments to a typical Linux shell command. Generally, valid arguments are optional and are specific to any given module. Invalid arguments are ignored by a module, however, when encountering an invalid argument, the module is required to write an error to <tt/syslog(3)/. For a list of <em/generic/ options see the next section. </descrip> Any line in (one of) the confiuration file(s), that is not formatted correctly, will generally tend (erring on the side of caution) to make the authentication process fail. A corresponding error is written to the system log files with a call to <tt/syslog(3)/. <sect1>Directory based configuration More flexible than the single configuration file, as of version 0.56, it is possible to configure <tt>libpam</tt> via the contents of the <tt>/etc/pam.d/</tt> directory. In this case the directory is filled with files each of which has a filename equal to a service-name (in lower-case): it is the personal configuration file for the named service. <bf/Linux-PAM/ can be compiled in one of two modes. The preferred mode uses either <tt>/etc/pam.d/</tt> or <tt>/etc/pam.conf</tt> configuration but not both. That is to say, if there is a <tt>/etc/pam.d/</tt> directory then libpam only uses the files contained in this directory. However, in the absence of the <tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is used. The other mode (and the one currently supported by Red Hat 4.2 and higher) is to use both <tt>/etc/pam.d/</tt> and <tt>/etc/pam.conf</tt> in sequence. In this mode, entries in <tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>. The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of the <tt>/etc/pam.conf</tt> file and is made up of lines of the following form: <tscreen> <verb> module-type control-flag module-path arguments </verb> </tscreen> The only difference being that the <tt>service-name</tt> is not present. The service-name is of course the name of the given configuration file. For example, <tt>/etc/pam.d/login</tt> contains the configuration for the login service. This method of configuration has a number of advantages over the single file approach. We list them here to assist the reader in deciding which scheme to adopt: <itemize> <item>A lower chance of misconfiguring an application. There is one less field to mis-type when editing the configuration files by hand. <item>Easier to maintain. One application may be reconfigured without risk of interfering with other applications on the system. <item>It is possible to symbolically link different services configuration files to a single file. This makes it easier to keep the system policy for access consistent across different applications. (It should be noted, to conserve space, it is equally possible to hard link a number of configuration files. However, care should be taken when administering this arrangement as editing a hard linked file is likely to break the link.) <item>A potential for quicker configuration file parsing. Only the relevant entries are parsed when a service gets bound to its modules. <item>It is possible to limit read access to individual <bf/Linux-PAM/ configuration files using the file protections of the filesystem. <item>Package management becomes simpler. Every time a new application is installed, it can be accompanied by an <tt>/etc/pam.d/</tt>xxxxxx file. </itemize> <sect1>Generic optional arguments The following are optional arguments which are likely to be understood by any module. Arguments (including these) are in general <em/optional/. <descrip> <tag><tt/debug/</tag> Use the <tt/syslog(3)/ call to log debugging information to the system log files. <tag> <tt/no_warn/</tag> Instruct module to not give warning messages to the application. <tag> <tt/use_first_pass/</tag> The module should not prompt the user for a password. Instead, it should obtain the previously typed password (from the preceding <tt/auth/ module), and use that. If that doesn't work, then the user will not be authenticated. (This option is intended for <tt/auth/ and <tt/password/ modules only). <tag> <tt/try_first_pass/</tag> The module should attempt authentication with the previously typed password (from the preceding <tt/auth/ module). If that doesn't work, then the user is prompted for a password. (This option is intended for <tt/auth/ modules only). <tag> <tt/use_mapped_pass/</tag> This argument is not currently supported by any of the modules in the <bf/Linux-PAM/ distribution because of possible consequences associated with U.S. encryption exporting restrictions. Within the U.S., module developers are, of course, free to implement it (as are developers in other countries). For compatibility reasons we describe its use as suggested in the <bf/DCE-RFC 86.0/, see section <ref id="see-also-sec" name="bibliography"> for a pointer to this document. The <tt/use_mapped_pass/ argument instructs the module to take the clear text authentication token entered by a previous module (that requests such a token) and use it to generate an encryption/decryption key with which to safely store/retrieve the authentication token required for this module. In this way the user can enter a single authentication token and be quietly authenticated by a number of stacked modules. Obviously a convenient feature that necessarily requires some reliably strong encryption to make it secure. This argument is intended for the <tt/auth/ and <tt/password/ module types only. <tag><tt/expose_account/</tag> In general the leakage of some information about user accounts is not a secure policy for modules to adopt. Sometimes information such as users names or home directories, or preferred shell, can be used to attack a user's account. In some circumstances, however, this sort of information is not deemed a threat: displaying a user's full name when asking them for a password in a secured environment could also be called being 'friendly'. The <tt/expose_account/ argument is a standard module argument to encourage a module to be less discrete about account information as it is deemed appropriate by the local administrator. </descrip> <sect1>Example configuration file entries In this section, we give some examples of entries that can be present in the <bf/Linux-PAM/ configuration file. As a first attempt at configuring your system you could do worse than to implement these. <sect2>Default policy If a system is to be considered secure, it had better have a reasonably secure `<tt/OTHER/' entry. The following is a paranoid setting (which is not a bad place to start!): <tscreen> <verb> # # default; deny access # OTHER auth required /usr/lib/security/pam_deny.so OTHER account required /usr/lib/security/pam_deny.so OTHER password required /usr/lib/security/pam_deny.so OTHER session required /usr/lib/security/pam_deny.so </verb> </tscreen> Whilst fundamentally a secure default, this is not very sympathetic to a misconfigured system. For example, such a system is vulnerable to locking everyone out should the rest of the file become badly written. The module <tt/pam_deny/ (documented in a later section) is not very sophisticated. For example, it logs no information when it is invoked so unless the users of a system contact the administrator when failing to execute a service application, the administrator may go for a long while in ignorance of the fact that his system is misconfigured. The addition of the following line before those in the above example would provide a suitable warning to the administrator. <tscreen> <verb> # # default; wake up! This application is not configured # OTHER auth required /usr/lib/security/pam_warn.so OTHER password required /usr/lib/security/pam_warn.so </verb> </tscreen> Having two ``<tt/OTHER auth/'' lines is an example of stacking. On a system that uses the <tt>/etc/pam.d/</tt> configuration, the corresponding default setup would be achieved with the following file: <tscreen> <verb> # # default configuration: /etc/pam.d/other # auth required /usr/lib/security/pam_warn.so auth required /usr/lib/security/pam_deny.so account required /usr/lib/security/pam_deny.so password required /usr/lib/security/pam_warn.so password required /usr/lib/security/pam_deny.so session required /usr/lib/security/pam_deny.so </verb> </tscreen> This is the only explicit example we give for an <tt>/etc/pam.d/</tt> file. In general, it should be clear how to transpose the remaining examples to this configuration scheme. On a less sensitive computer, one on which the system administrator wishes to remain ignorant of much of the power of <tt/Linux-PAM/, the following selection of lines (in <tt>/etc/pam.conf</tt>) is likely to mimic the historically familiar Linux setup. <tscreen> <verb> # # default; standard UNIX access # OTHER auth required /usr/lib/security/pam_unix_auth.so OTHER account required /usr/lib/security/pam_unix_acct.so OTHER password required /usr/lib/security/pam_unix_passwd.so OTHER session required /usr/lib/security/pam_unix_session.so </verb> </tscreen> In general this will provide a starting place for most applications. Unfortunately, most is not all. One application that might require additional lines is <em/ftpd/ if you wish to enable <em/anonymous-ftp/. To enable anonymous-ftp, the following lines might be used to replace the default (<tt/OTHER/) ones. (<bf/*WARNING*/ as of 1996/12/28 this does not work correctly with any ftpd. Consequently, this description may be subject to change or the application will be fixed.) <tscreen> <verb> # # ftpd; add ftp-specifics. These lines enable anonymous ftp over # standard UNIX access (the listfile entry blocks access to # users listed in /etc/ftpusers) # ftpd auth sufficient /usr/lib/security/pam_ftp.so ftpd auth required /usr/lib/security/pam_unix_auth.so use_first_pass ftpd auth required /usr/lib/security/pam_listfile.so \ onerr=succeed item=user sense=deny file=/etc/ftpusers </verb> </tscreen> Note, the second line is necessary since the default entries are ignored by a service application (here <em/ftpd/) if there are <em/any/ entries in <tt>/etc/pam.conf</tt> for that specified service. Again, this is an example of authentication module stacking. Note the use of the <tt/sufficient/ control-flag. It says that ``if this module authenticates the user, ignore the subsequent <tt/auth/ modules''. Also note the use of the ``<tt/use_first_pass/'' module-argument, this instructs the UNIX authentication module that it is not to prompt for a password but rely one already having been obtained by the ftp module. <sect>Security issues of Linux-PAM This section will discuss good practices for using Linux-PAM in a secure manner. It is currently sadly lacking...suggestions are welcome! <sect1>If something goes wrong <bf/Linux-PAM/ has the potential to seriously change the security of your system. You can choose to have no security or absolute security (no access permitted). In general, <bf/Linux-PAM/ errs towards the latter. Any number of configuration errors can dissable access to your system partially, or completely. The most dramatic problem that is likely to be encountered when configuring <bf/Linux-PAM/ is that of deleting the configuration file(s): <tt>/etc/pam.d/*</tt> and/or <tt>/etc/pam.conf</tt>. This will lock you out of your own system! To recover, your best bet is to reboot the system in single user mode and set about correcting things from there. The following has been adapted from a life-saving email on the subject from David Wood: <em/NOTE:/ The following assumes that booting to single-user mode does not prompt for a password. However, on Debian and other distributions, this is not true. Init will instead start <tt/sulogin/, which asks for the root password. The program <tt/sulogin/ does not use PAM, so a broken PAM setup will not break this program. <verb> > What the hell do I do now? OK, don't panic. The first thing you have to realize is that this happens to 50% of users who ever do anything with PAM. It happened here, not once, not twice, but three times, all different, and in the end, the solution was the same every time. First, I hope you installed LILO with a delay. If you can, reboot, hit shift or tab or something and type: LILO boot: linux single (Replace 'linux' with 'name-of-your-normal-linux-image'). This will let you in without logging in. Ever wondered how easy it is to break into a linux machine from the console? Now you know. If you can't do that, then get yourself a bootkernel floppy and a root disk a-la slackware's rescue.gz. (Red Hat's installation disks can be used in this mode too.) In either case, the point is to get back your root prompt. Second, I'm going to assume that you haven't completely nuked your pam installation - just your configuration files. Here's how you make your configs nice again: cd /etc mv pam.conf pam.conf.orig mv pam.d pam.d.orig mkdir pam.d cd pam.d and then use vi to create a file called "other" in this directory. It should contain the following four lines: auth required pam_unix_auth.so account required pam_unix_acct.so password required pam_unix_passwd.so session required pam_unix_session.so Now you have the simplest possible PAM configuration that will work the way you're used to. Everything should magically start to work again. Try it out by hitting ALT-F2 and logging in on another virtual console. If it doesn't work, you have bigger problems, or you've mistyped something. One of the wonders of this system (seriously, perhaps) is that if you mistype anything in the conf files, you usually get no error reporting of any kind on the console - just some entries in the log file. So look there! (Try 'tail /var/log/messages'.) From here you can go back and get a real configuration going, hopefully after you've tested it first on a machine you don't care about screwing up. :/ Some pointers (to make everything "right" with Red Hat...): Install the newest pam, pamconfig, and pwdb from the redhat current directory, and do it all on the same command line with rpm... rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-* Then make sure you install (or reinstall) the newest version of libc, util-linux, wuftp, and NetKit. For kicks you might try installing the newest versions of the affected x apps, like xlock, but I haven't gotten those to work at all yet. </verb> <sect1>Avoid having a weak `other' configuration It is not a good thing to have a weak default (<tt/OTHER/) entry. This service is the default configuration for all PAM aware applications and if it is weak, your system is likely to be vulnerable to attack. Here is a sample "other" configuration file. The <em/pam_deny/ module will deny access and the <em/pam_warn/ module will send a syslog message to <tt/auth.notice/: <tscreen> <verb> # # The PAM configuration file for the `other' service # auth required pam_deny.so auth required pam_warn.so account required pam_deny.so account required pam_warn.so password required pam_deny.so password required pam_warn.so session required pam_deny.so session required pam_warn.so </verb> </tscreen> <sect>A reference guide for available modules Here, we collect together some descriptions of the various modules available for <bf/Linux-PAM/. In general these modules should be freely available. Where this is not the case, it will be indicated. Also please note the comments contained in the section <ref id="text-conventions" name="on text conventions above"> when copying the examples listed below.    <sect1> The access module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt>pam_access</tt> <tag><bf>Author[s]:</bf></tag> Alexei Nogin <alexei@nogin.dnttm.ru> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> account <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> Requires a configuration file <tt>/etc/security/access.conf</tt> <tag><bf>Network aware:</bf></tag> Through <tt/PAM_TTY/ if set, otherwise attempts getting tty name of the stdin file descriptor with <tt/ttyname()/. Standard gethostname(), <tt/yp_get_default_domain()/, <tt/gethostbyname()/ calls. <bf/NIS/ is used for netgroup support. </descrip> <sect2>Overview of module Provides logdaemon style login access control. <sect2> Account component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This module provides logdaemon style login access control based on login names and on host (or domain) names, internet addresses (or network numbers), or on terminal line names in case of non-networked logins. Diagnostics are reported through <tt/syslog(3)/. Wietse Venema's <tt/login_access.c/ from <em/logdaemon-5.6/ is used with several changes by A. Nogin. <tag><bf>Examples/suggested usage:</bf></tag> Use of module is recommended, for example, on administrative machines such as <bf/NIS/ servers and mail servers where you need several accounts active but don't want them all to have login capability. For <tt>/etc/pam.d</tt> style configurations where your modules live in <tt>/lib/security</tt>, start by adding the following line to <tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>, <tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>: <tscreen> <verb> account required /lib/security/pam_access.so </verb> </tscreen> Note that use of this module is not effective unless your system ignores <tt>.rhosts</tt> files. See the the pam_rhosts_auth documentation. A sample <tt>access.conf</tt> configuration file is included with the distribution. </descrip>  <sect1>Chroot <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_chroot/ <tag><bf>Author:</bf></tag> Bruce Campbell <brucec@humbug.org.au> <tag><bf>Maintainer:</bf></tag> Author; proposed on 20/11/96 - email for status <tag><bf>Management groups provided:</bf></tag> account; session; authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> Unwritten. <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> Expects localhost. </descrip> <sect2>Overview of module This module is intended to provide a transparent wrapper around the average user, one that puts them in a fake file-system (eg, their '<tt>/</tt>' is really <tt>/some/where/else</tt>). Useful if you have several classes of users, and are slightly paranoid about security. Can be used to limit who else users can see on the system, and to limit the selection of programs they can run. <sect2>Account component: <em/Need more info here./ <sect2>Authentication component: <em/Need more info here./ <sect2>Session component: <em/Need more info here./ <descrip> <tag><bf>Recognized arguments:</bf></tag> Arguments and logging levels for the PAM version are being worked on. <tag><bf>Description:</bf></tag> <tag><bf>Examples/suggested usage:</bf></tag> Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm', 'cp' and 'ed' in there is a bit... Don't take it to extremes (eg, you can set up a separate environment for each user, but its a big waste of your disk space.) </descrip>   <sect1>Cracklib pluggable password strength-checker <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> pam_cracklib <tag><bf>Author:</bf></tag> Cristian Gafton <gafton@redhat.com> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> password <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> Requires the system library <tt/libcrack/ and a system dictionary: <tt>/var/cache/cracklib/cracklib_dict</tt>. <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module can be plugged into the <tt/password/ stack of a given application to provide some plug-in strength-checking for passwords. This module works in the following manner: it first calls the Cracklib routine to check the strength of the password; if crack likes the password, the module does an additional set of strength checks. These checks are: <itemize> <item> <bf/Palindrome/ - Is the new password a palindrome of the old one? <item> <bf/Case Change Only/ - Is the new password the the old one with only a change of case? <item> <bf/Similar/ - Is the new password too much like the old one? This is controlled by one argument, <tt/difok/ which is a number of characters that if different between the old and new are enough to accept the new password, this defaults to 10 or 1/2 the size of the new password whichever is smaller. <item> <bf/Simple/ - Is the new password too small? This is controlled by 5 arguments <tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and <tt/ocredit/. See the section on the arguments for the details of how these work and there defaults. <item> <bf/Rotated/ - Is the new password a rotated version of the old password? <item> <bf/Already used/ - Was the password used in the past? Previously used passwords are to be found in /etc/security/opasswd. </itemize> This module with no arguments will work well for standard unix password encryption. With md5 encryption, passwords can be longer than 8 characters and the default settings for this module can make it hard for the user to choose a satisfactory new password. Notably, the requirement that the new password contain no more than 1/2 of the characters in the old password becomes a non-trivial constraint. For example, an old password of the form "the quick brown fox jumped over the lazy dogs" would be difficult to change... In addition, the default action is to allow passwords as small as 5 characters in length. For a md5 systems it can be a good idea to increase the required minimum size of a password. One can then allow more credit for different kinds of characters but accept that the new password may share most of these characters with the old password. <sect2>Password component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/; <tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/; <tag><bf>Description:</bf></tag> The action of this module is to prompt the user for a password and check its strength against a system dictionary and a set of rules for identifying poor choices. The default action is to prompt for a single password, check its strength and then, if it is considered strong, prompt for the password a second time (to verify that it was typed correctly on the first occasion). All being well, the password is passed on to subsequent modules to be installed as the new authentication token. The default action may be modified in a number of ways using the arguments recognized by the module: <itemize> <item> <tt/debug/ - this option makes the module write information to syslog(3) indicating the behavior of the module (this option does <bf/not/ write password information to the log file). <item> <tt/type=XXX/ - the default action is for the module to use the following prompts when requesting passwords: ``New UNIX password: '' and ``Retype UNIX password: ''. Using this option you can replace the word UNIX with <tt/XXX/. <item> <tt/retry=N/ - the default number of times this module will request a new password (for strength-checking) from the user is 1. Using this argument this can be increased to <tt/N/. <item> <tt/difok=N/ - This argument will change the default of 10 for the number of characters in the new password that must not be present in the old password. In addition, if 1/2 of the characters in the new password are different then the new password will be accepted anyway. <item> <tt/minlen=N/ - The minimum acceptable size for the new password plus one. In addition to the number of characters in the new password, credit (of +1 in length) is given for each different kind of character (other, upper, lower and <em/digit/). The default for this parameter is 9 which is good for a old style UNIX password all of the same type of character but may be too low to exploit the added security of a md5 system. Note that there is a pair of length limits in Cracklib itself, a "way too short" limit of 4 which is hard coded in and a defined limit (6) that will be checked without reference to <tt>minlen</tt>. If you want to allow passwords as short as 5 characters you should either not use this module or recompile the crack library and then recompile this module. <item> <tt/dcredit=N/ - This is the maximum credit for having digits in the new password. If you have less than or <tt/N/ digits, each digit will count +1 towards meeting the current <tt/minlen/ value. The default for <tt/dcredit/ is 1 which is the recommended value for <tt/minlen/ less than 10. <item> <tt/ucredit=N/ - This is the maximum credit for having upper case letters in the new password. If you have less than or <tt/N/ upper case letters each letter will count +1 towards meeting the current <tt/minlen/ value. The default for <tt/ucredit/ is 1 which is the recommended value for <tt/minlen/ less than 10. <item> <tt/lcredit=N/ - This is the maximum credit for having lower case letters in the new password. If you have less than or <tt/N/ lower case letters, each letter will count +1 towards meeting the current <tt/minlen/ value. The default for <tt/lcredit/ is 1 which is the recommended value for <tt/minlen/ less than 10. <item> <tt/ocredit=N/ - This is the maximum credit for having other characters in the new password. If you have less than or <tt/N/ other characters, each character will count +1 towards meeting the current <tt/minlen/ value. The default for <tt/ocredit/ is 1 which is the recommended value for <tt/minlen/ less than 10. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> For an example of the use of this module, we show how it may be stacked with the password component of <tt/pam_unix/: <tscreen> <verb> # # These lines stack two password type modules. In this example the # user is given 3 opportunities to enter a strong password. The # "use_authtok" argument ensures that the pam_unix module does not # prompt for a password, but instead uses the one provided by # pam_cracklib. # passwd password required pam_cracklib.so retry=3 passwd password required pam_unix.so use_authtok </verb> </tscreen> Another example (in the <tt>/etc/pam.d/passwd</tt> format) is for the case that you want to use md5 password encryption: <tscreen> <verb> #%PAM-1.0 # # These lines allow a md5 systems to support passwords of at least 14 # bytes with extra credit of 2 for digits and 2 for others the new # password must have at least three bytes that are not present in the # old password # password required pam_cracklib.so \ difok=3 minlen=15 dcredit= 2 ocredit=2 password required pam_unix.so use_authtok nullok md5 </verb> </tscreen> </descrip>   <sect1>The locking-out module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> pam_deny <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> current <bf/Linux-PAM/ maintainer <tag><bf>Management groups provided:</bf></tag> account; authentication; password; session <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> clean. <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module can be used to deny access. It always indicates a failure to the application through the PAM framework. As is commented in the overview section <ref id="overview-section" name="above">, this module might be suitable for using for default (the <tt/OTHER/) entries. <sect2>Account component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This component does nothing other than return a failure. The failure type is <tt/PAM_ACCT_EXPIRED/. <tag><bf>Examples/suggested usage:</bf></tag> Stacking this module with type <tt/account/ will prevent the user from gaining access to the system via applications that refer to <bf/Linux-PAM/'s account management function <tt/pam_acct_mgmt()/. The following example would make it impossible to login: <tscreen> <verb> # # add this line to your other login entries to disable all accounts # login account required pam_deny.so </verb> </tscreen> </descrip> <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This component does nothing other than return a failure. The failure type is <tt/PAM_AUTH_ERR/ in the case that <tt/pam_authenticate()/ is called (when the application tries to authenticate the user), and is <tt/PAM_CRED_UNAVAIL/ when the application calls <tt/pam_setcred()/ (to establish and set the credentials of the user -- it is unlikely that this function will ever be called in practice). <tag><bf>Examples/suggested usage:</bf></tag> To deny access to default applications with this component of the <tt/pam_deny/ module, you might include the following line in your <bf/Linux-PAM/ configuration file: <tscreen> <verb> # # add this line to your existing OTHER entries to prevent # authentication succeeding with default applications. # OTHER auth required pam_deny.so </verb> </tscreen> </descrip> <sect2>Password component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This component of the module denies the user the opportunity to change their password. It always responds with <tt/PAM_AUTHTOK_ERR/ when invoked. <tag><bf>Examples/suggested usage:</bf></tag> This module should be used to prevent an application from updating the applicant user's password. For example, to prevent <tt/login/ from automatically prompting for a new password when the old one has expired you should include the following line in your configuration file: <tscreen> <verb> # # add this line to your other login entries to prevent the login # application from being able to change the user's password. # login password required pam_deny.so </verb> </tscreen> </descrip> <sect2>Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This aspect of the module prevents an application from starting a session on the host computer. <tag><bf>Examples/suggested usage:</bf></tag> Together with another session module, that displays a message of the day perhaps (XXX - such a module needs to be written), this module can be used to block a user from starting a shell. Given the presence of a <tt/pam_motd/ module, we might use the following entries in the configuration file to inform the user it is system time: <tscreen> <verb> # # An example to see how to configure login to refuse the user a # session (politely) # login session required pam_motd.so \ file=/etc/system_time login session required pam_deny.so </verb> </tscreen> </descrip>   <sect1>Set/unset environment variables <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_env/ <tag><bf>Author:</bf></tag> Dave Kinchlea <kinch@kinch.ark.com> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> Authentication (setcred) <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tt>/etc/security/pam_env.conf</tt> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module allows the (un)setting of environment variables. Supported is the use of previously set environment variables as well as PAM_ITEMs such as <tt>PAM_RHOST</tt>. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/conffile=/<em/configuration-file-name/; <tt/envfile/=/<em/env-file-name/; <tt/readenv/=/<em/0|1/ <tag><bf>Description:</bf></tag> This module allows you to (un)set arbitrary environment variables using fixed strings, the value of previously set environment variables and/or <em/PAM_ITEM/s. All is controlled via a configuration file (by default, <tt>/etc/security/pam_env.conf</tt> but can be overriden with <tt>connfile</tt> argument). Each line starts with the variable name, there are then two possible options for each variable <bf>DEFAULT</bf> and <bf>OVERRIDE</bf>. <bf>DEFAULT</bf> allows and administrator to set the value of the variable to some default value, if none is supplied then the empty string is assumed. The <bf>OVERRIDE</bf> option tells pam_env that it should enter in its value (overriding the default value) if there is one to use. <bf>OVERRIDE</bf> is not used, <tt>""</tt> is assumed and no override will be done. <tscreen> <verb> VARIABLE [DEFAULT=[value]] [OVERRIDE=[value]] </verb> </tscreen> (Possibly non-existent) environment variables may be used in values using the <tt>${string}</tt> syntax and (possibly non-existent) <em/PAM_ITEM/s may be used in values using the <tt>@{string}</tt> syntax. Both the <tt>$</tt> and <tt>@</tt> characters can be backslash-escaped to be used as literal values (as in <tt>\$</tt>. Double quotes may be used in values (but not environment variable names) when white space is needed <bf>the full value must be delimited by the quotes and embedded or escaped quotes are not supported</bf>. This module can also parse a file with simple KEY=VAL pairs on seperate lines (/etc/environment by default). You can change the default file to parse, with the <em/envfile/ flag and turn it on or off by setting the <em/readenv/ flag to 1 or 0 respectively. The behavior of this module can be modified with one of the following flags: <itemize> <item><tt/debug/ - write more information to <tt/syslog(3)/. <item><tt/conffile=/<em/filename/ - by default the file <tt>/etc/security/pam_env.conf</tt> is used as the configuration file. This option overrides the default. You must supply a complete path + file name. <item><tt/envfile=/<em/filename/ - by default the file <tt>/etc/environment</tt> is used to load KEY=VAL pairs directly into the env. This option overrides the default. You must supply a complete path + file name. <item><tt/readenv=/<em/0|1/ - turns on or off the reading of the file specified by envfile (0 is off, 1 is on). By default this option is on. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> See sample <tt>pam_env.conf</tt> for more information and examples. </descrip>   <sect1>The filter module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> pam_filter <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> account; authentication; password; session <tag><bf>Cryptographically sensitive:</bf></tag> Not yet. <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> This module compiles cleanly on Linux based systems. <tag><bf>System dependencies:</bf></tag> To function it requires <em/filters/ to be installed on the system. <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module was written to offer a plug-in alternative to programs like ttysnoop (XXX - need a reference). Since writing a filter that performs this function has not occurred, it is currently only a toy. The single filter provided with the module simply transposes upper and lower case letters in the input and output streams. (This can be very annoying and is not kind to termcap based editors). <sect2>Account+Authentication+Password+Session components <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/new_term/; <tt/non_term/; <tt/runX/ <tag><bf>Description:</bf></tag> Each component of the module has the potential to invoke the desired filter. The filter is always <tt/execv(2)/d with the privilege of the calling application and <bf/not/ that of the user. For this reason it cannot usually be killed by the user without closing their session. The behavior of the module can be significantly altered by the arguments passed to it in the <bf/Linux-PAM/ configuration file: <itemize> <item><tt/debug/ - this option increases the amount of information logged to <tt/syslog(3)/ as the module is executed. <item><tt/new_term/ - the default action of the filter is to set the <tt/PAM_TTY/ item to indicate the terminal that the user is using to connect to the application. This argument indicates that the filter should set <tt/PAM_TTY/ to the filtered pseudo-terminal. <item><tt/non_term/ - don't try to set the <tt/PAM_TTY/ item. <item><tt/runX/ - in order that the module can invoke a filter it should know when to invoke it. This argument is required to tell the filter when to do this. The arguments that follow this one are respectively the full pathname of the filter to be run and any command line arguments that the filter might expect. Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the precise time the that filter is to be run. To explain this concept it will be useful to have read the Linux-PAM Module developer's guide. Basically, for each management group there are up to two ways of calling the module's functions. In the case of the <em/authentication/ and <em/session/ components there are actually two separate functions. For the case of authentication, these functions are <tt/_authenticate/ and <tt/_setcred/ -- here <tt/run1/ means run the filter from the <tt/_authenticate/ function and <tt/run2/ means run the filter from <tt/_setcred/. In the case of the session modules, <tt/run1/ implies that the filter is invoked at the <tt/_open_session/ stage, and <tt/run2/ for <tt/_close_session/. For the case of the account component. Either <tt/run1/ or <tt/run2/ may be used. For the case of the password component, <tt/run1/ is used to indicate that the filter is run on the first occasion <tt/_chauthtok/ is run (the <tt/PAM_PRELIM_CHECK/ phase) and <tt/run2/ is used to indicate that the filter is run on the second occasion (the <tt/PAM_UPDATE_AUTHTOK/ phase). </itemize> <tag><bf>Examples/suggested usage:</bf></tag> At the time of writing there is little real use to be made of this module. For fun you might try adding the following line to your login's configuration entries <tscreen> <verb> # # An example to see how to configure login to transpose upper and # lower case letters once the user has logged in(!) # login session required pam_filter.so \ run1 /usr/sbin/pam_filter/upperLOWER </verb> </tscreen> </descrip>   <sect1>Anonymous access module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_ftp.so/ <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@linux.kernel.org> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> prompts for email address of user; easily spoofed (XXX - needs work) </descrip> <sect2>Overview of module The purpose of this module is to provide a pluggable anonymous ftp mode of access. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/users=XXX,YYY,.../; <tt/ignore/ <tag><bf>Description:</bf></tag> This module intercepts the user's name and password. If the name is ``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/ part; these pam-items being set accordingly. The username is set to ``<tt/ftp/''. In this case the module succeeds. Alternatively, the module sets the <tt/PAM_AUTHTOK/ item with the entered password and fails. The behavior of the module can be modified with the following flags: <itemize> <item><tt/debug/ - log more information to with <tt/syslog(3)/. <item><tt/users=XXX,YYY,.../ - instead of ``<tt/ftp/'' or ``<tt/anonymous/'', provide anonymous login to the comma separated list of users; ``<tt/XXX,YYY,.../''. Should the applicant enter one of these usernames the returned username is set to the first in the list; ``<tt/XXX/''. <item><tt/ignore/ - pay no attention to the email address of the user (if supplied). </itemize> <tag><bf>Examples/suggested usage:</bf></tag> An example of the use of this module is provided in the configuration file section <ref id="configuration" name="above">. With care, this module could be used to provide new/temporary account anonymous login. </descrip>   <sect1>The group access module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_group/ <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> Sensitive to <em/setgid/ status of file-systems accessible to users. <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> Requires an <tt>/etc/security/group.conf</tt> file. Can be compiled with or without <tt/libpwdb/. <tag><bf>Network aware:</bf></tag> Only through correctly set <tt/PAM_TTY/ item. </descrip> <sect2>Overview of module This module provides group-settings based on the user's name and the terminal they are requesting a given service from. It takes note of the time of day. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This module does not authenticate the user, but instead it grants group memberships (in the credential setting phase of the authentication module) to the user. Such memberships are based on the service they are applying for. The group memberships are listed in text form in the <tt>/etc/security/group.conf</tt> file. <tag><bf>Examples/suggested usage:</bf></tag> For this module to function correctly there must be a correctly formatted <tt>/etc/security/groups.conf</tt> file present. The format of this file is as follows. Group memberships are given based on the service application satisfying any combination of lines in the configuration file. Each line (barring comments which are preceded by `<tt/#/' marks) has the following syntax: <tscreen> <verb> services ; ttys ; users ; times ; groups </verb> </tscreen> Here the first four fields share the syntax of the <tt>pam_time</tt> configuration file; <tt>/etc/security/pam_time.conf</tt>, and the last field, the <tt/groups/ field, is a comma (or space) separated list of the text-names of a selection of groups. If the users application for service satisfies the first four fields, the user is granted membership of the listed groups. As stated in above this module's usefulness relies on the file-systems accessible to the user. The point being that once granted the membership of a group, the user may attempt to create a <em/setgid/ binary with a restricted group ownership. Later, when the user is not given membership to this group, they can recover group membership with the precompiled binary. The reason that the file-systems that the user has access to are so significant, is the fact that when a system is mounted <em/nosuid/ the user is unable to create or execute such a binary file. For this module to provide any level of security, all file-systems that the user has write access to should be mounted <em/nosuid/. The <tt>pam_group</tt> module fuctions in parallel with the <tt>/etc/group</tt> file. If the user is granted any groups based on the behavior of this module, they are granted in addition to those entries <tt>/etc/group</tt> (or equivalent). </descrip>   <sect1>Add issue file to user prompt <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_issue/ <tag><bf>Author:</bf></tag> Ben Collins <bcollins@debian.org> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> Authentication (pam_sm_authenticate) <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module prepends the issue file (/etc/issue by default) when prompting for a username. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/issue=issue-file-name/; <tt/noesc/; <tag><bf>Description:</bf></tag> This module allows you to prepend an issue file to the username prompt. It also by default parses escape codes in the issue file similar to some common getty's (using \x format). Recognized escapes: <itemize> <item><tt/d/ - current date <item><tt/s/ - operating system name <item><tt/l/ - name of this tty <item><tt/m/ - architecture of this system (i686, sparc, powerpc, ...) <item><tt/n/ - hostname of this system <item><tt/o/ - domainname of this system <item><tt/r/ - release number of the operation system (eg. 2.2.12) <item><tt/t/ - current time <item><tt/u/ - number of users currently logged in <item><tt/U/ - same as <tt/u/, except it is suffixed with "user" or "users" (eg. "1 user" or "10 users" <item><tt/v/ - version/build-date of the operating system (eg. "#3 Mon Aug 23 14:38:16 EDT 1999" on Linux). </itemize> The behavior of this module can be modified with one of the following flags: <itemize> <item><tt/issue/ - the file to output if not using the default <item><tt/noesc/ - turns off escape code parsing </itemize> <tag><bf>Examples/suggested usage:</bf></tag> login auth pam_issue.so issue=/etc/issue </descrip>   <sect1>The Kerberos 4 module. <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_krb4/ <tag><bf>Author:</bf></tag> Derrick J. Brashear <shadow@dementia.org> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> authentication; password; session <tag><bf>Cryptographically sensitive:</bf></tag> uses API <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> libraries - <tt/libkrb/, <tt/libdes/, <tt/libcom_err/, <tt/libkadm/; and a set of Kerberos include files. <tag><bf>Network aware:</bf></tag> Gets Kerberos ticket granting ticket via a Kerberos key distribution center reached via the network. </descrip> <sect2>Overview of module This module provides an interface for doing Kerberos verification of a user's password, getting the user a Kerberos ticket granting ticket for use with the Kerberos ticket granting service, destroying the user's tickets at logout time, and changing a Kerberos password. <sect2> Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This component of the module currently sets the user's <tt/KRBTKFILE/ environment variable (although there is currently no way to export this), as well as deleting the user's ticket file upon logout (until <tt/PAM_CRED_DELETE/ is supported by <em/login/). <tag><bf>Examples/suggested usage:</bf></tag> This part of the module won't be terribly useful until we can change the environment from within a <tt/Linux-PAM/ module. </descrip> <sect2> Password component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/use_first_pass/; <tt/try_first_pass/ <tag><bf>Description:</bf></tag> This component of the module changes a user's Kerberos password by first getting and using the user's old password to get a session key for the password changing service, then sending a new password to that service. <tag><bf>Examples/suggested usage:</bf></tag> This should only be used with a real Kerberos v4 <tt/kadmind/. It cannot be used with an AFS kaserver unless special provisions are made. Contact the module author for more information. </descrip> <sect2> Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/use_first_pass/; <tt/try_first_pass/ <tag><bf>Description:</bf></tag> This component of the module verifies a user's Kerberos password by requesting a ticket granting ticket from the Kerberos server and optionally using it to attempt to retrieve the local computer's host key and verifying using the key file on the local machine if one exists. It also writes out a ticket file for the user to use later, and deletes the ticket file upon logout (not until <tt/PAM_CRED_DELETE/ is called from <em/login/). <tag><bf>Examples/suggested usage:</bf></tag> This module can be used with a real Kerberos server using MIT v4 Kerberos keys. The module or the system Kerberos libraries may be modified to support AFS style Kerberos keys. Currently this is not supported to avoid cryptography constraints. </descrip>   <sect1>The last login module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_lastlog/ <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> auth <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> uses information contained in the <tt>/var/log/lastlog</tt> file. <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This session module maintains the <tt>/var/log/lastlog</tt> file. Adding an open entry when called via the <tt>pam_open_seesion()</tt> function and completing it when <tt>pam_close_session()</tt> is called. This module can also display a line of information about the last login of the user. If an application already performs these tasks, it is not necessary to use this module. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/nodate/; <tt/noterm/; <tt/nohost/; <tt/silent/; <tt/never/ <tag><bf>Description:</bf></tag> This module can be used to provide a ``Last login on ...'' message. when the user logs into the system from what ever application uses the PAM libraries. In addition, the module maintains the <tt>/var/log/lastlog</tt> file. The behavior of this module can be modified with one of the following flags: <itemize> <item><tt/debug/ - write more information to <tt/syslog(3)/. <item><tt/nodate/ - neglect to give the date of the last login when displaying information about the last login on the system. <item><tt/noterm/ - neglect to diplay the terminal name on which the last login was attempt. <item><tt/nohost/ - neglect to indicate from which host the last login was attempted. <item><tt/silent/ - neglect to inform the user about any previous login: just update the <tt>/var/log/lastlog</tt> file. <item><tt/never/ - if the <tt>/var/log/lastlog</tt> file does not contain any old entries for the user, indicate that the user has never previously logged in with a ``welcome..." message. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> This module can be used to indicate that the user has new mail when they <em/login/ to the system. Here is a sample entry for your <tt>/etc/pam.conf</tt> file: <tscreen> <verb> # # do we have any mail? # login session optional pam_lastlog.so </verb> </tscreen> Note, some applications may perform this function themselves. In such cases, this module is not necessary. </descrip>   <sect1>The resource limits module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_limits/ <tag><bf>Authors:</bf></tag> Cristian Gafton <gafton@redhat.com> <newline> Thanks are also due to Elliot Lee <sopwith@redhat.com> for his comments on improving this module. <tag><bf>Maintainer:</bf></tag> Cristian Gafton - 1996/11/20 <tag><bf>Management groups provided:</bf></tag> session <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> requires an <tt>/etc/security/limits.conf</tt> file and kernel support for resource limits. Also uses the library, <tt/libpwdb/. <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module, through the <bf/Linux-PAM/ <em/open/-session hook, sets limits on the system resources that can be obtained in a user-session. Its actions are dictated more explicitly through the configuration file discussed below. <sect2>Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt>conf=/path/to/file.conf</tt> <tag><bf>Description:</bf></tag> Through the contents of the configuration file, <tt>/etc/security/limits.conf</tt>, resource limits are placed on users' sessions. Users of <tt/uid=0/ are not affected by this restriction. The behavior of this module can be modified with the following arguments: <itemize> <item><tt/debug/ - verbose logging to <tt/syslog(3)/. <item><tt>conf=/path/to/file.conf</tt> - indicate an alternative <em/limits/ configuration file to the default. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> In order to use this module the system administrator must first create a <em/root-only-readable/ file (default is <tt>/etc/security/limits.conf</tt>). This file describes the resource limits the superuser wishes to impose on users and groups. No limits are imposed on <tt/uid=0/ accounts. Each line of the configuration file describes a limit for a user in the form: <tscreen> <verb> <domain> <type> <item> <value> </verb> </tscreen> The fields listed above should be filled as follows...<newline> <tt><domain></tt> can be: <itemize> <item> a username <item> a groupname, with <tt>@group</tt> syntax <item> the wild-card <tt/*/, for default entry </itemize> <tt><type></tt> can have the two values: <itemize> <item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits are set by the superuser and enforced by the Linux Kernel. The user cannot raise his requirement of system resources above such values. <item> <tt/soft/ for enforcing <em/soft/ resource limits. These limits are ones that the user can move up or down within the permitted range by any pre-exisiting <em/hard/ limits. The values specified with this token can be thought of as <em/default/ values, for normal system usage. </itemize> <tt><item></tt> can be one of the following: <itemize> <item><tt/core/ - limits the core file size (KB) <item><tt/data/ - max data size (KB) <item><tt/fsize/ - maximum filesize (KB) <item><tt/memlock/ - max locked-in-memory address space (KB) <item><tt/nofile/ - max number of open files <item><tt/rss/ - max resident set size (KB) <item><tt/stack/ - max stack size (KB) <item><tt/cpu/ - max CPU time (MIN) <item><tt/nproc/ - max number of processes <item><tt/as/ - address space limit <item><tt/maxlogins/ - max number of logins for this user. <item><tt/priority/ - the priority to run user process with <item><tt/chroot/ - directory to chroot user to </itemize> To completely disable limits for a user (or a group), a single dash (-) will do (Example: ``<tt/bin -/'', ``<tt/@admin -/''). Please remember that individual limits have priority over group limits, so if you impose no limits for <tt/admin/ group, but one of the members in this group have a limits line, the user will have its limits set according to this line. Also, please note that all limit settings are set <em/per login/. They are not global, nor are they permanent; existing only for the duration of the session. In the <em/limits/ configuration file, the ``<tt/#/'' character introduces a comment - after which the rest of the line is ignored. The <tt/pam_limits/ module does its best to report configuration problems found in its configuration file via <tt/syslog(3)/. The following is an example configuration file: <tscreen> <verb> # EXAMPLE /etc/security/limits.conf file: # ======================================= # <domain> <type> <item> <value> * soft core 0 * hard rss 10000 @student hard nproc 20 @faculty soft nproc 20 @faculty hard nproc 50 ftp hard nproc 0 ftp - chroot /ftp @student - maxlogins 4 </verb> </tscreen> Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource (see <tt/@faculty/) -- this establishes the <em/default/ and permitted <em/extreme/ level of resources that the user can can obtain in a given service-session. For the services that need resources limits (login for example) put a the following line in <tt>/etc/pam.conf</tt> as the last line for that service (usually after the pam_unix session line: <tscreen> <verb> # # Resource limits imposed on login sessions via pam_limits # login session required pam_limits.so </verb> </tscreen> </descrip>   <sect1>The list-file module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_listfile/ <tag><bf>Author:</bf></tag> Elliot Lee <tt><sopwith@cuc.edu></tt> <tag><bf>Maintainer:</bf></tag> Red Hat Software:<newline> Michael K. Johnson <johnsonm@redhat.com> 1996/11/18<newline> (if unavailable, contact Elliot Lee <sopwith@cuc.edu>). <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> clean <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module The list-file module provides a way to deny or allow services based on an arbitrary file. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt>onerr=succeed|fail</tt>; <tt>sense=allow|deny</tt>; <tt>file=</tt><it>filename</it>; <tt>item=user|tty|rhost|ruser|group|shell</tt> <tt>apply=user|@group</tt> <tt>quiet</tt> <tag><bf>Description:</bf></tag> The module gets the item of the type specified -- <tt>user</tt> specifies the username, <tt>PAM_USER</tt>; tty specifies the name of the terminal over which the request has been made, <tt>PAM_TTY</tt>; rhost specifies the name of the remote host (if any) from which the request was made, <tt>PAM_RHOST</tt>; and ruser specifies the name of the remote user (if available) who made the request, <tt>PAM_RUSER</tt> -- and looks for an instance of that item in the file <it>filename</it>. <it>filename</it> contains one line per item listed. If the item is found, then if <tt>sense=allow</tt>, <tt>PAM_SUCCESS</tt> is returned, causing the authorization request to succeed; else if <tt>sense=deny</tt>, <tt>PAM_AUTH_ERR</tt> is returned, causing the authorization request to fail. If an error is encountered (for instance, if <it>filename</it> does not exist, or a poorly-constructed argument is encountered), then if <tt>onerr=succeed</tt>, <tt>PAM_SUCCESS</tt> is returned, otherwise if <tt>onerr=fail</tt>, <tt>PAM_AUTH_ERR</tt> or <tt>PAM_SERVICE_ERR</tt> (as appropriate) will be returned. An additional argument, <tt>apply=</tt>, can be used to restrict the application of the above to a specific user (<tt>apply=</tt>username) or a given group (<tt>apply=@</tt>groupname). This added restriction is only meaningful when used with the <tt/tty/, <tt/rhost/ and <tt/shell/ <em/items/. Besides this last one, all arguments should be specified; do not count on any default behavior, as it is subject to change. The one exception is the <tt>quiet</tt> options, which reduces the amount of logging for non-fatal errors. No credentials are awarded by this module. <tag><bf>Examples/suggested usage:</bf></tag> Classic ``ftpusers'' authentication can be implemented with this entry in <tt>/etc/pam.conf</tt>: <tscreen> <verb> # # deny ftp-access to users listed in the /etc/ftpusers file # ftp auth required pam_listfile.so \ onerr=succeed item=user sense=deny file=/etc/ftpusers </verb> </tscreen> Note, users listed in <tt>/etc/ftpusers</tt> file are (counterintuitively) <bf/not/ allowed access to the ftp service. To allow login access only for certain users, you can use an pam.conf entry like this: <tscreen> <verb> # # permit login to users listed in /etc/loginusers # login auth required pam_listfile.so \ onerr=fail item=user sense=allow file=/etc/loginusers </verb> </tscreen> For this example to work, all users who are allowed to use the login service should be listed in the file <tt>/etc/loginusers</tt>. Unless you are explicitly trying to lock out root, make sure that when you do this, you leave a way for root to log in, either by listing root in <tt>/etc/loginusers</tt>, or by listing a user who is able to <em/su/ to the root account. </descrip>   <sect1>The mail module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_mail/ <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@linux.kernel.org> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> Authentication (credential) Session (open) <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> Default mail directory <tt>/var/spool/mail/</tt> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module looks at the user's mail directory and indicates whether the user has any mail in it. <sect2>Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/dir=/<em/direcory-name/; <tt/nopen/; <tt/close/; <tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/; <tt/quiet/; <tag><bf>Description:</bf></tag> This module provides the ``you have new mail'' service to the user. It can be plugged into any application that has credential hooks. It gives a single message indicating the <em/newness/ of any mail it finds in the user's mail folder. This module also sets the <bf/Linux-PAM/ environment variable, <tt/MAIL/, to the user's mail directory. The behavior of this module can be modified with one of the following flags: <itemize> <item><tt/debug/ - write more information to <tt/syslog(3)/. <item><tt/dir=/<em/pathname/ - look for the users' mail in an alternative directory given by <em/pathname/. The default location for mail is <tt>/var/spool/mail</tt>. Note, if the supplied <em/pathname/ is prefixed by a `<tt/˜/', the directory is interpreted as indicating a file in the user's home directory. <item><tt/nopen/ - instruct the module to <em/not/ print any mail information when the user's credentials are acquired. This flag is useful to get the <tt/MAIL/ environment variable set, but to not display any information about it. <item><tt/close/ - instruct the module to indicate if the user has any mail at the as the user's credentials are revoked. <item><tt/noenv/ - do not set the <tt/MAIL/ environment variable. <item><tt/empty/ - indicate that the user's mail directory is empty if this is found to be the case. <item><tt/hash=/<em/hashcount/ - mail directory hash depth. For example, a <em/hashcount/ of 2 would make the mailfile be <tt>/var/spool/mail/u/s/user</tt>. <item><tt/standard/ - old style "You have..." format which doesn't show the mail spool being used. this also implies "empty" <item><tt/quiet/ - only report when there is new mail. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> This module can be used to indicate that the user has new mail when they <em/login/ to the system. Here is a sample entry for your <tt>/etc/pam.conf</tt> file: <tscreen> <verb> # # do we have any mail? # login session optional pam_mail.so </verb> </tscreen> Note, some applications may perform this function themselves. In such cases, this module is not necessary. </descrip> <sect2>Authentication compent Then authentication companent works the same as the session component, expect that everything is done during the pam_setcred() phase.   <sect1>Create home directories on initial login <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_mkhomedir/ <tag><bf>Author:</bf></tag> Jason Gunthorpe <jgg@ualberta.ca> <tag><bf>Maintainer:</bf></tag> Ben Collins <bcollins@debian.org> <tag><bf>Management groups provided:</bf></tag> Session <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module Creates home directories on the fly for authenticated users. <sect2>Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/skel=skeleton-dir/; <tt/umask=octal-umask/; <tag><bf>Description:</bf></tag> This module is useful for distributed systems where the user account is managed in a central database (such as NIS, NIS+, or LDAP) and accessed through miltiple systems. It frees the administrator from having to create a default home directory on each of the systems by creating it upon the first succesfully authenticated login of that user. The skeleton directory (usually /etc/skel/) is used to copy default files and also set's a umask for the creation. The behavior of this module can be modified with one of the following flags: <itemize> <item><tt/skel/ - The skeleton directory for default files to copy to the new home directory. <item><tt/umask/ - An octal for of the same format as you would pass to the shells umask command. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 </descrip>   <sect1>Output the motd file <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_motd/ <tag><bf>Author:</bf></tag> Ben Collins <bcollins@debian.org> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> Session (open) <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module outputs the motd file (/etc/motd by default) upon succesful login. <sect2>Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/motd=motd-file-name/; <tag><bf>Description:</bf></tag> This module allows you to have arbitrary motd's (message of the day) output after a succesful login. By default this file is /etc/motd, but is configurable to any file. The behavior of this module can be modified with one of the following flags: <itemize> <item><tt/motd/ - the file to output if not using the default. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> login session pam_motd.so motd=/etc/motd </descrip>   <sect1>The no-login module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_nologin/ <tag><bf>Author:</bf></tag> Written by Michael K. Johnson <johnsonm@redhat.com><newline> (based on code taken from a module written by Andrew G. Morgan <morgan@parc.power.net>). <tag><bf>Maintainer:</bf></tag> Michael K. Johnson <johnsonm@redhat.com> <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> 1 warning about dropping const <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module Provides standard Unix <em/nologin/ authentication. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> Provides standard Unix <em/nologin/ authentication. If the file <tt>/etc/nologin</tt> exists, only root is allowed to log in; other users are turned away with an error message. All users (root or otherwise) are shown the contents of <tt>/etc/nologin</tt>. If the file <tt>/etc/nologin</tt> does not exist, this module succeeds silently. <tag><bf>Examples/suggested usage:</bf></tag> In order to make this module effective, all login methods should be secured by it. It should be used as a <tt>required</tt> method listed before any <tt>sufficient</tt> methods in order to get standard Unix nologin semantics. </descrip>   <sect1>The promiscuous module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> pam_permit <tag><bf>Author:</bf></tag> Andrew G. Morgan, <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> Linux-PAM maintainer. <tag><bf>Management groups provided:</bf></tag> account; authentication; password; session <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> VERY LOW. Use with extreme caution. <tag><bf>Clean code base:</bf></tag> Clean. <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module is very dangerous. It should be used with extreme caution. Its action is always to permit access. It does nothing else. <sect2>Account+Authentication+Password+Session components <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> No matter what management group, the action of this module is to simply return <tt/PAM_SUCCESS/ -- operation successful. In the case of authentication, the user's name will be acquired. Many applications become confused if this name is unknown. <tag><bf>Examples/suggested usage:</bf></tag> It is seldom a good idea to use this module. However, it does have some legitimate uses. For example, if the system-administrator wishes to turn off the account management on a workstation, and at the same time continue to allow logins, then she might use the following configuration file entry for login: <tscreen> <verb> # # add this line to your other login entries to disable account # management, but continue to permit users to log in... # login account required pam_permit.so </verb> </tscreen> </descrip>   <sect1>The rhosts module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_rhosts_auth/ <tag><bf>Author:</bf></tag> Al Longyear <longyear@netcom.com> <tag><bf>Maintainer:</bf></tag> <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> Clean. <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> Standard <tt/inet_addr()/, <tt/gethostbyname()/ function calls. </descrip> <sect2>Overview of module This module performs the standard network authentication for services, as used by traditional implementations of <em/rlogin/ and <em/rsh/ etc. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/no_hosts_equiv/; <tt/no_rhosts/; <tt/debug/; <tt/no_warn/; <tt/privategroup/; <tt/promiscuous/; <tt/suppress/ <tag><bf>Description:</bf></tag> The authentication mechanism of this module is based on the contents of two files; <tt>/etc/hosts.equiv</tt> (or <tt/_PATH_HEQUIV/ in <tt>#include <netdb.h></tt>) and <tt>~/.rhosts</tt>. Firstly, hosts listed in the former file are treated as equivalent to the localhost. Secondly, entries in the user's own copy of the latter file is used to map "<tt/remote-host remote-user/" pairs to that user's account on the current host. Access is granted to the user if their host is present in <tt>/etc/hosts.equiv</tt> and their remote account is identical to their local one, or if their remote account has an entry in their personal configuration file. Some restrictions are applied to the attributes of the user's personal configuration file: it must be a regular file (as defined by <tt/S_ISREG(x)/ of POSIX.1); it must be owned by the <em/superuser/ or the user; it must not be writable by any user besides its owner. The module authenticates a remote user (internally specified by the item <tt/PAM_RUSER/) connecting from the remote host (internally specified by the item <tt/PAM_RHOST/). Accordingly, for applications to be compatible this authentication module they must set these items prior to calling <tt/pam_authenticate()/. The module is not capable of independently probing the network connection for such information. In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is <em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option should be used. Instead, the superuser must have a correctly configured personal configuration file. The behavior of the module is modified by flags: <itemize> <item> <tt/debug/ - log more information to <tt/syslog(3)/. (XXX - actually, this module does not do any logging currently, please volunteer to fix this!) <item> <tt/no_warn/ - do not give verbal warnings to the user about failures etc. (XXX - this module currently does not issue any warnings, please volunteer to fix this!) <item> <tt/no_hosts_equiv/ - ignore the contents of the <tt>/etc/hosts.equiv</tt> file. <item> <tt/hosts_equiv_rootok/ - allow the use of <tt>/etc/hosts.equiv</tt> for superuser. Without this option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account. This option has no effect if the <tt>no_hosts_equiv</tt> option is used. <item> <tt/no_rhosts/ - ignore the contents of all user's personal configuration file <tt>~/.rhosts</tt>. <item> <tt/privategroup/ - normally, the <tt>~/.rhosts</tt> file must not be writable by anyone other than its owner. This option overlooks group write access in the case that the group owner of this file has the same name as the user being authenticated. To lessen the security problems associated with this option, the module also checks that the user is the only member of their private group. <item> <tt/promiscuous/ - A host entry of `+' will lead to all hosts being granted access. Without this option, '+' entries will be ignored. Note, that the <tt/debug/ option will syslog a warning in this latter case. <item> <tt/suppress/ - This will prevent the module from <tt/syslog(3)/ing a warning message when this authentication fails. This option is mostly for keeping logs free of meaningless errors, in particular when the module is used with the <tt/sufficient/ control flag. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> To allow users to login from trusted remote machines, you should try adding the following line to your <tt>/etc/pam.conf</tt> file <em/before/ the line that would otherwise prompt the user for a password: <tscreen> <verb> # # No passwords required for users from hosts listed above. # login auth sufficient pam_rhosts_auth.so no_rhosts </verb> </tscreen> Note, in this example, the system administrator has turned off all <em/personal/ <em/rhosts/ configuration files. Also note, that this module can be used to <em/only/ allow remote login from hosts specified in the <tt>/etc/host.equiv</tt> file, by replacing <tt/sufficient/ in the above example with <tt/required/. </descrip>   <sect1>The root access module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> pam_rootok <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> <bf>Linux-PAM</bf> maintainer <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> Clean. <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This module is for use in situations where the superuser wishes to gain access to a service without having to enter a password. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/ <tag><bf>Description:</bf></tag> This module authenticates the user if their <tt/uid/ is <tt/0/. Applications that are created <em/setuid/-root generally retain the <tt/uid/ of the user but run with the authority of an enhanced <em/effective-/<tt/uid/. It is the real <tt/uid/ that is checked. <tag><bf>Examples/suggested usage:</bf></tag> In the case of the <tt/su/ application the historical usage is to permit the superuser to adopt the identity of a lesser user without the use of a password. To obtain this behavior under <tt/Linux-PAM/ the following pair of lines are needed for the corresponding entry in the configuration file: <tscreen> <verb> # # su authentication. Root is granted access by default. # su auth sufficient pam_rootok.so su auth required pam_unix_auth.so </verb> </tscreen> Note. For programs that are run by the superuser (or started when the system boots) this module should not be used to authenticate users. </descrip>   <sect1>The securetty module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_securetty/ <tag><bf>Author[s]:</bf></tag> Elliot Lee <sopwith@cuc.edu> <tag><bf>Maintainer:</bf></tag> Red Hat Software:<newline> <em/currently/ Michael K. Johnson <johnsonm@redhat.com><newline> (if unavailable, contact Elliot Lee <sopwith@cuc.edu>). <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tt>/etc/securetty</tt> file <tag><bf>Network aware:</bf></tag> Requires the application to fill in the <tt>PAM_TTY</tt> item correctly in order to act meaningfully. </descrip> <sect2>Overview of module Provides standard Unix securetty checking. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> Provides standard Unix securetty checking, which causes authentication for root to fail unless <tt>PAM_TTY</tt> is set to a string listed in the <tt>/etc/securetty</tt> file. For all other users, it succeeds. <tag><bf>Examples/suggested usage:</bf></tag> For canonical usage, should be listed as a <tt>required</tt> authentication method before any <tt>sufficient</tt> authentication methods. </descrip>   <sect1>Time control <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_time/ <tag><bf>Author:</bf></tag> Andrew G. Morgan <tt><morgan@parc.power.net></tt> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> account <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> Requires a configuration file <tt>/etc/security/time.conf</tt> <tag><bf>Network aware:</bf></tag> Through the <tt/PAM_TTY/ item only </descrip> <sect2>Overview of module Running a well regulated system occasionally involves restricting access to certain services in a selective manner. This module offers some time control for access to services offered by a system. Its actions are determined with a configuration file. This module can be configured to deny access to (individual) users based on their name, the time of day, the day of week, the service they are applying for and their terminal from which they are making their request. <sect2>Account component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> This module bases its actions on the rules listed in its configuration file: <tt>/etc/security/pam.conf</tt>. Each rule has the following form, <tscreen> <em/services/<tt/;/<em/ttys/<tt/;/<em/users/<tt/;/<em/times/ </tscreen> In words, each rule occupies a line, terminated with a newline or the beginning of a comment; a `<tt/#/'. It contains four fields separated with semicolons, `<tt/;/'. The fields are as follows: <itemize> <item><em/services/ - a logic list of service names that are affected by this rule. <item><em/ttys/ - a logic list of terminal names indicating those terminals covered by the rule. <item><em/user/ - a logic list of usernames to which this rule applies By a logic list we mean a sequence of tokens (associated with the appropriate <tt/PAM_/ item), containing no more than one wildcard character; `<tt/*/', and optionally prefixed with a negation operator; `<tt/!/'. Such a sequence is concatenated with one of two logical operators: <tt/&/ (logical AND) and <tt/|/ (logical OR). Two examples are: <tt>!morgan&!root</tt>, indicating that this rule does not apply to the user <tt>morgan</tt> nor to <tt>root</tt>; and <tt>tty*&!ttyp*</tt>, which indicates that the rule applies only to console terminals but not pseudoterminals. <item><em/times/ - a logic list of times at which this rule applies. The format of each element is a day/time-range. The days are specified by a sequence of two character entries. For example, <tt/MoTuSa/, indicates Monday Tuesday and Saturday. Note that repeated days are <em/unset/; <tt/MoTuMo/ indicates Tuesday, and <tt/MoWk/ means all weekdays bar Monday. The two character combinations accepted are, <tscreen> <verb> Mo Tu We Th Fr Sa Su Wk Wd Al </verb> </tscreen> The last two of these being <em/weekend/ days and <em/all 7 days/ of the week respectively. The time range part is a pair of 24-hour times, <em/HHMM/, separated by a hyphen -- indicating the start and finish time for the rule. If the finsish time is smaller than the start time, it is assumed to apply on the following day. For an example, <tt/Mo1800-0300/ indicates that the permitted times are Monday night from 6pm to 3am the following morning. </itemize> Note, that the given time restriction is only applied when the first three fields are satisfied by a user's application for service. For convenience and readability a rule can be extended beyond a single line with a `<tt>\</tt><em/newline/'. <tag><bf>Examples/suggested usage:</bf></tag> The use of this module is initiated with an entry in the <bf/Linux-PAM/ configuration file of the following type: <tscreen> <verb> # # apply pam_time accounting to login requests # login account required pam_time.so </verb> </tscreen> where, here we are applying the module to the <em/login/ application. Some examples of rules that can be placed in the <tt>/etc/security/time.conf</tt> configuration file are the following: <descrip> <tag><tt>login ; tty* & ; !ttyp* ; !root ; !Al0000-2400</tt></tag> all users except for <tt/root/ are denied access to console-login at all times. <tag><tt>games ; * ; !waster ; Wd0000-2400 | Wk1800-0800</tt></tag> games (configured to use Linux-PAM) are only to be accessed out of working hours. This rule does not apply to the user <tt/waster/. </descrip> Note, currently there is no daemon enforcing the end of a session. This needs to be remedied. Poorly formatted rules are logged as errors using <tt/syslog(3)/. </descrip>   <sect1>The Unix Password module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> pam_unix <tag><bf>Author:</bf></tag> <tag><bf>Maintainer:</bf></tag> Authors. <tag><bf>Management groups provided:</bf></tag> account; authentication; password; session <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module This is the standard Unix authentication module. It uses standard calls from the system's libraries to retrieve and set account information as well as authentication. Usually this is obtained from the /etc/passwd and the /etc/shadow file aswell if shadow is enabled. <sect2>Account component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/audit/ <tag><bf>Description:</bf></tag> The <tt/debug/ argument makes the accounting functions of this module <tt/syslog(3)/ more information on its actions. (Remaining arguments supported by the other functions of this module are silently ignored, but others are logged as errors through <tt/syslog(3)/). The <tt/audit/ argument causes even more logging. Based on the following <tt/shadow/ elements: <tt/expire/; <tt/last_change/; <tt/max_change/; <tt/min_change/; <tt/warn_change/, this module performs the task of establishing the status of the user's account and password. In the case of the latter, it may offer advice to the user on changing their password or, through the <tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until they have established a new password. The entries listed above are documented in the <em/GNU Libc/ info documents. Should the user's record not contain one or more of these entries, the corresponding <em/shadow/ check is not performed. <tag><bf>Examples/suggested usage:</bf></tag> In its accounting mode, this module can be inserted as follows: <tscreen> <verb> # # Ensure users account and password are still active # login account required pam_unix.so </verb> </tscreen> </descrip> <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/audit/; <tt/use_first_pass/; <tt/try_first_pass/; <tt/nullok/; <tt/nodelay/ <tag><bf>Description:</bf></tag> The <tt/debug/ argument makes the authentication functions of this module <tt/syslog(3)/ more information on its actions. The <tt/audit/ causes even more information to be logged. The default action of this module is to not permit the user access to a service if their <em/official/ password is blank. The <tt/nullok/ argument overrides this default. When given the argument <tt/try_first_pass/, before prompting the user for their password, the module first tries the previous stacked <tt/auth/-module's password in case that satisfies this module as well. The argument <tt/use_first_pass/ forces the module to use such a recalled password and will never prompt the user - if no password is available or the password is not appropriate, the user will be denied access. The argument, <tt>nodelay</tt>, can be used to discourage the authentication component from requesting a delay should the authentication as a whole fail. The default action is for the module to request a delay-on-failure of the order of one second. Remaining arguments, supported by the other functions of this module, are silently ignored. Other arguments are logged as errors through <tt/syslog(3)/. A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's password when it is stored in a read protected database. This binary is very simple and will only check the password of the user invoking it. It is called transparently on behalf of the user by the authenticating component of this module. In this way it is possible for applications like xlock to work without being setuid-root. <tag><bf>Examples/suggested usage:</bf></tag> The correct functionality of this module is dictated by having an appropriate <tt>/etc/nsswitch.conf</tt> file, the user databases specified there dictate the source of the authenticated user's record. In its authentication mode, this module can be inserted as follows: <tscreen> <verb> # # Authenticate the user # login auth required pam_unix.so </verb> </tscreen> </descrip> <sect2>Password component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/audit/; <tt/nullok/; <tt/not_set_pass/; <tt/use_authtok/; <tt/try_first_pass/; <tt/use_first_pass/; <tt/md5/; <tt/bigcrypt/; <tt/shadow/; <tt/nis/; <tt/min/; <tt/max/; <tt/obscure/; <tt/remember/ <tag><bf>Description:</bf></tag> This part of the <tt/pam_unix/ module performs the task of updating the user's password. In the case of conventional unix databases (which store the password encrypted) the <tt/md5/ argument is used to do the encryption with the MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call. As an alternative to this, the <tt/bigcrypt/ argument can be used to encrypt more than the first 8 characters of a password with DEC's (Digital Equipment Cooperation) `C2' extension to the standard UNIX <tt/crypt()/ algorithm. The <tt/nullok/ argument is used to permit the changing of a password <em/from/ an empty one. Without this argument, empty passwords are treated as account-locking ones. The argument <tt/use_first_pass/ is used to lock the choice of old and new passwords to that dictated by the previously stacked <tt/password/ module. The <tt/try_first_pass/ argument is used to avoid the user having to re-enter an old password when <tt/pam_unix/ follows a module that possibly shared the user's old password - if this old password is not correct the user will be prompted for the correct one. The argument <tt/use_authtok/ is used to <em/force/ this module to set the new password to the one provided by the previously stacked <tt/password/ module (this is used in an example of the stacking of the <em/Cracklib/ module documented above). The <tt/not_set_pass/ argument is used to inform the module that it is not to pay attention to/make available the old or new passwords from/to other (stacked) password modules. The <tt/debug/ argument makes the password functions of this module <tt/syslog(3)/ more information on its actions. Other arguments may be logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes even more information to be logged. With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC for setting new passwords. The <tt/remember/ argument takes one value. This is the number of most recent passwords to save for each user. These are saved in <tt>/etc/security/opasswd</tt> in order to force password change history and keep the user from alternating between the same password too frequently. The <tt/min/ and <tt/max/ options allow control over the length of the password. These have a hard coded default of 1 and 8. The values are inclusive. The <tt/obscure/ option enables some extra checks on the password. These is taken after the same obscure checks enabled in the original shadow package. This works very similar to the pam_cracklib module and implements these checks (it does not implement dictionary checks): <itemize> <item> <bf/Palindrome/ - Is the new password a palindrome of the old one? A palindrome is where the words read the same backwards and forwards (eg. madam and radar). <item> <bf/Case Change Only/ - Is the new password the the old one with only a change of case? <item> <bf/Similar/ - Is the new password too much like the old one? <item> <bf/Simple/ - Is the new password too small? This is based on the length of the password and the number of different types of characters used (ie.alpha, numeric...). <item> <bf/Rotated/ - Is the new password a rotated version of the old password (eg. "billy" and "illyb")? </itemize> <tag><bf>Examples/suggested usage:</bf></tag> Standard usage: <tscreen> <verb> # # Change the users password # passwd password required pam_unix.so </verb> </tscreen> An example of the stacking of this module with respect to the pluggable password checking module, <tt/pam_cracklib/: <tscreen> <verb> # # Change the users password # passwd password required pam_cracklib.so retry=3 minlen=6 difok=3 passwd password required pam_unix.so use_authtok nullok md5 </verb> </tscreen> </descrip> <sect2>Session component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> No arguments are recognized by this module component. Its action is simply to log the username and the service-type to <tt/syslog(3)/. Messages are logged at the beginning and end of the user's session. <tag><bf>Examples/suggested usage:</bf></tag> The use of the session modules is straightforward: <tscreen> <verb> # # session opening and closing # login session required pam_unix.so </verb> </tscreen> </descrip>   <sect1>The userdb module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_userdb/ <tag><bf>Author:</bf></tag> Cristian Gafton <gafton@redhat.com> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> Requires Berkeley DB. <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module Look up users in a .db database and verify their password against what is contained in that database. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/icase/; <tt/dump/; <tt/db=XXXX/; <tag><bf>Description:</bf></tag> This module is used to verify a username/password pair against values stored in a Berkeley DB database. The database is indexed by the username, and the data fields corresponding to the username keys are the passwords, in unencrypted form, so caution must be exercised over the access rights to the DB database itself.. The module will read the password from the user using the conversation mechanism. If you are using this module on top of another authetication module (like <tt/pam_unix/;) then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module. The action of the module may be modified from this default by one or more of the following flags in the <tt>/etc/pam.d/<service></tt> file. <itemize> <item> <tt/debug/ - Supply more debugging information to <tt/syslog(3)/. <item> <tt/icase/ - Perform the password comparisons case insensitive. <item> <tt/dump/ - dump all the entries in the database to the log (eek, don't do this by default!) <item> <tt/db=XXXX/ - use the database found on pathname XXXX. Note that Berkeley DB usually adds the needed filename extension for you, so you should use something like <tt>/etc/foodata</tt> instead of <tt>/etc/foodata.db</tt>. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt> on most systems) that will accept for login users whose username/password pairs are provided in the <tt>/tmp/dbtest.db</tt> file: <tscreen> <verb> #%PAM-1.0 auth required pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed auth sufficient pam_userdb.so icase db=/tmp/dbtest auth required pam_unix.so shadow nullok try_first_pass auth required pam_shells.so account required pam_unix.so session required pam_unix.so </verb> </tscreen> </descrip>   <sect1>Warning logger module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_warn/ <tag><bf>Author:</bf></tag> Andrew G. Morgan <morgan@parc.power.net> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> authentication; password <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> logs information about the remote user and host (if pam-items are known) </descrip> <sect2>Overview of module This module is principally for logging information about a proposed authentication or application to update a password. <sect2>Authentication+Password component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tag><bf>Description:</bf></tag> Log the service, terminal, user, remote user and remote host to <tt/syslog(3)/. The items are not probed for, but instead obtained from the standard pam-items. <tag><bf>Examples/suggested usage:</bf></tag> an example is provided in the configuration file section <ref id="configuration" name="above">. </descrip>   <sect1>The wheel module <sect2>Synopsis <descrip> <tag><bf>Module Name:</bf></tag> <tt/pam_wheel/ <tag><bf>Author:</bf></tag> Cristian Gafton <gafton@redhat.com> <tag><bf>Maintainer:</bf></tag> Author. <tag><bf>Management groups provided:</bf></tag> authentication <tag><bf>Cryptographically sensitive:</bf></tag> <tag><bf>Security rating:</bf></tag> <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> <tag><bf>Network aware:</bf></tag> </descrip> <sect2>Overview of module Only permit root access to members of the wheel (<tt/gid=0/) group. <sect2>Authentication component <descrip> <tag><bf>Recognized arguments:</bf></tag> <tt/debug/; <tt/trust/; <tt/deny/; <tt/group=XXXX/ <tag><bf>Description:</bf></tag> This module is used to enforce the so-called <em/wheel/ group. By default, it permits root access to the system if the applicant user is a member of the <tt/wheel/ group (first, the module checks for the existence of a '<tt/wheel/' group. Otherwise the module defines the group with group-id <tt/0/ to be the <em/wheel/ group). The action of the module may be modified from this default by one or more of the following flags in the <tt>/etc/pam.conf</tt> file. <itemize> <item> <tt/debug/ - Supply more debugging information to <tt/syslog(3)/. <item> <tt/trust/ - This option instructs the module to return <tt/PAM_SUCCESS/ should it find the user applying for root privilege is a member of the wheel group. The default action is to return <tt/PAM_IGNORE/ in this situation. By using the <tt/trust/ option it is possible to arrange for <tt/wheel/-group members to become root without typing a password. <bf/USE WITH CARE/. <item> <tt/deny/ - This is used to reverse the logic of the module's behavior. If the user is trying to get <tt/uid=0/ access and is a member of the wheel group, deny access (for the wheel group, this is perhaps nonsense!): it is intended for use in conjunction with the <tt/group=/ argument... <item> <tt/group=XXXX/ - Instead of checking the <tt/gid=0/ group, use the user's <tt/XXXX/ group membership for the authentication. Here, <tt/XXXX/ is the name of the group and <bf/not/ its numeric identifier. </itemize> <tag><bf>Examples/suggested usage:</bf></tag> To restrict access to superuser status to the members of the <tt/wheel/ group, use the following entries in your configuration file: <tscreen> <verb> # # root gains access by default (rootok), only wheel members can # become root (wheel) but Unix authenticate non-root applicants. # su auth sufficient pam_rootok.so su auth required pam_wheel.so su auth required pam_unix_auth.so </verb> </tscreen> </descrip> <bf>NOTE</bf>: In this context, being a member of a group means that the user is listed as a member in the /etc/groups file. The pam-wheel module does not check the users primary group (the one listed in their /etc/passwd entry).  <sect>Files <descrip> <tag><tt>/usr/lib/libpam.so.*</tt></tag> the shared library providing applications with access to <bf/Linux-PAM/. <tag><tt>/etc/pam.conf</tt></tag> the <bf/Linux-PAM/ configuration file. <tag><tt>/usr/lib/security/pam_*.so</tt></tag> the primary location for <bf/Linux-PAM/ dynamically loadable object files; the modules. </descrip> <sect>See also<label id="see-also-sec"> <itemize> <item>The <bf/Linux-PAM/ Application Writers' Guide. <item>The <bf/Linux-PAM/ Module Writers' Guide. <item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request For Comments 86.0, October 1995. See this url: <tt><htmlurl url="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt" name="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt"></tt> </itemize> <sect>Notes I intend to put development comments here... like ``at the moment this isn't actually supported''. At release time what ever is in this section will be placed in the Bugs section below! :) Are we going to be able to support the <tt/use_mapped_pass/ module argument? Anyone know a cheap (free) good lawyer?! <itemize> <item> This issue may go away, as Sun have investigated adding a new management group for mappings. In this way, libpam would have mapping modules that could securely store passwords using strong cryptography and in such a way that they need not be distributed with Linux-PAM. </itemize> <sect>Author/acknowledgments This document was written by Andrew G. Morgan (morgan@linux.kernel.org) with many contributions from   Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger, Craig S. Bell, Derrick J. Brashear, Ben Buxton, Seth Chaiklin, Oliver Crow, Chris Dent, Marc Ewing, Cristian Gafton, Emmanuel Galanos, Brad M. Garcia, Eric Hester, Roger Hu, Eric Jacksch, Michael K. Johnson, David Kinchlea, Olaf Kirch, Marcin Korzonek, Stephen Langasek, Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton, Al Longyear, Ingo Luetkebohle, Marek Michalkiewicz, Robert Milkowski, Aleph One, Martin Pool, Sean Reifschneider, Jan Rekorajski, Erik Troan, Theodore Ts'o, Jeff Uphoff, Myles Uyema, Savochkin Andrey Vladimirovich, Ronald Wahl, David Wood, John Wilmes, Joseph S. D. Yao and Alex O. Yuriev. Thanks are also due to Sun Microsystems, especially to Vipin Samar and Charlie Lai for their advice. At an early stage in the development of <bf/Linux-PAM/, Sun graciously made the documentation for their implementation of PAM available. This act greatly accelerated the development of <bf/Linux-PAM/. <sect>Bugs/omissions More PAM modules are being developed all the time. It is unlikely that this document will ever be truely up to date! This manual is unfinished. Only a partial list of people is credited for all the good work they have done. <sect>Copyright information for this document Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. <newline> Email: <tt><morgan@linux.kernel.org></tt> Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: <itemize> <item> 1. Redistributions of source code must retain the above copyright notice, and the entire permission notice in its entirety, including the disclaimer of warranties. <item> 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. <item> 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. </itemize> <bf/Alternatively/, this product may be distributed under the terms of the GNU General Public License (GPL), in which case the provisions of the GNU GPL are required <bf/instead of/ the above restrictions. (This clause is necessary due to a potential bad interaction between the GNU GPL and the restrictions contained in a BSD-style copyright.) THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <tt>$Id: pam_source.sgml,v 1.9 1999/11/08 05:09:17 morgan Exp $</tt> </article>