summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorRicardo Wurmus <rekado@elephly.net>2019-03-20 19:43:07 +0100
committerRicardo Wurmus <rekado@elephly.net>2019-03-20 20:31:15 +0100
commitc16423f143919916a5273761d7ed29bd49f14519 (patch)
treef0e9ddca711bb138845815f0f196e4dc25bdb9b0 /doc
parentbcf66fc2e75151b248265ed12ec8453fe9b0ce47 (diff)
services: Add nslcd-service-type.
* gnu/services/authentication.scm (nslcd-service-type, nslcd-configuration, %nslcd-accounts): New variables. (uglify-field-name, value->string, serialize-field, serialize-list, ssl-option?, tls-reqcert-option?, deref-option?, comma-separated-list-of-strings?, serialize-ignore-users-option, log-option?, serialize-log-option, valid-map?, scope-option?, serialize-scope-option, map-entry?, list-of-map-entries?, filter-entry?, list-of-filter-entries?, serialize-filter-entry, serialize-list-of-filter-entries, serialize-map-entry, serialize-list-of-map-entries, nslcd-config-file, nslcd-etc-service, nslcd-shepherd-service, pam-ldap-pam-services, pam-ldap-pam-service, generate-nslcd-documentation): New procedures. * gnu/tests/ldap.scm: New file. * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. * doc/guix.texi (LDAP Services): Document it.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi479
1 files changed, 479 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index bb344e1625..94d7a29bdf 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -11139,6 +11139,7 @@ declaration.
* Telephony Services:: Telephony services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
+* LDAP Services:: LDAP services.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
@@ -17685,6 +17686,484 @@ Local accounts with lower values will silently fail to authenticate.
@end deftp
+@node LDAP Services
+@subsection LDAP Services
+@cindex LDAP
+@cindex nslcd, LDAP service
+
+The @code{(gnu services authentication)} module provides the
+@code{nslcd-service-type}, which can be used to authenticate against an LDAP
+server. In addition to configuring the service itself, you may want to add
+@code{ldap} as a name service to the Name Service Switch. @xref{Name Service
+Switch} for detailed information.
+
+Here is a simple operating system declaration with a default configuration of
+the @code{nslcd-service-type} and a Name Service Switch configuration that
+consults the @code{ldap} name service last:
+
+@example
+(use-service-modules authentication)
+(use-modules (gnu system nss))
+...
+(operating-system
+ ...
+ (services
+ (cons*
+ (service nslcd-service-type)
+ (service dhcp-client-service-type)
+ %base-services))
+ (name-service-switch
+ (let ((services (list (name-service (name "db"))
+ (name-service (name "files"))
+ (name-service (name "ldap")))))
+ (name-service-switch
+ (inherit %mdns-host-lookup-nss)
+ (password services)
+ (shadow services)
+ (group services)
+ (netgroup services)
+ (gshadow services)))))
+@end example
+
+@c %start of generated documentation for nslcd-configuration
+
+Available @code{nslcd-configuration} fields are:
+
+@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
+The @code{nss-pam-ldapd} package to use.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
+The number of threads to start that can handle requests and perform LDAP
+queries. Each thread opens a separate connection to the LDAP server.
+The default is to start 5 threads.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} string uid
+This specifies the user id with which the daemon should be run.
+
+Defaults to @samp{"nslcd"}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} string gid
+This specifies the group id with which the daemon should be run.
+
+Defaults to @samp{"nslcd"}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} log-option log
+This option controls the way logging is done via a list containing
+SCHEME and LEVEL. The SCHEME argument may either be the symbols "none"
+or "syslog", or an absolute file name. The LEVEL argument is optional
+and specifies the log level. The log level may be one of the following
+symbols: "crit", "error", "warning", "notice", "info" or "debug". All
+messages with the specified log level or higher are logged.
+
+Defaults to @samp{("/var/log/nslcd" info)}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list uri
+The list of LDAP server URIs. Normally, only the first server will be
+used with the following servers as fall-back.
+
+Defaults to @samp{("ldap://localhost:389/")}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
+The version of the LDAP protocol to use. The default is to use the
+maximum version supported by the LDAP library.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
+Specifies the distinguished name with which to bind to the directory
+server for lookups. The default is to bind anonymously.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
+Specifies the credentials with which to bind. This option is only
+applicable when used with binddn.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
+Specifies the distinguished name to use when the root user tries to
+modify a user's password using the PAM module.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
+Specifies the credentials with which to bind if the root user tries to
+change a user's password. This option is only applicable when used with
+rootpwmoddn
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
+Specifies the SASL mechanism to be used when performing SASL
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
+Specifies the SASL realm to be used when performing SASL authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
+Specifies the authentication identity to be used when performing SASL
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
+Specifies the authorization identity to be used when performing SASL
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
+Determines whether the LDAP server host name should be canonicalised. If
+this is enabled the LDAP library will do a reverse host name lookup. By
+default, it is left up to the LDAP library whether this check is
+performed or not.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
+Set the name for the GSS-API Kerberos credentials cache.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} string base
+The directory search base.
+
+Defaults to @samp{"dc=example,dc=com"}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} scope-option scope
+Specifies the search scope (subtree, onelevel, base or children). The
+default scope is subtree; base scope is almost never useful for name
+service lookups; children scope is not supported on all servers.
+
+Defaults to @samp{(subtree)}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
+Specifies the policy for dereferencing aliases. The default policy is
+to never dereference aliases.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
+Specifies whether automatic referral chasing should be enabled. The
+default behaviour is to chase referrals.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
+This option allows for custom attributes to be looked up instead of the
+default RFC 2307 attributes. It is a list of maps, each consisting of
+the name of a map, the RFC 2307 attribute to match and the query
+expression for the attribute as it is available in the directory.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
+A list of filters consisting of the name of a map to which the filter
+applies and an LDAP search filter expression.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
+Specifies the time limit in seconds to use when connecting to the
+directory server. The default value is 10 seconds.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
+Specifies the time limit (in seconds) to wait for a response from the
+LDAP server. A value of zero, which is the default, is to wait
+indefinitely for searches to be completed.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
+Specifies the period if inactivity (in seconds) after which the con‐
+nection to the LDAP server will be closed. The default is not to time
+out connections.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
+Specifies the number of seconds to sleep when connecting to all LDAP
+servers fails. By default one second is waited between the first
+failure and the first retry.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
+Specifies the time after which the LDAP server is considered to be
+permanently unavailable. Once this time is reached retries will be done
+only once per this time period. The default value is 10 seconds.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
+Specifies whether to use SSL/TLS or not (the default is not to). If
+'start-tls is specified then StartTLS is used rather than raw LDAP over
+SSL.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
+Specifies what checks to perform on a server-supplied certificate. The
+meaning of the values is described in the ldap.conf(5) manual page.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
+Specifies the directory containing X.509 certificates for peer authen‐
+tication. This parameter is ignored when using GnuTLS.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
+Specifies the path to the X.509 certificate for peer authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
+Specifies the path to an entropy source. This parameter is ignored when
+using GnuTLS.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
+Specifies the ciphers to use for TLS as a string.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
+Specifies the path to the file containing the local certificate for
+client TLS authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
+Specifies the path to the file containing the private key for client TLS
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
+Set this to a number greater than 0 to request paged results from the
+LDAP server in accordance with RFC2696. The default (0) is to not
+request paged results.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
+This option prevents group membership lookups through LDAP for the
+specified users. Alternatively, the value 'all-local may be used. With
+that value nslcd builds a full list of non-LDAP users on startup.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
+This option ensures that LDAP users with a numeric user id lower than
+the specified value are ignored.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
+This option specifies an offset that is added to all LDAP numeric user
+ids. This can be used to avoid user id collisions with local users.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
+This option specifies an offset that is added to all LDAP numeric group
+ids. This can be used to avoid user id collisions with local groups.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
+If this option is set, the member attribute of a group may point to
+another group. Members of nested groups are also returned in the higher
+level group and parent groups are returned when finding groups for a
+specific user. The default is not to perform extra searches for nested
+groups.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
+If this option is set, the group member list is not retrieved when
+looking up groups. Lookups for finding which groups a user belongs to
+will remain functional so the user will likely still get the correct
+groups assigned on login.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
+If this option is set, functions which cause all user/group entries to
+be loaded from the directory will not succeed in doing so. This can
+dramatically reduce LDAP server load in situations where there are a
+great number of users and/or groups. This option is not recommended for
+most configurations.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
+This option can be used to specify how user and group names are verified
+within the system. This pattern is used to check all user and group
+names that are requested and returned from LDAP.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
+This specifies whether or not to perform searches using case-insensitive
+matching. Enabling this could open up the system to authorization
+bypass vulnerabilities and introduce nscd cache poisoning
+vulnerabilities which allow denial of service.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
+This option specifies whether password policy controls are requested and
+handled from the LDAP server when performing user authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
+By default nslcd performs an LDAP search with the user's credentials
+after BIND (authentication) to ensure that the BIND operation was
+successful. The default search is a simple check to see if the user's
+DN exists. A search filter can be specified that will be used instead.
+It should return at least one entry.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
+This option allows flexible fine tuning of the authorisation check that
+should be performed. The search filter specified is executed and if any
+entries match, access is granted, otherwise access is denied.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
+If this option is set password modification using pam_ldap will be
+denied and the specified message will be presented to the user instead.
+The message can be used to direct the user to an alternative means of
+changing their password.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list pam-services
+List of pam service names for which LDAP authentication should suffice.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@c %end of generated documentation for nslcd-configuration
+
+
@node Web Services
@subsection Web Services