Provided by: nsscache_0.49-2_all bug

NAME

       nsscache.conf - NSS local cache synchroniser configuration file

SYNOPSIS

       /etc/nsscache.conf

DESCRIPTION

       nsscache  synchronises  a  local  NSS  cache,  and  other databases, against a remote data
       source. This approach allows the administrator to separate the network from the NSS lookup
       codepath, improving speed and reliability of name services.

       The nsscache configuration file comprises of one DEFAULT section, followed by zero or more
       map-specific configuration sections.  The file format is similar to that of ".ini" files.

       The DEFAULT section must provide at least one source keyword, specifying the  data  source
       to  use,  one  cache  keyword, specifying the means in which the cache data will be stored
       locally,  one  maps  keyword,  specifying  which  NSS  maps  should  be  cached,  and  one
       timestamp_dir  keyword,  specifying  the  location  of the timestamps used for incremental
       updates.

       Additional global defaults, such as LDAP search parameters, or the filesystem location  of
       the cache, may also be included in the DEFAULT section.

       Additional sections may be included that allow per-map overrides to configuration options.
       For example, one might specify their global LDAP search base  as  ou=People  but  want  to
       override that for the group mapping as ou=Groups

       Apart  from the source, cache, and maps configuration options, all options are prefixed by
       the name of the module that they configure.

       A complete list of configuration options follows.

