From 1eb81c19d5c4181242bf983ed0c640b652c2e415 Mon Sep 17 00:00:00 2001 From: "Andrew G. Morgan" Date: Mon, 19 Mar 2001 01:46:41 +0000 Subject: Relevant BUGIDs: 408961 Purpose of commit: documentation fixes Commit summary: --------------- This checkin is courtesy of some fixes from Michel D'HOOGE. --- CHANGELOG | 1 + doc/CREDITS | 1 + doc/modules/pam_env.sgml | 14 ++++++------ doc/modules/pam_filter.sgml | 4 ++-- doc/modules/pam_ftp.sgml | 2 +- doc/modules/pam_limits.sgml | 6 ++--- doc/modules/pam_listfile.sgml | 4 ++-- doc/modules/pam_mail.sgml | 4 ++-- doc/modules/pam_motd.sgml | 4 ++-- doc/modules/pam_pwdb.sgml | 4 ++-- doc/modules/pam_radius.sgml | 4 ++-- doc/modules/pam_time.sgml | 2 +- doc/modules/pam_unix.sgml | 3 +-- doc/pam_appl.sgml | 51 ++++++++++++++++++++++++------------------- doc/pam_source.sgml | 14 ++++++------ 15 files changed, 62 insertions(+), 56 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 9bec8693..079408f1 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -50,6 +50,7 @@ libpam. Prior versions were buggy - see bugfix for Bug 129775. ** WARNING ** +* Michel D'HOOGE submitted documentation fixes (Bug 408961 - agmorgan) * fix for module linking directions (Bug 133545 - agmorgan) * fix for glibc-2.2.2 compilation of pam_issue (Bug 133542 - agmorgan) * fix pam_userdb to make and link both .o files it needs - converse() diff --git a/doc/CREDITS b/doc/CREDITS index 059bb5f2..df0eb599 100644 --- a/doc/CREDITS +++ b/doc/CREDITS @@ -17,6 +17,7 @@ Cristian Gafton, Emmanuel Galanos, Brad M. Garcia, Eric Hester, +Michel D'Hooge, Roger Hu, Eric Jacksch, Michael K. Johnson, diff --git a/doc/modules/pam_env.sgml b/doc/modules/pam_env.sgml index 8057b38d..d795d591 100644 --- a/doc/modules/pam_env.sgml +++ b/doc/modules/pam_env.sgml @@ -51,7 +51,7 @@ is the use of previously set environment variables as well as Recognized arguments: Description: This module allows you to (un)set arbitrary environment variables @@ -61,9 +61,9 @@ and/or All is controlled via a configuration file (by default, /etc/security/pam_env.conf but can be overriden with -connfile argument). Each line starts with the variable name, +conffile argument). Each line starts with the variable name, there are then two possible options for each variable DEFAULT -and OVERRIDE. DEFAULT allows and administrator to +and OVERRIDE. DEFAULT allows an administrator to set the value of the variable to some default value, if none is supplied then the empty string is assumed. The OVERRIDE option tells pam_env that it should enter in its value (overriding the @@ -89,10 +89,10 @@ space is needed the full value must be delimited by the quotes and embedded or escaped quotes are not supported.

-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 KEY=VAL pairs +on seperate lines (/etc/environment by default). You can +change the default file to parse, with the The behavior of this module can be modified with one of the following diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml index 598279b8..2bd97c09 100644 --- a/doc/modules/pam_filter.sgml +++ b/doc/modules/pam_filter.sgml @@ -100,8 +100,8 @@ the filter might expect.

