DEBOPS.NSLCD(5)

NAME
debops.nslcd - Configure LDAP support for NSS and PAM lookups

SYNOPSIS

debops run service/nslcd [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The nslcd daemon, part of the nss-pam-ldapd <https://arthurdejong.org/nss-pam-ldapd/> software package, is used to look up user, group or other information stored in LDAP that is related to UNIX accounts or groups. It is needed if you want to use the posixAccount and posixGroup LDAP objects to authenticate to the UNIX-like hosts.

The debops.nslcd Ansible role can be used to configure the nslcd service on a host and, via debops.ldap role, create a bind account in the LDAP directory used by nslcd to perform LDAP lookups.

GETTING STARTED

  Example inventory

To enable the nslcd service on a host, you need to add it to the [debops_service_nslcd] Ansible inventory group. The host should also be configured with base LDAP support via the debops.ldap role (see its documentation for more details):

[debops_service_ldap]
hostname
[debops_service_nslcd]
hostname

A common case is configuration of LDAP authentication in the entire cluster of hosts. You can enable debops.nslcd role on all DebOps hosts in the Ansible inventory at once:

[debops_all_hosts]
hostname1
hostname2
[debops_service_nslcd:children]
debops_all_hosts

The nslcd service can also be installed and configured by other playbooks, for example bootstrap-ldap.yml. In such cases the custom playbook will configure the nslcd service on a host, but the role playbook will not work on a host automatically; you will have to include that host in the [debops_service_nslcd] Ansible inventory group via one of the methods above to be able to change the service configuration.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.nslcd role:

---
- name: Manage nslcd service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_nslcd' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::ldap' ]
      python__dependent_packages3:
        - '{{ ldap__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ ldap__python__dependent_packages2 }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ nslcd__ldap__dependent_tasks }}'
    - role: nslcd
      tags: [ 'role::nslcd', 'skip::nslcd' ]
    - role: nsswitch
      tags: [ 'role::nsswitch', 'skip::nsswitch' ]
      nsswitch__dependent_services:
        - '{{ nslcd__nsswitch__dependent_services }}'

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

role::nslcd
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.nslcd Ansible role:

•   Manual pages: nslcd.conf(5) <https://manpages.debian.org/nslcd.conf(5)>

•   LDAP support in DebOps: client-side, server-side

•   LDAP/NSS setup instructions <https://wiki.debian.org/LDAP/NSS#NSS_Setup_with_libnss-ldapd> in the Debian Wiki

•   LDAP/PAM setup instructions <https://wiki.debian.org/LDAP/PAM> in the Debian Wiki

•   LDAP authentication <https://wiki.archlinux.org/index.php/LDAP_authentication> documentation in the Arch Wiki

•   Debian LDAP Portal <https://wiki.debian.org/LDAP> page in the Debian Wiki

DEFAULT VARIABLE DETAILS

Some of the debops.nslcd default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  nslcd__configuration

The nslcd__*_configuration variables define the contents of the /etc/nslcd.conf configuration file. The variables are merged in order defined by the nslcd__combined_configuration variable, which allows modification of the default configuration through the Ansible inventory. See nslcd.conf(5) <https://manpages.debian.org/nslcd.conf(5)> for possible configuration parameters and their values.

  Examples

See nslcd__default_configuration variable for an example of existing configuration.

Limit UNIX accounts and groups that appear on the server based on the host attribute. The value can be:

•   host.example.org or host (specific host)

•   *.example.org (specific subdomain)

•   * (all hosts)

    nslcd__configuration:
      - name: 'filter_passwd_group'
        comment: 'Limit which UNIX accounts and groups are present on a host'
        raw: |
          filter passwd (&(objectClass=posixAccount)(|(host={{ ansible_fqdn }})(host=\2a.{{ ansible_domain }})(host={{ ansible_hostname }})(host=\2a)))
          filter group  (&(objectClass=posixGroupId)(|(host={{ ansible_fqdn }})(host=\2a.{{ ansible_domain }})(host={{ ansible_hostname }})(host=\2a)))
          filter shadow (&(objectClass=shadowAccount)(|(host={{ ansible_fqdn }})(host=\2a.{{ ansible_domain }})(host={{ ansible_hostname }})(host=\2a)))

    Send debug logs to syslog to allow easier debugging:

    nslcd__configuration:
      - name: 'log'
        value: 'syslog debug'

  Syntax

The variables contain a list of YAML dictionaries, each dictionary can have specific parameters:

name
    Required. Name of the nslcd.conf(5) <https://manpages.debian.org/nslcd.conf(5)> configuration option. The configuration options with the same name parameter will be merged in order of appearance.

    If you want to specify multiple configuration options with the same name, make sure that the name parameter is unique and use the option parameter to specify the "real" option name to use.

value
    Required. The value of a given configuration option. It can be either a string, or a YAML list (elements will be joined with spaces).

option
    Optional. When configuration options are specified multiple times, this parameter can be used to specify the option name instead of the name parameter.

map Optional. Name of the "map" to configure, inserted between the option name, and its value. You can find more about map usage in the nslcd.conf(5) <https://manpages.debian.org/nslcd.conf(5)> documentation.

raw Optional. String or YAML text block which will be included in the configuration file "as is". If this parameter is specified, name, option and map parameters are ignored - you need to specify the entire line(s) with configuration option names as well.

state
    Optional. If not defined or present, a given configuration option will be included in the generated configuration file. If absent, a given configuration option will be removed from the generated file. If comment, the option will be included, but commented out and inactive. If ignore, the role will not evaluate the configuration entry during template generation, this can be used for conditional activation of nslcd.conf(5) <https://manpages.debian.org/nslcd.conf(5)> configuration options.

comment
    Optional. String or YAML text block that contains comments about a given configuration option.

separator
    Optional, boolean. If True, and additional empty line will be added before a given configuration option to separate it from the other options for readability.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others