nss-pam-ldapd commit: r1117 - in nss-pam-ldapd: . man
[
Date Prev][
Date Next]
[
Thread Prev][
Thread Next]
nss-pam-ldapd commit: r1117 - in nss-pam-ldapd: . man
- From: "Commits of the nss-pam-ldapd project." <nss-pam-ldapd-commits [at] lists.arthurdejong.org>
- To: nss-pam-ldapd-commits [at] lists.arthurdejong.org
- Reply-to: nss-pam-ldapd-users [at] lists.arthurdejong.org
- Subject: nss-pam-ldapd commit: r1117 - in nss-pam-ldapd: . man
- Date: Sun, 23 May 2010 23:26:19 +0200 (CEST)
Author: arthur
Date: Sun May 23 23:26:16 2010
New Revision: 1117
URL: http://arthurdejong.org/viewvc/nss-pam-ldapd?view=rev&revision=1117
Log:
update documentation
Modified:
nss-pam-ldapd/HACKING
nss-pam-ldapd/README
nss-pam-ldapd/man/nslcd.8.xml
nss-pam-ldapd/man/nslcd.conf.5.xml
Modified: nss-pam-ldapd/HACKING
==============================================================================
--- nss-pam-ldapd/HACKING Sun May 23 22:11:40 2010 (r1116)
+++ nss-pam-ldapd/HACKING Sun May 23 23:26:16 2010 (r1117)
@@ -33,7 +33,7 @@
For building svn snapshots the following tools are needed:
-* autoconf (2.61 is used but 2.59 is minimal)
+* autoconf (2.65 is used but 2.61 is minimal)
* automake (1.11 is used)
and of course the usual build tools (gcc/make/etc). Also see debian/control
@@ -51,7 +51,7 @@
A new versioning scheme was chosen over the nss_ldap release scheme. The
scheme is a simple major.minor.micro numbering. Until a 1.0 release is made
the code will be considered work in progress. The interfaces may change and
-features may be added and removed.
+features may be added or removed.
GENERAL DESIGN
@@ -67,7 +67,7 @@
Both these parts translate the queries in a higher-level simple protocol used
to communicate with the nslcd daemon. This daemon translates the requests into
-LDAP searches. As a result the NSS and PAM modules don't need to known
+LDAP searches. As a result, the NSS and PAM modules don't need to known
anything about LDAP (in fact replacing it with another lookup method should be
very simple) and don't have to link with the LDAP libraries.
@@ -94,9 +94,9 @@
into files according to the database they support. Functions look like:
_nss_ldap_FUNCTION_r(...)
- This function opens the connection to the nslcd (with a time-out) builds the
- correct data structures and does a request (write()) to the nslcd waiting
- for an answer (again with a time-out)
+ This function opens the connection to the nslcd (with a time-out), builds
+ the correct data structures and does a request (write()) to the nslcd
+ waiting for an answer (again with a time-out)
The complete list of exported functions can be found in exports.linux and
prototypes.h. The NSS interface seems to be fairly libc-specific and is
@@ -108,7 +108,6 @@
the NSS-specific stuff is in nss/common.h.
Some useful links:
-http://mirrors.usc.edu/pub/gnu/Manuals/glibc-2.2.3/html_chapter/libc_28.html#SEC596
http://www.gnu.org/software/libc/manual/html_node/index.html
@@ -117,13 +116,13 @@
The PAM module is implemented in the pam directory. Implementation is fairly
straight-forward. The PAM module stores some state between PAM calls in a
-struct. The calls to nslcd are however stateless. The PAM module may however
-supply some information that help lookups (most notably DNs of user entries).
+struct. The calls to nslcd are however stateless. The PAM module may supply
+some information that help lookups (most notably DNs of user entries).
Care must be taken with the communication because the nslcd requests are not
authenticated (e.g. changing passwords requests should include all
-credentials). This is where the PAM module is different from the NSS module.
-The PAM module could result in state changes on the LDAP server.
+credentials). The PAM requests may result in state changes on the LDAP server
+and this is where they are most notably different from the NSS requests.
Some useful links:
http://www.kernel.org/pub/linux/libs/pam/
@@ -174,11 +173,11 @@
SECURITY NOTES
==============
-This design does open up the system to more potential security issues as there
-is now a local interface to a daemon with privileges. Before processes could
-only potentially exploit bugs in the library and gain the privileges of the
-process that was doing the name lookups. In this case the privileges of the
-daemon are potentially exposed.
+This design does open up the system to more potential security issues because
+there is now a local interface to a daemon with privileges. Before (with
+nss_ldap) processes could only potentially exploit bugs in the library and
+gain the privileges of the process that was doing the name lookups. In this
+case the privileges of the daemon are potentially exposed.
Extra care should be taken with processes that normally require extra
privileges (getting shadow entries, authentication, updating session
@@ -189,8 +188,8 @@
needed credentials itself.
-TEST SETUP
-==========
+TEST SET-UP
+===========
In the test directory there are a number of tests available. See the file
README in the test directory for more details.
Modified: nss-pam-ldapd/README
==============================================================================
--- nss-pam-ldapd/README Sun May 23 22:11:40 2010 (r1116)
+++ nss-pam-ldapd/README Sun May 23 23:26:16 2010 (r1117)
@@ -16,7 +16,7 @@
Copyright (C) 1997-2006 Luke Howard
Copyright (C) 2006, 2007 West Consulting
- Copyright (C) 2006, 2007, 2008, 2009 Arthur de Jong
+ Copyright (C) 2006, 2007, 2008, 2009, 2010 Arthur de Jong
Copyright (C) 2009 Howard Chu
This library is free software; you can redistribute it and/or
@@ -59,7 +59,7 @@
Both libraries consist of a thin NSS or PAM part that communicates with a
local daemon (nslcd) that handles the LDAP lookups. This simplifies the
architecture and fixes some scalability and locking problems in the original
-design.
+design of nss_ldap.
Also it is possible to use the thin NSS and PAM parts together with the nssov
overlay in the OpenLDAP server (slapd).
@@ -94,9 +94,9 @@
enabled without affecting "normal" processes
This package runs a local daemon that will be enabled during the boot process.
-This daemon will handle connections to the LDAP server and accept NSS requests
-from a named socket (/var/run/nslcd/socket). The thin NSS library will proxy
-requests to the daemon.
+This daemon will handle connections to the LDAP server and accept requests
+through a named socket (/var/run/nslcd/socket). The thin NSS library will
+proxy requests to the daemon.
Note that the package currently cannot be used on the same system alongside
nss_ldap.
@@ -105,21 +105,17 @@
----------------------
The PAM module that is currently implemented contains functionality for
-authentication, account management, password management and session management
-but only authentication is currently implemented in the nslcd daemon. The
-OpenLDAP nssov overlay implements more functionality.
+authentication, account management, password management and session
+management. The nslcd daemon currently implements authentication,
+authorisation and password modification. The OpenLDAP nssov overlay also
+implements session functionality.
-supported C libraries
----------------------
+supported C libraries (for NSS module)
+--------------------------------------
This library currently only supports the GNU C Library. Support for other C
libraries has been removed in a refactoring step. Compatibility code and
-support for other C libraries will be added in due time upon request.
-
-supported PAM implementation
-----------------------------
-
-The PAM module is currently only regularly tested on Linux PAM
+support for other C libraries will be added upon request.
supported name databases
------------------------
@@ -142,41 +138,43 @@
implementation (on GNU/Linux) currently uses it's own method for getting the
maps from LDAP.
-Although aliases is exposed through NSS, most mailservers parse /etc/aliases
+Although aliases are exposed through NSS, most mail servers parse /etc/aliases
by themselves and getting aliases from LDAP requires some configuration in the
-mailserver.
+mail server.
-The publickey, bootparams and netmasks are currently also unsupported. Some
+The publickey, bootparams and netmasks are currently unsupported. Some
investigation should be done if these are needed for anything, which
interfaces should be exported and how the LDAP schema part should look like.
+supported PAM implementation
+----------------------------
+
+The PAM module is currently only regularly tested on Linux PAM but other PAM
+implementations should also work.
+
supported LDAP libraries
------------------------
The current version of nss-pam-ldapd has been developed with OpenLDAP 2.4 but
-adding support for other LDAP libraries with similar interfaces should not be
-too hard.
+other LDAP libraries and older versions of OpenLDAP may also work.
unsupported features
--------------------
Since nss-pam-ldapd was forked from nss_ldap most of the features that came
-with nss_ldap are available. However, not all features have extensively tested
-yet and may cause problems.
-- attribute value defaults and overrides have been removed (but may reappear
- some day if requested)
+with nss_ldap are available. The most important differences:
- the configuration file formats are not fully compatible
- nested groups are currently unsupported
- rootbinddn/rootbindpw support is removed and is not likely to return
-For the PAM module a lot more functionality is missing. Comparing it to
-pam_ldap:
-- only BIND authentication is implemented
-- no authorisation checks are performed
-- password changing is under development
-
-In general, the focus is to have the functionality that is present be well
-tested and supported and add more features when they are needed.
+For the PAM module some functionality is missing. Comparing it to pam_ldap:
+- only BIND authentication is supported
+- only LDAP password modify EXOP is supported as password changing mechanism
+
+Some things work a little different in nss-pam-ldapd. For instance the
+attribute defaults and overrides of nss_ldap are implemented with mapping
+expressions and pam_ldap's pam_check_*_attr options can be implemented with
+the pam_authz_search option.
INSTALLATION
@@ -198,7 +196,7 @@
pam_ldap.so files and the daemon (nslcd). The boot process needs to be
manually modified to start the daemon at the right time.
-Also it is recommended to create a dedicated user to run the nslcd daemon as.
+Also, it is recommended to create a dedicated user for the nslcd daemon.
Configure this user in /etc/nslcd.conf using the uid and gid options.
@@ -207,12 +205,9 @@
After installation the name service switch configuration file
(/etc/nsswitch.conf) needs to be modified to do name lookups using the new
-module. Also, the nss-pam-ldapd configuration file (specified at configure
-time) needs to be modified to contain to the correct LDAP configuration.
-
-Editing nsswitch.conf consist mostly of adding ldap in the list of lookup
-methods in the right place. See the nsswitch.conf(5) manual page for details
-on the format. As an example the file could look a little like this:
+module. This consist mostly of adding ldap in the list of lookup methods in
+the right place. See the nsswitch.conf(5) manual page for details on the
+format. As an example the file could look a little like this:
# the following contain normal unix user and group information
passwd: files ldap
@@ -233,10 +228,27 @@
# whether alias lookups really use NSS depends on the mail server
aliases: files ldap
-Furthermore a configuration file (by default /etc/nslcd.conf) needs to be
-made. The location of this file can be specified with configure. See the
-shipped manual page for details on the format and options. It should at least
-contain something like:
+Configuring PAM differs a little from platform to platform but this is a basic
+set-up for files under /etc/pam.d:
+
+auth sufficient pam_unix.so
+auth sufficient pam_ldap.so use_first_pass
+auth required pam_deny.so
+
+account required pam_unix.so
+account sufficient pam_ldap.so
+account required pam_permit.so
+
+session required pam_unix.so
+session optional pam_ldap.so
+
+password sufficient pam_unix.so nullok md5 shadow use_authtok
+password sufficient pam_ldap.so try_first_pass
+password required pam_deny.so
+
+Lastly, a configuration file for nslcd (by default /etc/nslcd.conf) needs to
+be made. See the shipped manual page for details on the format and options. It
+should at the very least contain something like:
# the location of LDAP server
uri ldap://localhost/
@@ -261,18 +273,18 @@
LDAP SCHEMA
===========
-nss-pam-ldapd supports a wide range of possible LDAP schema configurations.
-Furthermore it can be customized heavily. The LDAP schema used is described in
-RFC 2307. Groups with distinguished name members (instead of login names) (RFC
-2307bis) are also supported, although use of memberUid has much better
-performance (see below for details).
+nss-pam-ldapd supports a wide range of possible LDAP schema configurations and
+it can be customized heavily. The LDAP schema used is described in RFC 2307.
+Groups with distinguished name members (instead of login names) (RFC 2307bis)
+are also supported, although use of memberUid has much better performance (see
+below for details).
default attributes
------------------
This paragraph describes the mapping between the NSS lookups and the LDAP
-database. The mapping may be modified by changeging the nslcd.conf
-configuration file. See the nslcd.conf(5) manual page for details.
+database. The mapping may be modified by changing the nslcd.conf configuration
+file. See the nslcd.conf(5) manual page for details.
aliases (objectClass=nisMailAlias)
cn - alias name
@@ -331,16 +343,16 @@
--------------------------------
When using Microsoft Active Directory server (typically on Microsoft Windows
-2000) some changes need to be made to the nslcd.conf configuration file.
-The included sample configuration file has some commented out attribute
-mappings for such a set-up.
+2000) some changes need to be made to the nslcd.conf configuration file. The
+included sample configuration file has some commented out attribute mappings
+for such a set-up.
group membership
----------------
Currently, two ways of specifying group membership are supported. The first,
by using the memberUid attribute, is the simplest and by far the fastest
-(takes the least amount of lookups). This attributes maps to user names with
+(takes the least number of lookups). This attribute maps to user names with
the same values as the uid attribute would hold for posixAccount entries.
The second method is to use DN values in the uniqueMember attribute (attribute
@@ -351,8 +363,7 @@
If the DN value already contains a uid value (e.g. uid=arthur, dc=example,
dc=com) the lookup is skipped and the value from the DN is used. A cache is
-maintained that holds on to DN to uid translations for 15 minutes (see
-DN2UID_CACHE_TIMEOUT in nslcd/passwd.c).
+maintained that saves the DN to uid translations for 15 minutes.
In all cases, users that are specified as member multiple times are returned
only once.
@@ -365,20 +376,20 @@
----------------
Most values in the NSS databases are considered case-sensitive (e.g. the user
-"Foo" is a different user from the user "foo"). Values in an LDAP database are
-however cosidered case-insensitive. nss-pam-ldapd tries to solve this problem
-by adding an extra filtering layer and ensure that e.g. when looking for the
-user "foo" it will not return a user "Foo" that is found in LDAP.
+"Foo" is a different user from the user "foo"). Most values in an LDAP
+database are however considered case-insensitive. nss-pam-ldapd tries to solve
+this problem by adding an extra filtering layer to ensure that e.g. when
+looking for the user "foo" it will not return a user "Foo" that is found in
+LDAP.
For the group, netgroup, passwd, protocols, rpc, services and shadow maps the
matches will be checked case-sensitively and for aliases, ethers, hosts and
networks matches will be case-insensitive (this seems to be what Glibc is
-doing currently with flat files). Only searching for groups by member the
-username matching is done case-insensitive. Note that in all cases the
-case-use in the LDAP directory is returned.
+doing currently with flat files). Only searching for groups by user is done
+case-insensitive. In all cases the case-use in the LDAP directory is returned.
-Note however that having entries that only differ in case is a bad idea and
-will likely get you in trouble. One example of such a problem is that the DN
+Note that having entries that only differ in case is a bad idea and will
+likely get you in trouble. One example of such a problem is that the DN
uid=test,dc=example,dc=com is the same as uid=TEST,dc=example,dc=com.
Modified: nss-pam-ldapd/man/nslcd.8.xml
==============================================================================
--- nss-pam-ldapd/man/nslcd.8.xml Sun May 23 22:11:40 2010 (r1116)
+++ nss-pam-ldapd/man/nslcd.8.xml Sun May 23 23:26:16 2010 (r1117)
@@ -58,9 +58,9 @@
<refsect1 id="description">
<title>Description</title>
<para>
- <command>nslcd</command> is a daemon that will do LDAP queries
- for local processes based on a simple configuration
- file.
+ <command>nslcd</command> is a daemon that will do LDAP queries for local
+ processes that want to do user, group and other naming lookups (NSS) or do
+ user authentication, authorisation or password modification (PAM).
</para>
<para>
<command>nslcd</command> is configured through a configuration file
Modified: nss-pam-ldapd/man/nslcd.conf.5.xml
==============================================================================
--- nss-pam-ldapd/man/nslcd.conf.5.xml Sun May 23 22:11:40 2010 (r1116)
+++ nss-pam-ldapd/man/nslcd.conf.5.xml Sun May 23 23:26:16 2010 (r1117)
@@ -60,15 +60,15 @@
configuration information for running <command>nslcd</command> (see
<citerefentry><refentrytitle>nslcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
The file contains options, one on each line, defining the way
- <acronym>NSS</acronym> lookups are mapped onto
- <acronym>LDAP</acronym> lookups.
+ <acronym>NSS</acronym> lookups and <acronym>PAM</acronym> actions
+ are mapped to <acronym>LDAP</acronym> lookups.
</para>
</refsect1>
<refsect1 id="options">
<title>Options</title>
- <refsect2 id='runtime_options'>
+ <refsect2 id="runtime_options">
<title>Runtime options</title>
<variablelist>
@@ -87,7 +87,7 @@
<term><option>uid</option> <replaceable>UID</replaceable></term>
<listitem>
<para>
- This specifies which user id with which the daemon should be run.
+ This specifies the user id with which the daemon should be run.
This can be a numerical id or a symbolic value.
If no uid is specified no attempt to change the user will be made.
Note that you should use values that don't need <acronym>LDAP</acronym>
@@ -100,7 +100,7 @@
<term><option>gid</option> <replaceable>GID</replaceable></term>
<listitem>
<para>
- This specifies which group id with which the daemon should be run.
+ This specifies the group id with which the daemon should be run.
This can be a numerical id or a symbolic value.
If no gid is specified no attempt to change the group will be made.
Note that you should use values that don't need <acronym>LDAP</acronym>
@@ -112,7 +112,7 @@
</variablelist>
</refsect2>
- <refsect2 id='general_connection_options'>
+ <refsect2 id="general_connection_options">
<title>General connection options</title>
<variablelist>
@@ -202,7 +202,7 @@
</refsect2>
<!-- DO NOT DOCUMENT FOR NOW BECAUSE IT'S NOT SUPPORTED
- <refsect2 id='sasl_authentication_options'>
+ <refsect2 id="sasl_authentication_options">
<title><acronym>SASL</acronym> authentication options</title>
<variablelist>
@@ -273,7 +273,7 @@
</refsect2>
-->
- <refsect2 id='kerberos_authentication_options'>
+ <refsect2 id="kerberos_authentication_options">
<title>Kerberos authentication options</title>
<variablelist>
@@ -289,7 +289,7 @@
</variablelist>
</refsect2>
- <refsect2 id='search_mapping_options'>
+ <refsect2 id="search_mapping_options">
<title>Search/mapping options</title>
<variablelist>
@@ -412,7 +412,7 @@
</variablelist>
</refsect2>
- <refsect2 id='timing_reconnect_options'>
+ <refsect2 id="timing_reconnect_options">
<title>Timing/reconnect options</title>
<variablelist>
@@ -423,7 +423,7 @@
Specifies the time limit (in seconds) to use when connecting to the
directory server.
This is distinct from the time limit specified in
- <option>timelimit</option> and affects the setup of the connection only.
+ <option>timelimit</option> and affects the set-up of the connection
only.
Note that not all <acronym>LDAP</acronym> client libraries have support
for setting the connection time out.
The default <option>bind_timelimit</option> is 10 seconds.
@@ -483,8 +483,9 @@
<para>
Note that the reconnect logic as described above is the mechanism that
is used between <command>nslcd</command> and the <acronym>LDAP</acronym>
- server. The mechanism between the <acronym>NSS</acronym> client library
- and <command>nslcd</command> is simpler with a fixed compiled-in
+ server. The mechanism between the <acronym>NSS</acronym> and
+ <acronym>PAM</acronym> client libraries on one end and
+ <command>nslcd</command> on the other is simpler with a fixed compiled-in
time out of a 10 seconds for writing to <command>nslcd</command> and
a time out of 60 seconds for reading answers.
<command>nslcd</command> itself has a read time out of 0.5 seconds
@@ -493,7 +494,7 @@
</refsect2>
- <refsect2 id='ssl_tls_options'>
+ <refsect2 id="ssl_tls_options">
<title><acronym>SSL</acronym>/<acronym>TLS</acronym> options</title>
<variablelist>
@@ -587,7 +588,7 @@
</variablelist>
</refsect2>
- <refsect2 id='other_options'>
+ <refsect2 id="other_options">
<title>Other options</title>
<variablelist>
--
To unsubscribe send an email to
nss-pam-ldapd-commits-unsubscribe@lists.arthurdejong.org or see
http://lists.arthurdejong.org/nss-pam-ldapd-commits
- nss-pam-ldapd commit: r1117 - in nss-pam-ldapd: . man,
Commits of the nss-pam-ldapd project.
