path: root/man/nslcd.conf.5.xml.in

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<!--
   nslcd.conf.5.xml - docbook manual page for nslcd.conf

   Copyright (C) 1997-2005 Luke Howard
   Copyright (C) 2007-2014 Arthur de Jong

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
   02110-1301 USA
-->

<refentry id="nssldapdconf5">

 <refentryinfo>
  <author>
   <firstname>Arthur</firstname>
   <surname>de Jong</surname>
  </author>
 </refentryinfo>

 <refmeta>
  <refentrytitle>nslcd.conf</refentrytitle>
  <manvolnum>5</manvolnum>
  <refmiscinfo class="version">Version @PROGRAM_VERSION@</refmiscinfo>
  <refmiscinfo class="manual">System Manager's Manual</refmiscinfo>
  <refmiscinfo class="date">Jun 2014</refmiscinfo>
 </refmeta>

 <refnamediv id="name">
  <refname>nslcd.conf</refname>
  <refpurpose>configuration file for LDAP nameservice daemon</refpurpose>
 </refnamediv>

 <refsect1 id="description">
  <title>Description</title>
  <para>
   The <emphasis>@PACKAGE_NAME@</emphasis> package allows <acronym>LDAP</acronym>
   directory servers to be used as a primary source of name service
   information. (Name service information typically includes users, hosts,
   groups, and other such data historically stored in flat files or
   <acronym>NIS</acronym>.)
  </para>
  <para>
    The file <filename>nslcd.conf</filename> contains the
    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 and <acronym>PAM</acronym> actions
    are mapped to <acronym>LDAP</acronym> lookups.
  </para>
 </refsect1>

 <refsect1 id="options">
  <title>Options</title>

  <refsect2 id="runtime_options">
   <title>Runtime options</title>
   <variablelist>

    <varlistentry id="threads"> <!-- since 0.6.2 -->
     <term><option>threads</option> <replaceable>NUM</replaceable></term>
     <listitem>
      <para>
       Specifies the number of threads to start that can handle requests
       and perform <acronym>LDAP</acronym> queries.
       Each thread opens a separate connection to the <acronym>LDAP</acronym>
       server.
       The default is to start 5 threads.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="log"> <!-- since 0.9 -->
     <term><option>log</option> <replaceable>SCHEME</replaceable> <optional><replaceable>LEVEL</replaceable></optional></term>
     <listitem>
      <para>
       This option controls the way logging is done.
       The <replaceable>SCHEME</replaceable> argument may either be
       <literal>none</literal>, <literal>syslog</literal> or an absolute
       file name.
       The <replaceable>LEVEL</replaceable> argument is optional and specifies
       the log level.
       The log level may be one of: <literal>crit</literal>,
       <literal>error</literal>, <literal>warning</literal>,
       <literal>notice</literal>, <literal>info</literal> or
       <literal>debug</literal>. The default log level is <literal>info</literal>.
       All messages with the specified loglevel or higher are logged.
       This option can be supplied multiple times.
       If this option is omitted <literal>syslog info</literal> is assumed.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </refsect2>

  <refsect2 id="general_connection_options">
   <title>General connection options</title>
   <variablelist>

    <varlistentry id="yamldir">
     <term><option>yamldir</option> <replaceable>PATH</replaceable></term>
     <listitem>
      <para>
       Specifies where hackers.git is checked out to.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </refsect2>

  <refsect2 id="other_options">
   <title>Other options</title>
   <variablelist>

    <varlistentry id="pagesize"> <!-- since 0.3 -->
     <term><option>pagesize</option> <replaceable>NUMBER</replaceable></term>
     <listitem>
      <para>
       Set this to a number greater than 0 to request paged results from
       the <acronym>LDAP</acronym> server in accordance with RFC2696.
       The default (0) is to not request paged results.
      </para>
      <para>
       This is useful for <acronym>LDAP</acronym> servers that contain a
       lot of entries (e.g. more than 500) and limit the number of entries
       that are returned with one request.
       For OpenLDAP servers you may need to set
       <option>sizelimit size.prtotal=unlimited</option>
       for allowing more entries to be returned over multiple pages.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="nss_initgroups_ignoreusers"> <!-- since 0.7.4 -->
     <term><option>nss_initgroups_ignoreusers</option> user1,user2,...</term>
     <listitem>
      <para>
       This option prevents group membership lookups through
       <acronym>LDAP</acronym> for the specified users. This can be useful
       in case of unavailability of the <acronym>LDAP</acronym> server.
       This option may be specified multiple times.
      </para>
      <para>
       Alternatively, the value <literal>ALLLOCAL</literal> may be
       used. With that value nslcd builds a full list of
       non-<acronym>LDAP</acronym> users on startup.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="nss_min_uid"> <!-- since 0.8.0 -->
     <term><option>nss_min_uid</option> <replaceable>UID</replaceable></term>
     <listitem>
      <para>
       This option ensures that <acronym>LDAP</acronym> users with a numeric
       user id lower than the specified value are ignored. Also requests for
       users with a lower user id are ignored.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="nss_nested_groups"> <!-- since 0.9.0 -->
     <term><option>nss_nested_groups</option> yes|no</term>
     <listitem>
      <para>
       If this option is set, the <literal>member</literal> 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.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="validnames"> <!-- since 0.8.2 -->
     <term><option>validnames</option> <replaceable>REGEX</replaceable></term>
     <listitem>
      <para>
       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 <acronym>LDAP</acronym>.
      </para>
      <para>
       The regular expression should be specified as a POSIX extended regular
       expression. The expression itself needs to be separated by slash (/)
       characters and the 'i' flag may be appended at the end to indicate
       that the match should be case-insensetive.
       The default value is
       <literal>/^[a-z0-9._@$()]([a-z0-9._@$() \\~-]*[a-z0-9._@$()~-])?$/i</literal>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="ignorecase"> <!-- since 0.8.7 -->
     <term><option>ignorecase</option> yes|no</term>
     <listitem>
      <para>
       This specifies whether or not to perform searches for group,
       netgroup, passwd, protocols, rpc, services and shadow maps using
       case-insensitive matching.
       Setting this to <literal>yes</literal> could open up the system
       to authorisation vulnerabilities and introduce nscd cache poisoning
       vulnerabilities which allow denial of service.
       The default is to perform case-sensitve filtering of LDAP search
       results for the above maps.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="pam_password_prohibit_message"> <!-- since 0.8.11 -->
     <term><option>pam_password_prohibit_message</option>
           "<replaceable>MESSAGE</replaceable>"</term>
     <listitem>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="reconnect_invalidate"> <!-- since 0.9.1, was nscd_invalidate in 0.9.0 -->
     <term><option>reconnect_invalidate</option>
           <replaceable>DB</replaceable>,<replaceable>DB</replaceable>,...</term>
     <listitem>
      <para>
       If this option is set, on start-up and whenever a connection to the
       <acronym>LDAP</acronym> server is re-established after an error
       the specified caches are flushed.
      </para>
      <para>
       If <replaceable>DB</replaceable> is one of the nsswitch maps,
       <command>nscd</command> is contacted to flush its cache for the
       specified database.
       <!-- since 0.9.1 -->
       If <replaceable>DB</replaceable> is <literal>nfsidmap</literal>,
       <command>nfsidmap</command> is contacted to clear its cache.
      </para>
      <para>
       Using this option ensures that external caches are cleared of
       information (typically the absence of users) while the
       <acronym>LDAP</acronym> server was unavailable.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </refsect2>

 </refsect1>

 <refsect1 id="files">
  <title>Files</title>
  <variablelist remap="TP">
   <varlistentry>
    <term><filename>@NSLCD_CONF_PATH@</filename></term>
    <listitem><para>the main configuration file</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/etc/nsswitch.conf</filename></term>
    <listitem><para>Name Service Switch configuration file</para></listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 id="see_also">
  <title>See Also</title>
  <para>
   <citerefentry><refentrytitle>nslcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
   <citerefentry><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  </para>
 </refsect1>

 <refsect1 id="author">
  <title>Author</title>
  <para>This manual was written by Arthur de Jong &lt;arthur@arthurdejong.org&gt;
        and is based on the
        <citerefentry><refentrytitle>nss_ldap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        manual developed by PADL Software Pty Ltd.</para>
 </refsect1>

</refentry>