.\" Copying restrictions apply. See the COPYRIGHT file.
.\" $OpenLDAP$
.SH NAME
-slapo-nssov \- NSS lookup requests through a local Unix Domain socket
+slapo-nssov \- NSS and PAM requests through a local Unix Domain socket
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
.B nssov
overlay to
.BR slapd (8)
-allows NSS lookup requests through a local Unix Domain socket.
+services NSS and PAM requests through a local Unix Domain socket.
It uses the same IPC protocol as Arthur de Jong's nss-ldapd, and
-a complete copy of the nss-ldapd source is included here. It also
-handles PAM requests.
+a complete copy of the nss-ldapd source is included along with the
+nssov source code.
.LP
-The main objective here was to eliminate the libldap dependencies/clashes that
-the current pam_ldap/nss_ldap solutions all suffer from. A secondary objective
-was to allow for the possibility of more sophisticated caching than nscd
-provides. (E.g., run slapd back-ldap + pcache on each node.) Of course, you
-can also completey eliminate cache staleness considerations by running a
-regular database with syncrepl.
+Using a separate IPC protocol for NSS and PAM requests eliminates the
+libldap dependencies/clashes that the current pam_ldap/nss_ldap solutions
+all suffer from. Both the original nss-ldapd and this nssov solution
+are free from these library issues.
.LP
-And of course, another major objective was to allow all security policy to be
+Unlike nss-ldapd, since this overlay executes inside slapd it allows for
+the possibility of sophisticated caching, without any of the weaknesses of
+nscd and other related caching solutions. E.g., a remote LDAP database can
+be accessed using back-ldap with proxy caching (see
+.BR slapd-ldap (5)
+and
+.BR slapo-pcache (5)
+) to leverage back-ldap's
+connection pooling as well as pcache's persistent caching, to provide
+high performance and a measure of support for disconnected operation.
+Alternatively, cache considerations can be completely eliminated by running
+a regular database with syncrepl to maintain synchronization with a remote
+LDAP database.
+.LP
+Another major benefit of nssov is that it allows all security policy to be
administered centrally via LDAP, instead of having fragile rules scattered
across multiple flat files. As such, there is no client-side configuration at
-all for the pam/nss stub libraries. (They talk to the server via a Unix domain
-socket whose path is hardcoded to /var/run/nslcd/). As a side benefit, this
-can finally eliminate the perpetual confusion over /etc/ldap.conf vs
-/etc/openldap/ldap.conf.
+all for the NSS/PAM stub libraries. (The stubs talk to the server via a Unix
+domain socket whose path is hardcoded to /var/run/nslcd/). As a side benefit,
+this can finally eliminate the perpetual confusion between OpenLDAP's
+ldap.conf file in ETCDIR/ldap.conf and the similarly named files typically
+used by pam_ldap and nss_ldap.
.LP
User authentication is performed by internal simple Binds. User authorization
leverages the slapd ACL engine, which offers much more power and flexibility
.B nss-ldapd/README
for more information on the schema and which features are supported.
.LP
-To use the overlay add:
-.LP
-.RS
-.nf
- include <path to>nis.schema
-
- moduleload <path to>nssov.so
- ...
-
- database hdb
- ...
- overlay nssov
-.fi
-.RE
-.LP
-to your slapd configuration file. (The nis.schema file contains
-the original [RFC2307] schema. Some modifications will be needed to
-use [RFC2307bis].)
+You will also need to include the nis.schema in your slapd configuration
+for RFC2307 support. If you wish to use RFC2307bis you will need a slightly
+different schema. You will also need the ldapns.schema for PAM authorization
+management.
.LP
-The overlay may be configured with
-.B Service Search Descriptors (SSDs)
-for each NSS service that will be used. SSDs are configured using
-.LP
-.RS
-.nf
- nssov-ssd <service> <url>
-.fi
-.RE
-.LP
-where the <service> may be one of
-.LP
+You must select
+.B ldap
+in the appropriate services in
+.I /etc/nsswitch.conf
+in order for these NSS features to take effect. Likewise, you must
+enable
+.B pam_ldap
+for the authenticate, account, session, and password services in
+.I /etc/pam.conf
+or
+.I /etc/pam.d
+for these PAM features to take effect.
+
+.TP
+.B overlay nssov
+This directive adds the nssov overlay to the current backend.
+.TP
+.B nssov-ssd <service> <url>
+This directive configures a Service Search Descriptor (SSD) for each NSS
+service that will be used. The <service> may be one of
.RS
.nf
alias
shadow
.fi
.RE
-.LP
and the <url> must be of the form
-.LP
.RS
-.nf
- ldap:///[<basedn>][??[<scope>][?<filter>]]
-.fi
+.TP
+.B ldap:///[<basedn>][??[<scope>][?<filter>]]
.RE
-.LP
The
.B <basedn>
will default to the first suffix of the current database.
defaults to "subtree". The default
.B <filter>
depends on which service is being used.
-.LP
+.TP
+.B nssov-map <service> <orig> <new>
If the local database is actually a proxy to a foreign LDAP server, some
-mapping of schema may be needed. Some simple attribute substitutions may
-be performed using
-.LP
-.RS
-.nf
- nssov-map <service> <orig> <new>
-.fi
-.RE
-.LP
-See the
+mapping of schema may be needed. This directive allows some simple attribute
+substitutions to be performed. See the
.B nss-ldapd/README
for the original attribute names used in this code.
+.TP
+.B nssov-pam <option> [...]
+This directive determines a number of PAM behaviors. Multiple options may
+be used at once, and available levels are:
+.RS
+.RS
+.PD 0
+.TP
+.B userhost
+check host attribute in user entry for authorization
+.TP
+.B userservice
+check authorizedService attribute in user entry for authorization
+.TP
+.B usergroup
+check that user is a member of specific group for authorization
+.TP
+.B hostservice
+check authorizedService attribute in host entry for authorization
+.TP
+.B authz2dn
+use authz-regexp mapping to map uid to LDAP DN
+.TP
+.B uid2dn
+use NSS passwd SSD to map uid to LDAP DN
+.PD
+.RE
+
+Setting the
+.BR userhost ,
+.BR userservice ,
+and
+.B usergroup
+options duplicates the original pam_ldap authorization behavior.
+
+The recommended approach is to use
+.B hostservice
+instead. In this case, ipHost entries must be created for all hosts
+being managed, and they must also have the authorizedServiceObject
+class to allow authorizedService attributes to be used.
+Authorization is checked by performing an LDAP Compare operation
+looking for the PAM service name in the authorizedService attribute.
+.B slapd
+ACLs should be set to grant or deny
+.B Compare
+privilege to the appropriate users or groups as desired.
+
+If the
+.B authz2dn
+option is set then authz-regexp mappings will be used to map the
+PAM username to an LDAP DN. The authentication DN will be of the
+form
+.RS
+.B cn=<service>+uid=<user>,cn=<hostname>,cn=pam,cn=auth
+.RE
+
+If no mapping is found for this authentication DN, then this
+mapping will be ignored.
+
+If the
+.B uid2dn
+option is set then the NSS passwd SSD will be used to map the
+PAM username to an LDAP DN. The passwd SSD must have already been
+configured for this mapping to succeed.
+
+If neither the authz2dn nor the uid2dn mapping succeeds, the module
+will return a PAM_USER_UNKNOWN failure code. If both options are set,
+the authz mapping is attempted first; if it succeeds the uid2dn mapping
+will be skipped.
+
+By default only the
+.B uid2dn
+option is set.
+.RE
+.TP
+.B nssov-pam-defhost <hostname>
+Specify a default hostname to check if an ipHost entry for the current
+hostname cannot be found. This setting is only relevant if the
+.B hostservice
+option has been set.
+.TP
+.B nssov-pam-group-dn <DN>
+Specify the DN of an LDAP group to check for authorization. The LDAP user
+must be a member of this group for the login to be allowed. There is no
+default value. This setting is only relevant if the
+.B usergroup
+option has been set.
+.TP
+.B nssov-pam-group-ad <attribute>
+Specify the attribute to use for group membership checks.
+There is no default value. This setting is only relevant if the
+.B usergroup
+option has been set.
+.TP
+.B nssov-pam-minuid <integer>
+Specify a minimum uid that is allowed to login. Users with a uidNumber
+lower than this value will be denied access. The default is zero, which
+disables this setting.
+.TP
+.B nssov-pam-maxuid <integer>
+Specify a maximum uid that is allowed to login. Users with a uidNumber
+higher than this value will be denied access. The default is zero, which
+disables this setting.
+.TP
+.B nssov-pam-template-ad <attribute>
+Specify an attribute to check in a user's entry for a template login name.
+The template login feature is used by FreeBSD's PAM framework. It can be
+viewed as a form of proxying, where a user can authenticate with one
+username/password pair, but is assigned the identity and credentials of
+the template user. This setting is disabled by default.
+.TP
+.B nssov-pam-template <name>
+Specify a default username to be used if no template attribute is found
+in the user's entry. The
+.B nssov-pam-template-ad
+directive must be configured for this setting to have any effect.
+.TP
+.B nssov-pam-session <service>
+Specify a PAM service name whose sessions will be recorded. For the
+configured services, logins will be recorded in the
+.B loginStatus
+operational attribute of the user's entry. The attribute's values are
+of the form
+.RS
+.RS
+.B <generalizedTime> <host> <service> <tty> (<ruser@rhost>)
+.RE
+.RE
+Upon logout the corresponding value will be deleted. This feature allows
+a single LDAP Search to be used to check which users are logged in across
+all the hosts of a network. By default no services are configured.
.LP
-The overlay also supports dynamic configuration in cn=config. The layout
+The PAM functions support LDAP Password Policy as well. If the password
+policy overlay is in use (see
+.BR slapo-ppolicy (5)),
+policy
+information (e.g. password expiration, password quality, etc.)
+may be returned to the PAM client as a result of authentication,
+account management, and password modification requests.
+
+The overlay also supports dynamic configuration in cn=config. An example
of the config entry is
.LP
.RS
olcOverlay: {0}nssov
olcNssSvc: passwd ldap:///ou=users,dc=example,dc=com??one
olcNssMap: passwd uid accountName
+ olcNssPam: hostservice uid2dn
+ olcNssPamDefHost: defaulthost
+ olcNssPamMinUid: 500
+ olcNssPamMaxUid: 32000
+ olcNssPamSession: login
+ olcNssPamSession: sshd
.fi
.RE
.LP
which enables the passwd service, and uses the accountName attribute to
-fetch what is usually retrieved from the uid attribute.
-.LP
-PAM authentication, account management, session management, and password
-management are supported.
-.LP
-Authentication is performed using Simple Binds. Since all operations occur
-inside the slapd overlay, "fake" connections are used and they are
-inherently secure. Two methods of mapping the PAM username to an LDAP DN
-are provided:
- the mapping can be accomplished using slapd's authz-regexp facility. In
-this case, a DN of the form
-.B cn=<service>+uid=<user>,cn=<hostname>,cn=pam,cn=auth
-is fed into the regexp matcher. If a match is produced, the resulting DN
-is used. Otherwise, the NSS passwd map is invoked (which means it must already
-be configured).
-.LP
-If no DN is found, the overlay returns PAM_USER_UNKNOWN. If the DN is
-found, and Password Policy is supported, then the Bind will use the
-Password Policy control and return expiration information to PAM.
-.LP
-Account management also uses two methods. These methods depend on the
-ldapns.schema included with the nssov source.
-.LP
-The first is identical to the method used in PADL's pam_ldap module:
-host and authorizedService attributes may be looked up in the user's entry,
-and checked to determine access. Also a check may be performed to see if
-the user is a member of a particular group. This method is pretty
-inflexible and doesn't scale well to large networks of users, hosts,
-and services.
-.LP
- The second uses slapd's ACL engine to check if the user has "compare"
-privilege on an ipHost object whose name matches the current hostname, and
-whose authorizedService attribute matches the current service name. This
-method is preferred, since it allows authorization to be centralized in
-the ipHost entries instead of scattered across the entire user population.
-The ipHost entries must have an authorizedService attribute (e.g. by way
-of the authorizedServiceObject auxiliary class) to use this method.
-.LP
-Session management: the overlay may optionally add a "logged in" attribute
-to a user's entry for successful logins, and delete the corresponding
-value upon logout. The attribute value is of the form
-.B <generalizedTime> <host> <service> <tty> (<ruser@rhost>)
-Password management: the overlay will perform a PasswordModify exop
-in the server for the given user.
+fetch what is usually retrieved from the uid attribute. It also enables
+some PAM authorization controls, and specifies that the PAM
+.B login
+and
+.B sshd
+services should have their logins recorded.
.SH FILES
.TP
ETCDIR/slapd.conf
.BR slapd.conf (5),
.BR slapd\-config (5),
.BR slapd\-ldap (5),
+.BR slapo\-pcache (5),
+.BR slapo\-ppolicy (5),
.BR slapd (8).
.SH AUTHOR
-Originally implemented by Howard Chu; man page Gavin Henry, Suretec Systems Ltd.
+Howard Chu, inspired by nss-ldapd by Arthur de Jong and pam_ldap by Luke Howard
projects / openldap / commitdiff