Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NSSCACHE.CONF(5)		 File formats		      NSSCACHE.CONF(5)

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 reliabil-
       ity of name services.

       The nsscache configuration file comprises of one	DEFAULT	section,  fol-
       lowed  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,  specify-
       ing  the	data source to use, one	cache keyword, specifying the means in
       which the cache data will be stored locally, one	maps keyword, specify-
       ing  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 op-
       tions 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

       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 for-
	      mat   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  in-
	      dex  file	 will be written alongside, for	use with the nss-cache
	      NSS module.  (See	https://github.com/google/libnss-cache.)

	      nssdb Store in a Berkeley	DB file, for use with the  nss_db  NSS
	      module.  Please note that	this option is deprecated in favour of
	      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 dis-
	      abled 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	(unen-
	      crypted)	 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  us-
	      ing 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 ex-
	      isting uidNumber and gidNumber.

       ldap_uidregex
	      A	Python regex to	extract	uid components from the	 uid-like  at-
	      tribute.	 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 mem-
	      ber or memberOf attributes.  All matching	 groups	 are  concate-
	      nated  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  synchro-
	      nization 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 de-
	      fault.

       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 li-
	      brary 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

nssdb CACHE OPTIONS
       These options configure the behaviour of	the nssdb cache.

       nssdb_dir
	      Directory	 to  store the Berkeley	DB databases.  Defaults	to the
	      current directory.  Note	that  nss_db  hardcodes	 the  path  to
	      /var/db/nsscache	on Debian systems, and /var/db on Red Hat sys-
	      tems.

       nssdb_makedb
	      Path to the makedb(1) command, which is used by the nssdb	 cache
	      code  to ensure that the Berkeley	DB version created by the mod-
	      ule matches that expected	by the nss_db NSS module.

files CACHE OPTIONS
       These optiosn 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 = nssdb
	 maps =	passwd,	group, shadow
	 ldap_uri = ldap://ldap.example.com
	 ldap_base = ou=People,dc=example,dc=com
	 ldap_filter = (objectclass=posixAccount)
	 nssdb_dir = /var/db/nsscache

	 [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 db
	 group:	files db
	 shadow: files db

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 (C) 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.

nsscache 0.39			  2019-11-12		      NSSCACHE.CONF(5)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT-only OPTIONS | ldap SOURCE OPTIONS | s3 SOURCE OPTIONS | nssdb CACHE OPTIONS | files CACHE OPTIONS | EXAMPLE | FILES | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nsscache.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help