nsscache.conf - NSS local cache synchroniser configuration
file
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.
- 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.
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.
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
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 ...
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.
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
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:::
- /etc/nsscache.conf
- The system-wide nsscache configuration file
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.