DEBOPS.NSCD(5)

NAME
debops.nscd - Manage Name Service Cache Daemon with Ansible

SYNOPSIS

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

DESCRIPTION

The Name Service Cache Daemon is a local service which caches NSS database information from remote sources like LDAP, Active Directory or NIS. The service is useful in combination with the nslcd (managed by the debops.nslcd role) to lower the number of queries to the remote databases and make system operations faster.

The debops.nscd Ansible role supports two flavors of the caching service, the original nscd implemented by GNU libc library, as well as its drop-in replacement, unscd, created by the BusyBox project. The unscd version is installed by default.

GETTING STARTED

  Example inventory

To enable the nscd service on a host, you need to add it to the [debops_service_nscd] Ansible inventory group.

[debops_service_nscd]
hostname

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

[debops_all_hosts]
hostname1
hostname2
[debops_service_nscd:children]
debops_all_hosts

The nscd service can also be installed and configured by other playbooks, for example bootstrap-ldap.yml. In such cases the custom playbook will configure the nscd 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_nscd] 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.nscd role:

---
- name: Manage Name Service Cache Daemon
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_nscd' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: nscd
      tags: [ 'role::nscd', 'skip::nscd' ]

  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::nscd
    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.nscd Ansible role:

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

DEFAULT VARIABLE DETAILS

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

  nscd__configuration

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

  Examples

See nscd__default_configuration variable for an example of existing configuration.

  Syntax

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

name
    Required. Name of the NSS service to cache. If the name parameter is set to 'global', and the options parameter is defined, this creates a special "global" section at the beginning of the configuration file.

    The name parameter is used as an anchor to merge multiple configuration entries with the same name together.

state
    Optional. If not specified or present, a given configuration section will be included in the generated configuration file. If absent, a given configuration section will be removed from the generated file. If comment, the configuration section will be present, but commented out.

comment
    Optional. String or YAML text block with a comment added before a given configuration section.

options
    Optional. A list of configuration options which should be included in a given configuration section. This parameter only makes sense in the "global" section, and otherwise should not be present in configuration entries. See the nscd.conf(5) <https://manpages.debian.org/nscd.conf(5)> manual page for the possible configuration options.

    Each list element is defined as a YAML dictionary with specific parameters:

name
    Required. The configuration option name.

value
    Required. The configuration option value. Can be defined as a string, an integer or a boolean.

state
    Optional. If not specified 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 configuration option will be present, but commented out.

    The parameters described below are based on the configuration options defined in the nscd.conf(5) <https://manpages.debian.org/nscd.conf(5)> manual page. All of the parameters are usually required for a given configuration section to work; different nscd flavors will use different parameters.

enable_cache
    Boolean. Enable or disable cache for a given NSS service.

positive_time_to_live
    Number of seconds after which an existing entry is removed from cache.

negative_time_to_live
    Number of seconds after which a non-existent entry is removed from cache.

suggested_size
    Size of the hash that is used to store cached entries. Its value should be a prime number.

check_files
    Boolean. If True, the service checks the contents of the /etc/passwd, /etc/group and /etc/hosts files and invalidates the cached entries if the files changed.

persistent
    Boolean. If True, cached entries of a given NSS service will be kept between nscd daemon restarts.

shared
    Boolean. If True, the memory mapped for cache is shared with the service clients directly instead of forcing them to talk to the daemon.

max_db_size
    Specify the maximum size of the cache for a given NSS service.

auto_propagate
    Boolean. When set to False for the passwd or group service, then the .byname requests are not added to passwd.byuid or group.bygid cache. This may help for tables containing multiple records for the same id value.

AUTHOR
Maciej Delmanowski

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