DEFAULT-only OPTIONS

       source Specifies the source to use to retrieve NSS data from.

              Valid Options: ldap, s3, http, gcs

       cache  Specifies the cache method to use to store the data, which will be queried  by  the
              NSS itself.

              Valid  options: files Store in a plain text file, similar in format to /etc/passwd.
              If the files-module option files_cache_filename_suffix is also set  to  cache  then
              not  only  will  the  files be created with a .cache suffix, but also an index file
              will  be  written  alongside,  for  use  with  the  nss-cache  NSS  module.    (See
              https://github.com/google/libnss-cache.)

       maps   Specifies the names of the maps that will be queried and cached by nsscache

              Valid options: passwd group shadow netgroup automount sshkey

       timestamp_dir
              Specifies the directory where update and modify timestamps are stored.

ldap SOURCE OPTIONS

       These options configure the behaviour of the ldap source.

       ldap_ad
              Set  to  1  if connecting to Active Directory. If enabled, default Active Directory
              attributes will be used for mapping. Leave disabled if connecting to openldap.

       ldap_uri
              The LDAP URI to connect to.

       ldap_base
              The base to perform LDAP searches under.

       ldap_filter
              The search filter to use when querying.

       ldap_scope
              The search scope to use.  Defaults to one

              Valid options: sub[tree] one[level] base

       ldap_bind_dn
              The bind DN to use when connecting to LDAP.  Empty string  is  an  anonymous  bind.
              Defaults to the empty string.

       ldap_bind_password
              The  bind  password  to  use  when  connecting  to  LDAP.  Empty string is used for
              anonymous binds.  Defaults to the empty string.

       ldap_timelimit
              Timelimit in seconds for search results to return.  -1 means no limit.  Defaults to
              -1.

       ldap_retry_max
              Number of retries on soft failures before giving up.  Defaults to 3.

       ldap_retry_delay
              Delay in seconds between retries.  Defaults to 5.

       ldap_tls_require_cert
              Sets  expectations  for  SSL  certificates,  using  TLS.   One  of 'never', 'hard',
              'demand', 'allow', or 'try' ('demand' is the default).  See ldap.conf(5)  for  more
              information.

       ldap_tls_cacertdir
              Directory  for  trusted  CA  certificates.   By  default,  the  system's default CA
              certificate directory will be used.

       ldap_tls_cacertfile
              Filename containing trusted CA certificates.

       ldap_tls_certfile
              Filename of an optional LDAP client  certificate.  If  specified,  ldap_tls_keyfile
              must also be specified.

       ldap_tls_keyfile
              Filename  of  an  optional  LDAP client key.  Only plaintext (unencrypted) keys are
              currently supported.  If specified, ldap_tls_certfile must also be specified.

       ldap_tls_starttls
              Set to 1 to enable STARTTLS. Leave absent to disable.

       ldap_uidattr
              The uid-like attribute in your directory. Defaults to uid.

       ldap_use_rid
              If enabled (set to 1) the relative identifier (RID) wll be used  for  mapping.   By
              default  uidNumber  and gidNumber will be mapped when connecting to OpenLDAP with a
              POSIX-like schema.  When using Samba4 AD,  these  attributes  won't  exist.   Leave
              disabled for default.  It has no effect if the option ldap_ad is enabled.

       ldap_offset
              Default Offset option to map uidNumber and gidNumber to higher number.  This can be
              useful to avoid conflict with already existing uidNumber and gidNumber.

       ldap_uidregex
              A Python regex to extract uid components from the uid-like attribute.  All matching
              groups  are  concatenated  without  spaces.  For example:  '(.*)@example.com' would
              return a uid to the left of the @example.com domain.  Default is no regex.

       ldap_groupregex
              A Python regex to extract group member  components  from  the  member  or  memberOf
              attributes.   All  matching  groups  are concatenated without spaces.  For example:
              '(.*)@example.com' would return a  member  without  the  the  @example.com  domain.
              Default is no regex.

       ldap_nested_groups
              To  enable  expansion  of nested groups, set this to 1. Note that this only applies
              during a full sync, and incremental synchronization should not be used if  this  is
              set.

       ldap_override_shell
              If  specified,  set  every  user's  login  shell to the given one. May be useful on
              bastion hosts or to ensure  uniformity.  Enable  for  Active  Directory  since  the
              attribute (loginShell) is not default.

       ldap_home_dir
              Set a home directory for all users in passwd. If enabled (set to 1), all users will
              have their home directory in /home.

       ldap_rfc2307bis
              Default uses rfc2307 schema. If rfc2307bis (groups stored  as  a  list  of  DNs  in
              'member' attr), set this to 1.

       ldap_debug
              Sets the debug level for the underlying C library.  Defaults to no logging.

s3 SOURCE OPTIONS

       These options configure the behaviour of the s3 source.

       s3_bucket
              AWS  S3  bucket  containing  passwd,  group,  shadow objects.  boto3 python package
              should be installed to use this type of source.  It is highly recommended to use s3
              source only with AWS IAM role attached to the ec2 instance configured for read-only
              access to the bucket.  So no extra configuration options like access_key and secret
              provided   in   config.    Though   they   may   be   used  via  ~/.aws/config  and
              ~/.aws/credentials because python boto3 library used in implementation  is  capable
              to read them by itself.

       s3_passwd_object
              Object  containing passwd array of records in json format. E.g.  [{"Value": {"gid":
              10000, uid : 10000}, Key : user1 }].  Valid attributes: comment , home  ,  shell  ,
              passwd , gid , uid

       s3_group_object
              Object  containing  group array of records in json format. E.g.  [{"Value": {"gid":
              20000, members : user10ser20ser3 }, Key :  group1  }].   Valid  attributes:  gid  ,
              members Members should be sequence of usernames split by \n (see example above)

       s3_shadow_object
              Object  containing  shadow  array  of  records  in  json  format.  E.g.  [{"Value":
              {"passwd": * }, Key : user1 }].  Valid attributes: passwd , lstchg , min  ,  max  ,
              warn , inact , expire

       s3_sshkey_object
              Object  containing  sshkey  array  of  records  in  json  format.  E.g.  [{"Value":
              {"sshPublicKey": ssh-rsa ... }, Key : user1 }].  Valid attributes: sshPublicKey

http SOURCE OPTIONS

       These options configure the behaviour of the http source.

       http_passwd_url
              URL for an HTTP endpoint that returns a  file  containing  passwd  records  in  the
              standard format. E.g.  root:*:0:0:System Administrator:/var/root:/bin/sh

       http_group_url
              URL  for  an  HTTP  endpoint  that  returns  a file containing group records in the
              standard format. E.g.  users:x:100:memberships....

       http_shadow_url
              URL for an HTTP endpoint that returns a  file  containing  shadow  records  in  the
              standard format. E.g.  root:*:18866:0:99999:7:::

       http_sshkey_url
              URL  for  an  HTTP  endpoint  that  returns a file containing sshkey records in the
              standard format. E.g.  root:ssh-rsa ...

files CACHE OPTIONS

       These options configure the behaviour of the files cache.

       files_dir
              Directory location to store the plain text  files  in.   Defaults  to  the  current
              directory.

       files_cache_filename_suffix
              A  suffix  appended to the cache filename to differentiate it from, say, system NSS
              databases.  Defaults to '.cache'.

       files_local_automount_master
              A yes/no field only used for automount maps.  A 'yes' value will cause nsscache  to
              update the auto.master file with the master map from the source.  A 'no' value will
              cause nsscache to leave auto.master alone, allowing the system to manage this  file
              in  other  ways.   When set to 'no', nsscache will only update other automount maps
              defined both locally and in the source.  Defaults to 'yes'.

       prefix A regular expression to capture a prefix, or mount point.

       suffix A regular expression to modify the prefix.

EXAMPLE

       A typical example might look like this:

         [DEFAULT]
         source = ldap
         cache = files
         maps = passwd, group, shadow
         ldap_uri = ldap://ldap.example.com
         ldap_base = ou=People,dc=example,dc=com
         ldap_filter = (objectclass=posixAccount)

         files_dir = /etc
         files_cache_filename_suffix = cache

         [group]
         ldap_base = ou=Group,dc=example,dc=com
         ldap_filter = (objectclass=posixGroup)
         ldap_nested_groups = 1

         [shadow]
         ldap_filter = (objectclass=posixAccount)

       And a complementary /etc/nsswitch.conf might look like this:

         passwd: files cache
         group: files cache
         shadow: files cache

gcs SOURCE OPTIONS

       These options configure the behaviour of the gcs source.

       gcs_bucket
              Google Cloud Storage bucket containing passwd, group, shadow blobs.

              gcs_passwd_object Name for a object  containing  passwd  records  in  the  standard
              format. E.g.  root:*:0:0:System Administrator:/var/root:/bin/sh

              gcs_group_object  Name for a object containing group records in the standard format
              E.g.  users:x:100:memberships....

              gcs_shadow_object Name of the object containing  shadow  records  in  the  standard
              format. E.g.  root:*:18866:0:99999:7:::

FILES

       /etc/nsscache.conf
              The system-wide nsscache configuration file

SEE ALSO

       nsscache(1)

       nsswitch.conf(5)
              The system name service switch configuration file

       ldap.conf(5)
              Details on LDAP configuration options exposed by the LDAP client libraries.

AUTHOR

       Written by Jamie Wilkinson (jaq@google.com) and Vasilios Hoffman (vasilios@google.com).

       The source code lives at https://github.com/google/nsscache

COPYRIGHT

       Copyright © 2007 Google, Inc.
       This  is  free software; see the source for copying conditions.  There is NO warranty; not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.