From c16423f143919916a5273761d7ed29bd49f14519 Mon Sep 17 00:00:00 2001 From: Ricardo Wurmus Date: Wed, 20 Mar 2019 19:43:07 +0100 Subject: 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. --- doc/guix.texi | 479 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 479 insertions(+) (limited to 'doc/guix.texi') 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 -- cgit 1.4.1