Permitted values for Note, the use of -For the services that need resources limits (login for example) put a +For the services that need resources limits (login for example) put the following line in /etc/pam.conf as the last line for that service (usually after the pam_unix session line: diff --git a/doc/modules/pam_listfile.sgml b/doc/modules/pam_listfile.sgml index 98589a3b..3754f57e 100644 --- a/doc/modules/pam_listfile.sgml +++ b/doc/modules/pam_listfile.sgml @@ -111,8 +111,8 @@ Note, users listed in /etc/ftpusers file are (counterintuitively) -To allow login access only for certain users, you can use an -pam.conf entry like this: +To allow login access only for certain users, you can use a + # diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml index a7698d3a..c1ed7a87 100644 --- a/doc/modules/pam_mail.sgml +++ b/doc/modules/pam_mail.sgml @@ -49,7 +49,7 @@ whether the user has any mail in it. Recognized arguments: - -Authentication compent +Authentication component

Then authentication companent works the same as the session component, diff --git a/doc/modules/pam_motd.sgml b/doc/modules/pam_motd.sgml index 1f8fc393..8ddc6392 100644 --- a/doc/modules/pam_motd.sgml +++ b/doc/modules/pam_motd.sgml @@ -38,8 +38,8 @@ Session (open) Overview of module

-This module outputs the motd file (/etc/motd by default) upon succesful -login. +This module outputs the motd file (/etc/motd by default) upon +successful login. Session component diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml index 022cfe57..84873356 100644 --- a/doc/modules/pam_pwdb.sgml +++ b/doc/modules/pam_pwdb.sgml @@ -1,7 +1,7 @@ The Password-Database module @@ -16,7 +16,7 @@ pam_pwdb Author: Cristian Gafton <gafton@redhat.com> -and Andrew G. Morgan <morgan@linux.kernel.org> +and Andrew G. Morgan <morgan@kernel.org> Maintainer: Authors. diff --git a/doc/modules/pam_radius.sgml b/doc/modules/pam_radius.sgml index fb442ee3..2bc4a9cd 100644 --- a/doc/modules/pam_radius.sgml +++ b/doc/modules/pam_radius.sgml @@ -44,7 +44,7 @@ yes; this is a network module (independent of application).

This module is intended to provide the session service for users -autheticated with a RADIUS server. At the present stage, the only +authenticated with a RADIUS server. At the present stage, the only option supported is the use of the RADIUS server as an accounting server. @@ -60,7 +60,7 @@ server. Description: This module is intended to provide the session service for users -autheticated with a RADIUS server. At the present stage, the only +authenticated with a RADIUS server. At the present stage, the only option supported is the use of the RADIUS server as an /etc/security/time.conf configuration file are the following: -login ; tty* & ; !ttyp* ; !root ; !Al0000-2400 +login ; tty* & !ttyp* ; !root ; !Al0000-2400 all users except for Author: Maintainer: -Authors. Management groups provided: account; authentication; password; session @@ -40,7 +39,7 @@ account; authentication; password; session 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. +and the /etc/shadow file as well if shadow is enabled. Account component diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml index 9149ecd5..a30dfd6f 100644 --- a/doc/pam_appl.sgml +++ b/doc/pam_appl.sgml @@ -4,7 +4,7 @@ $Id$ - Copyright (C) Andrew G. Morgan 1996-9. All rights reserved. + Copyright (C) Andrew G. Morgan 1996-2001. All rights reserved. Redistribution and use in source (sgml) and binary (derived) forms, with or without modification, are permitted provided that the @@ -46,7 +46,7 @@ DAMAGE. The Linux-PAM Application Developers' Guide <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.75 2001/02/04 +<date>DRAFT v0.75 2001/03/18 <abstract> This manual documents what an application developer needs to know about the <bf>Linux-PAM</bf> library. It describes how an application @@ -130,7 +130,7 @@ manage. In addition to authentication, PAM provides account management, credential management, session management and authentication-token (password changing) management services. It is important to realize when writing a PAM based application that these -services are provided in a manner that is <bf>transparent</bf> to the +services are provided in a manner that is <bf>transparent</bf> to the application. That is to say, when the application is written, no assumptions can be made about <em>how</em> the client will be authenticated. @@ -288,12 +288,16 @@ to cause a segmentation fault if accessed). <p> Under normal conditions the argument <tt/pam_status/ has the value -PAM_SUCCESS, but in the event of an unsuccessful service application -the approprite <bf/Linux-PAM/ error-return value should be used -here. -attempt its purpose is to be passed as an argument to the -module specific function <tt/cleanup()/ (see the <bf/Linux-PAM/ -<htmlurl url="pam_modules.html" name="Module Developers' Guide">). +PAM_SUCCESS, but in the event of an unsuccessful application for +service the appropriate <bf/Linux-PAM/ error-return value should be +used here. Note, <tt/pam_end()/ unconditionally shuts down the +authentication stack associated with the <tt/pamh/ handle. The value +taken by <tt/pam_status/ is used as an argument to the module specific +callback functions, <tt/cleanup()/ (see the <bf/Linux-PAM/ <htmlurl +url="pam_modules.html" name="Module Developers' Guide">). In this way, +the module can be given notification of the pass/fail nature of the +tear-down process, and perform any last minute tasks that are +appropriate to the module before it is unlinked. <sect2>Setting PAM items <label id="pam-set-item-section"> @@ -478,7 +482,7 @@ value when <bf/Linux-PAM/ returns control to the application. <p> For applications written with a single thread that are event driven in -nature, <tt/libpam/ generating this dalay may be undesirable. Instead, +nature, <tt/libpam/ generating this delay may be undesirable. Instead, the application may want to register the delay in some other way. For example, in a single threaded server that serves multiple authentication requests from a single event loop, the application @@ -646,7 +650,7 @@ this. In such cases, the user should be denied access until such time as they can update their password. <tag><tt/PAM_ACCT_EXPIRED/</tag> - The user is no longer permitted access to the system. + The user is no longer permitted to access the system. <tag><tt/PAM_AUTH_ERR/</tag> There was an authentication error. @@ -730,7 +734,7 @@ extern int pam_open_session(pam_handle_t *pamh, int flags); <p> This function is used to indicate that an authenticated session has -begun. It is used to inform the module that the user is currently in +begun. It is used to inform the modules that the user is currently in a session. It should be possible for the <bf>Linux-PAM</bf> library to open a session and close the same session (see section <ref id="pam-close-session-section" name="below">) from different @@ -757,14 +761,15 @@ extern int pam_close_session(pam_handle_t *pamh, int flags); <p> This function is used to indicate that an authenticated session has -ended. It is used to inform the module that the user is exiting a +ended. It is used to inform the modules that the user is exiting a session. It should be possible for the <bf>Linux-PAM</bf> library to open a session and close the same session from different applications. <p> -Currently, this function simply calls each of the corresponding -functions of the loaded modules. The only valid flag is -<tt/PAM_SILENT/ and this is, of course, <em/optional/. +This function simply calls each of the corresponding functions of the +loaded modules in the same order that they were invoked with +<tt/pam_open_session()/. The only valid flag is <tt/PAM_SILENT/ and +this is, of course, <em/optional/. <p> If any of the <em/required/ loaded modules are unable to close a @@ -801,7 +806,7 @@ setting. <tag>``<tt/NAME/''</tag> Without an `<tt/=/' the <tt/pam_putenv()/ function will delete the -correspoding variable from the <bf/Linux-PAM/ environment. +corresponding variable from the <bf/Linux-PAM/ environment. </descrip> @@ -982,7 +987,7 @@ to display some text. <p> Post Linux-PAM-0.59 (and in the interests of compatibility with -Sunsoft). The number of resposes is always equal to the <tt/num_msg/ +Sunsoft). The number of responses is always equal to the <tt/num_msg/ conversation function argument. This is slightly easier to program but does require that the response array is <tt/free(3)/'d after every call to the conversation function. The index of the responses @@ -1026,7 +1031,7 @@ generated. <p> PAM, from the perspective of an application, is a convenient API for authenticating users. PAM modules generally have no increased -privilege over that posessed by the application that is making use of +privilege over that possessed by the application that is making use of it. For this reason, the application must take ultimate responsibility for protecting the environment in which PAM operates. @@ -1335,7 +1340,7 @@ The following is extracted from an email. I'll tidy it up later. <p> The point of PAM is that the application is not supposed to have any -idea how the attatched authentication modules will choose to +idea how the attached authentication modules will choose to authenticate the user. So all they can do is provide a conversation function that will talk directly to the user(client) on the modules' behalf. @@ -1349,10 +1354,10 @@ point is that the retinal scanner is an ideal task for a "module". <p> While it is true that a pop-daemon program is designed with the POP -protocol in mind and no-one ever considered attatching a retinal +protocol in mind and no-one ever considered attaching a retinal scanner to it, it is also the case that the "clean" PAM'ification of such a daemon would allow for the possibility of a scanner module -being be attatched to it. The point being that the "standard" +being be attached to it. The point being that the "standard" pop-authentication protocol(s) [which will be needed to satisfy inflexible/legacy clients] would be supported by inserting an appropriate pam_qpopper module(s). However, having rewritten popd @@ -1373,7 +1378,7 @@ of the authentication procedure (how many passwords etc..) the exchange protocol (prefixes to prompts etc., numbers like 331 in the case of ftpd) and what is part of the service that the application delivers. PAM really needs to have total control in the -authentication "proceedure", the conversation function should only +authentication "procedure", the conversation function should only deal with reformatting user prompts and extracting responses from raw input. diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml index 4e1369ce..d24a53a3 100644 --- a/doc/pam_source.sgml +++ b/doc/pam_source.sgml @@ -4,7 +4,7 @@ $Id$ - Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. + Copyright (c) Andrew G. Morgan 1996-2001. All rights reserved. Redistribution and use in source (sgml) and binary (derived) forms, with or without modification, are permitted provided that the @@ -46,7 +46,7 @@ DAMAGE. <title>The Linux-PAM System Administrators' Guide <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.75 2001/02/07 +<date>DRAFT v0.75 2001/03/18 <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 @@ -140,10 +140,10 @@ command shell (<em>bash, tcsh, zsh, etc.</em>) running with the identity of the user. <p> -Traditinally, the former step is achieved by the <em/login/ +Traditionally, 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. +it agrees with that located on the system; hence verifying that +as 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/. <p> @@ -215,7 +215,7 @@ 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 +the order they appear in the configuration 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 @@ -577,7 +577,7 @@ next section. </descrip> <p> -Any line in (one of) the confiuration file(s), that is not formatted +Any line in (one of) the configuration 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)/. -- cgit v1.2.3