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

FreeBSD Manual Pages

  
 
  

home | help
lookupd(8)		  BSD System Manager's Manual		    lookupd(8)

NAME
     lookupd --	directory information and cache	daemon

SYNOPSIS
     lookupd

     lookupd -d

     lookupd -D	portname

     lookupd -f	category key value

     lookupd -q	category [[-a key [value ...]] ...]

     lookupd -configuration

     lookupd -flushcache

     lookupd -statistics

DESCRIPTION
     The lookupd daemon	acts as	an information broker and cache.  It is	called
     by	various	routines in the	System framework to find information about
     user accounts, groups, printers, e-mail aliases and distribution lists,
     computer names, Internet addresses, and several other kinds of informa-
     tion.

     lookupd keeps a cache of recently requested items to improve system per-
     formance.	It also	implements a search strategy used to find information
     from the many information sources that are	potentially available to a
     computer.	These include the Domain Name System (DNS), Sun	Microsystem's
     Network Information Services (NIS),  Apple's NetInfo system, and a	set of
     files found in the	/etc directory.	 lookupd also has a channel to query
     Directory Services, allowing access to data from LDAP and other directory
     systems.

     The lookupd process is monitored by the system's mach server registry
     (the mach_init process), and is automatically restarted if	it crashes or
     exits.  lookupd responds to a HUP signal by exiting.  This	is the pre-
     ferred mechanism for restarting / resetting the process.

     lookupd writes its	process	ID number in the file /var/run/lookupd.pid.

LOOKUP STRATEGY
     Internally, lookupd uses a	set of software	"agents" to get	information.
     There are agents for NetInfo, NIS,	DNS, the files in /etc (also known as
     the "Flat Files" ), Directory Services, and an agent which	manages	the
     internal cache.  There is also a special agent (the NILAgent) which re-
     turns negative entries.

     When lookupd searches for information about an item, it queries agents in
     a specific	order until the	item is	found or until all sources of informa-
     tion have been consulted without finding the desired item.	 By default,
     lookupd first queries its cache agent, then NetInfo, then the Directory
     Services agent.  If the item is a host or network,	lookupd	will query the
     cache, the	Flat File agent, then the DNS agent, then NetInfo, and Direc-
     tory Services last.  The default search order for services, protocols,
     and rpc protocols uses the	cache, then the	Flat File agent, NetInfo, and
     then Directory Services.

     In	some cases, lookupd creates lists of all the information available
     about some	sort of	entity.	 For example, all printers or all users.  In
     these cases lookupd queries each agent in turn and	concatenates all re-
     trieved information into a	single list.

     The search	order is configurable.	For example, you might specify that
     lookupd queries its internal cache, then NetInfo, then the	Flat Files,
     then NIS.	You may	also change the	lookup order for a particular category
     of	item.  The known categories are	users, groups, hosts, networks,	ser-
     vices, protocols, rpcs, mounts, printers, bootparams, bootp, aliases, and
     netgroups.	 You can set the lookup	order (and other configuration op-
     tions) for	all categories,	and override them for individual categories.
     Details on	configuring lookupd are	found in the CONFIGURATION section be-
     low.

     Some agents may have their	own configuration options.  Details on config-
     uring individual agents are found in the AGENTS section below.

CACHE
     There are caches for all categories of lookups.  The caches are unlimited
     in	capacity (although you can set a maximum size, see below).  The	de-
     fault lookup order	starts with the	cache agent for	each lookup category.
     Caching may be disabled for all categories	or for specific	categories by
     removing the cache	agent from the lookup order.

   CACHE VALIDATION
     lookupd validates items retrieved from cache before returning them.  If
     an	entry is invalid, a fresh copy is fetched to replace the stale one in
     cache.  In	many cases it is possible for lookupd to quickly determine
     that a cached entry is still valid; for example by	checking a time	stamp
     or	a database sequence number.  When cache	validation is enabled, perfor-
     mance is enhanced because many items can be stored	in cache, while	at the
     same time clients can be certain that any data they get from lookupd is
     as	up-to-date as possible.	 If cache validation is	disabled, items	are
     returned from cache without any checks.  In this case it is possible that
     the information is	out-of-date.  You can place limits on how stale	an
     item might	be by setting the cache	TimeToLive (see	below).

     You can also get the best of both worlds by having	cache validation en-
     abled and adjusting the ValidationLatency.	 If an agent has just fetched
     a database	version	number or read a time stamp in order to	validate one
     item in the cache,	then it	can use	that value for a few seconds to	vali-
     date other	entries	in the cache with only a small risk that those entries
     have become out-of-date.  Setting ValidationLatency to 0 seconds causes
     validation	on every fetch from cache.  Setting the	value to a larger num-
     ber means that lookupd will avoid re-checking time	stamps,	sequence num-
     bers, version numbers or other validation indicators for the indicated
     number of seconds.	 This allows you to say, for example, that you are
     willing to	let the	cache return an	item that might	be no more than	a few
     seconds out-of-date in order to reduce network traffic.  The default
     value for ValidationLatency is 15 seconds.

     Validation	is enabled by default, but may be disabled for all categories,
     or	for specific categories.  For example, since computer names and	ad-
     dresses very rarely change, you might want	to turn	off cache validation
     for the host cache	to save	time and reduce	network	traffic.  This is es-
     pecially useful on	slow network lines.  If	network	access is fast,	cache
     validation	is inexpensive,	and ensures that all data is up-to-date.

     The cache validation strategy in the NetInfo and Flat File	agents makes
     validation	as fast	and inexpensive	as possible.  DNS validation is	based
     on	the time-to-live value found in	the DNS	record for a particular	item.

     The NILAgent returns a negative record for	any lookup.  This stops	fur-
     ther search for an	item.  The NILAgent should always appear last in any
     LookupOrder specification (see below).  The value of these	negative
     records is	that they will be added	to the cache (if caching is enabled).
     If	a lookup for a particular item fails (after a long, slow search	of all
     available information sources), then subsequent lookups for the same item
     will find the negative record in the cache, thus avoiding another long
     search.  Like all other cached records, negative records are validated.
     By	default, negative records are valid for	60 seconds.  You can override
     the default by setting the	TimeToLive option in the NILAgent's configura-
     tion.  See	the AGENT section below.

     When an object is placed in a cache, it is	given a	time to	live.  After
     that time has expired, it will be removed from the	cache.	The default is
     12	hours.	Making things expire more quickly will cause the cache to stay
     smaller, but will result in more network traffic.	Whenever an object is
     validated,	its time to live is reset.

CONFIGURATION
     Configuration parameters may be placed in a set of	files in the local
     file system, or they may be written in a set of directories in NetInfo.
     These parameters will override default settings.  There may be one	file
     or	one configuration directory in NetInfo for each	agent, and one file or
     NetInfo directory for each	lookup category.  There	may also be a global
     configuration file	or NetInfo directory.  Additionally, each agent	may
     have category-specific configuration.

     lookupd searches for configuration	in the local file system first.	 If no
     configuration is given in the file	system,	lookupd	checks for a configu-
     ration directory in the local NetInfo domain.

     The configuration source may be specified on the command line as a
     startup option.  The configuration	source may be specified	using one of
     the following command-line	options:

	   -c default
	   -c file path
	   -c netinfo domain path

   FILE-BASED CONFIGURATION
     Configuration settings for	lookup may be placed in	files under the	direc-
     tory /etc/lookupd.	 A file	named "global" is used to store	global set-
     tings for lookupd and for individual agents.  Other files specify set-
     tings for each lookup category.  It is not	necessary to create every con-
     figuration	file.  Just create those in which you wish to override the de-
     fault values of configuration parameters.	The files that may be created
     are:

	   /etc/lookupd/global
	   /etc/lookupd/users
	   /etc/lookupd/groups
	   /etc/lookupd/hosts
	   /etc/lookupd/networks
	   /etc/lookupd/services
	   /etc/lookupd/protocols
	   /etc/lookupd/rpcs
	   /etc/lookupd/mounts
	   /etc/lookupd/printers
	   /etc/lookupd/bootparams
	   /etc/lookupd/bootp
	   /etc/lookupd/aliases
	   /etc/lookupd/netgroups
	   /etc/lookupd/agents
	   /etc/lookupd/agents/CacheAgent/global
	   /etc/lookupd/agents/DNSAgent/global
	   /etc/lookupd/agents/FFAgent/global
	   /etc/lookupd/agents/NIAgent/global
	   /etc/lookupd/agents/NILAgent/global
	   /etc/lookupd/agents/NISAgent/global

     Category-specific configuration files may appear in an agent's subdirec-
     tory.  For	example, category-specific files for NIAgent are:

	   /etc/lookupd/agents/NIAgent/global
	   /etc/lookupd/agents/NIAgent/users
	   /etc/lookupd/agents/NIAgent/groups
	   /etc/lookupd/agents/NIAgent/hosts
	   /etc/lookupd/agents/NIAgent/networks
	   /etc/lookupd/agents/NIAgent/services
	   /etc/lookupd/agents/NIAgent/protocols
	   /etc/lookupd/agents/NIAgent/rpcs
	   /etc/lookupd/agents/NIAgent/mounts
	   /etc/lookupd/agents/NIAgent/printers
	   /etc/lookupd/agents/NIAgent/bootparams
	   /etc/lookupd/agents/NIAgent/bootp
	   /etc/lookupd/agents/NIAgent/aliases
	   /etc/lookupd/agents/NIAgent/netgroups

     Note that only some agents	make use of category-specific configurations.
     They are described	in the AGENTS section below.

   NETINFO-BASED CONFIGURATION
     Configuration directories in NetInfo must be placed in a subtree begin-
     ning at either the	/config/lookupd	or the /locations/lookupd directory.
     /config/lookupd is	checked	first, and /locations/lookupd is checked if
     /config/lookupd does not exist.  /locations/lookupd may contain global
     settings, stored as values	for various keys.  Configuration options for
     specific categories reside	in the directories:

	   /locations/lookupd/users
	   /locations/lookupd/groups
	   /locations/lookupd/hosts
	   /locations/lookupd/networks
	   /locations/lookupd/services
	   /locations/lookupd/protocols
	   /locations/lookupd/rpcs
	   /locations/lookupd/mounts
	   /locations/lookupd/printers
	   /locations/lookupd/bootparams
	   /locations/lookupd/bootp
	   /locations/lookupd/aliases
	   /locations/lookupd/netgroups

     There may also be configuration directories for each agent.  These	must
     be	subdirectories of the /locations/lookupd/agents	directory:

	   /locations/lookupd/agents/CacheAgent
	   /locations/lookupd/agents/DNSAgent
	   /locations/lookupd/agents/FFAgent
	   /locations/lookupd/agents/NIAgent
	   /locations/lookupd/agents/NILAgent
	   /locations/lookupd/agents/NISAgent

     Each of these agent-specific directories may have category	specific sub-
     directories, for example:

	   /locations/locations/agents/NIAgent/printers
	   /locations/locations/agents/NIAgent/hosts
	   ...

   CONFIGURATION KEYS
     If	configuration parameters are stored in a file, each line of the	file
     will be of	the form:

	   key value [value ...]

     Lines beginning with "#" are treated as comments.

     Configuration directories in NetInfo have property	keys and values	as
     specified below.

     Keys and permissible values for the main (global) lookupd configuration
     directory or file are shown in the	following table.  keys and values that
     apply to specific agents are described in the AGENTS section.

	 LogFile
	 Name of a log file that contains a copy of all	messages sent to sys-
	 log.  There is	no default (i.e. no log	file is	kept).

	 LogPriority
	 Sets the maximum priority that	will be	logged.	 Note that syslog's
	 highest priority (LOG_EMERG) is 0, with priority 7 being the lowest
	 priority (LOG_DEBUG).	The default is LOG_NOTICE, meaning that	only
	 messages of LOG_NOTICE	or higher priority will	be logged.  This value
	 can also be set on the	command	line using the -l priority option.

	 StatisticsEnabled
	 If given the value YES, this setting will enable statistics-gather-
	 ing.  These statistics	can then be fetched by calling lookupd with
	 the -statistics command line option.  Details on these	statistics are
	 found in the PERFORMANCE TUNING AND TROUBLESHOOTING section.  The de-
	 fault value is	NO, unless lookupd is run in debug mode	with the -d or
	 -D options.

	 Debug
	 If given the value YES, statistics gathering is enabled, and the Log-
	 Priority is set to LOG_DEBUG.

	 MaxThreads
	 Maximum number	of threads in the query	dispatcher.  The default is
	 64.  Under moderatly heavy load, only 5 or 6 threads are used,	so 64
	 is usually more than enough.

	 MaxIdleThreads
	 When a	thread finishes	servicing a query, it will usually go back to
	 the message queue to wait for another query.  This setting limits the
	 maximum number	of idle	threads	waiting	on the queue.  If a thread
	 finishes servicing a query and	MaxIdleThreads are already waiting on
	 the queue, the	thread will exit.  The default value is	2.

	 MaxIdleServers
	 The dispatcher	uses a server object to	actually answer	a client
	 lookup.  One server is	required for each active thread.  The dis-
	 patcher keeps a pool of servers so that they can be re-used.  This
	 setting limits	the maximum number of servers in the pool, waiting for
	 a query to answer.  The default value is 4.

	 ValidateCache
	 This boolean value determines whether cache validation	is enabled for
	 all cache categories.	The default is YES.  Use NO to disable valida-
	 tion.	The setting of this value may be over-ridden for specific
	 cache categories (see below).

	 ValidationLatency
	 If Cache validation is	enabled, this integer value specifies the num-
	 ber of	seconds	that may elapse	between	successive validation checks
	 for a particular agent.  The default is 15 seconds.  This value ap-
	 plies to specific agents rather than to the cache.  The setting of
	 this value may	be over-ridden for specific agents (see	below).

	 CacheCapacity
	 Maximum number	of objects in the cache	for each category (e.g.	this
	 many users, this many hosts, ...).  Least-recently-used objects are
	 removed when space is required.  By default, there is no limit	to the
	 cache size.

	 TimeToLive
	 Time to live (measured	in seconds) in cache.  The default is 43200
	 seconds (12 hours).  This is the default mechanism used to limit the
	 growth	of the cache.

	 LookupOrder
	 Sets the lookup order for all categories, although you	may override
	 this for specific categories.	This key takes multiple	values.	 The
	 default for most categories is	CacheAgent, NIAgent, and then DSAgent.
	 For hosts and networks, the default lookup order is CacheAgent, FFA-
	 gent, DNSAgent, NIAgent, then DSAgent.	 For services, protocols, and
	 rpc, the default order	is CacheAgent, FFAgent,	NIAgent, then DSAgent.
	 Details about specifying agents in a lookup order may be found	in the
	 AGENTS	section.

	 Timeout
	 Time to wait for a response from a server.  The default value is 30
	 seconds.  Note	that this timeout applies individually to all agents.
	 It is not a global timeout for	any lookupd query.  The	total time
	 that might be taken for a single query	to lookupd depends on how many
	 agents	are involved in	the lookup order for that category of item.

     Options that can be set per lookup	category are ValidateCache,
     CacheCapacity, TimeToLive,	and LookupOrder.

AGENTS
     As	described above, agents	are specified as values	of a LookupOrder con-
     figuration	key.  As a convenience,	agent names may	be shortened by	omit-
     ting the trailing string "Agent" from their name.	Thus, for example, DNS
     may be used in place of DNSAgent.

     An	optional starting argument may be provided to an agent following a
     colon character.  For example, to use a Flat File agent that reads	from
     files in the directory /var/db/files rather than from files in /etc, you
     could specify:

	   FF:/var/db/files

     This mechanism allows you to specify several agents of the	same type,
     each with a different starting argument.  For example, several Flat File
     agents reading from different directories,	or several DNS agents using
     different domains.	 Starting options are described	for each agent in the
     sections below.

   CacheAgent
     The operation and configuration of	the cache agent	are described in de-
     tail in the sections above.  The configuration options for	the Cache
     agent are ValidateCache, CacheCapacity, and TimeToLive. These options may
     be	set globally and/or for	specific categories.  Options set for a	spe-
     cific category will over-ride the global setting.

     Note that CacheAgent should always	appear first in	a LookupOrder specifi-
     cation to allow lookupd to	find cached entries before searching other in-
     formation services.

     CacheAgent	does not support a startup argument (as	described at the be-
     ginning of	this section).

   NIAgent
     NIAgent is	the NetInfo client.  It	supports the Timeout, ConnectTimeout,
     ValidationLatency and DomainOrder options.

     The Timeout option	specifies a NetInfo read timeout in seconds.  This
     timeout is	applied	to all NetInfo lookups.

     ConnectTimeout controls timeouts on initial NetInfo connections done at
     startup time, and applies to all domains other than the local domain.
     The default value is 300 seconds.	A zero value indicates an unlimited
     timeout.

     ValidationLatency is described above in the section.  NIAgent validates
     cached entries by checking	the NetInfo server's database checksum.	 The
     NetInfo checksum changes whenever the database changes.  Thus, any	time a
     NetInfo domain is updated,	all cached entries from	that domain will be
     invalidated.

     The DomainOrder option was	the original mechanism implemented to allow
     you to specify a list of NetInfo domains (or specific NetInfo servers)
     that should be queried for	information.  A	search order may now be	speci-
     fied by using the startup argument	(see below).  However, the DomainOrder
     option is still supported for backward compatibility.

     By	default, the NetInfo agent starts with a computer's local domain, then
     climbs the	NetInfo	hierarchy until	reaching the root domain.  In very
     rare cases, you might find	that you can solve a difficult network admin-
     istration problem by altering the default lookup order.  Using this op-
     tion can make your	information systems configuration very confusing and
     spaghetti-like, so	exercise great caution in its use!

     The domain	search order may be set	globally (for all categories of
     lookups), and/or for specific categories.	A domain order for a specific
     category will over-ride the global	order for for lookups of that type
     (e.g. for user lookups).

     The DomainOrder option may	have multiple values.  Each value specifies a
     domain or a specific NetInfo server.  Domain names	may be absolute	paths
     starting at the root domain (e.g. /sales, /sol/jupiter), or a path	rela-
     tive to the local domain (e.g. ../zippy, ../../marketing).	 A "." stands
     for the local domain.  You	may also specify a domain relative to a	remote
     computer by using a value of the form

	   nidomain:path@address
     or
	   path@address

     For example, If you used the value

	   nidomain:/central@192.42.172.1

     NIAgent would connect to the computer with	Internet address 192.42.172.1
     and locate	the domain named /central relative to that computer.

     You can also include values of the	form

	   niserver:tag@address
     or
	   tag@address

     to	connect	to a specific NetInfo server.  For example,

	   niserver:network@192.42.172.5

     would contact the server for the database tagged network at the given ad-
     dress.

     You may set the DomainOrder for a particular lookup category by creating
     a category-specific configuration directory (for NetInfo-based configura-
     tions) or file (for file-based configurations).

     A LookupOrder may specify one or more NIAgents, each with a startup argu-
     ment.  The	startup	argument for NIAgent is	a comma	separated list of do-
     main or server specifications.  This includes the forms supported for the
     DomainOrder configuration key (see	above),	and may	also include the
     string "..." which	specifies that NIAgent should include all domains from
     the previous one specified	in the list up to the root domain of that Net-
     Info hierarchy.

     As	it is the case with the	DomainOrder list, you should use this facility
     with great	care, for you can easily make the search order very confusing.

     Some LookupOrder examples may help	clarify	the NIAgent startup argument.

      "	-compact -offset indent

     NI:.,extra@10.0.0.17	  Local	domain,	then "extra" at	10.0.0.17;

     NI:network@192.42.172.1,...  Start	with "network" at the specified	ad-
				  dress, then climb from that domain to	the
				  root domain.

   NISAgent
     The NISAgent is the NIS client.  The names	YPAgent	and YP are aliases for
     the NISAgent.

     The NIS domain name must be set before lookupd starts, or this agent will
     not be able to connect to a server	(in which case it does nothing).  The
     NIS domain	name is	usually	set during system startup using	the value of
     the NISDOMAIN variable in the file	/etc/hostconfig.  For example:

	   NISDOMAIN=quinta

     NISAgent supports the Timeout and ValidationLatency configuration op-
     tions.  NISAgent validates	entries	by checking the	map order numbers.

     Note that lookupd has separate agents for the Flat	Files (see FFAgent be-
     low) and NIS.  NIS	and the	files are viewed as independent	information
     systems.  You may use either agent	or both	in any order.

     NISAgent reads the	following maps.	 Note that some	of these maps are ex-
     tensions to the standard set of maps created by most YP servers.

	   ethers.byaddr	 Host names keyed by Ethernet address
	   bootptab.byaddr	 Bootp data keyed by Ethernet address
	   mail.aliases		 E-mail	aliases	and distribution lists
	   passwd.byname	 Users
	   passwd.byuid		 Users
	   group.byname		 Groups
	   group.bygid		 Groups
	   hosts.byname		 Hosts
	   hosts.byaddr		 Hosts
	   networks.byname	 Networks
	   networks.byaddr	 Networks
	   services.byname	 TCP/IP	service	ports and protocols
	   protocol.byname	 IP Protocols
	   protocol.bynumber	 IP Protocols
	   rpc.byname		 ONC RPC programs
	   rpc.bynumber		 ONC RPC programs
	   mounts.byname	 Mounts	(fstab entries)	keyed by name (fspec)
	   printcap.byname	 Printers (printcap entries) keyed by name
	   bootparams.byname	 Bootparams entries keyed by name
	   bootp.byip		 Bootp entries keyed by	IP address
	   netgroup		 Netgroups

     NISAgent does not support a startup argument.

   DNSAgent
     DNSAgent is the DNS client.  Cached DNS entries are validated simply by
     the time-to-live associated with the DNS records.	DNSAgent is only used
     for host name/address and network name/address resolution.

     The Mac OS	X DNS library used by the DNS agent allows the system to have
     a number of separate DNS clients.	Each DNS client	has the	address	of one
     or	more DNS servers (which	the client regards as being equivalent).
     Please refer to the resolver(5) man page for details on the Mac OS	X DNS
     resolver.

   FFAgent
     The FFAgent reads the "Flat Files"	in your	computer's /etc	directory.
     Specifically, it reads the	files:

	   /etc/master.passwd	  Users
	   /etc/group		  Groups
	   /etc/hosts		  Computer names and addresses
	   /etc/networks	  Network names	and addresses
	   /etc/services	  TCP/IP service ports and protocols
	   /etc/protocols	  IP protocol names and	numbers
	   /etc/rpcs		  ONC RPC servers
	   /etc/fstab		  NFS mounts
	   /etc/printcap	  Printers
	   /etc/bootparams	  Bootparams settings
	   /etc/bootp		  Bootp	settings
	   /etc/aliases		  E-mail aliases and distribution lists
	   /etc/netgroup	  Netgroups

     FFAgent supports a	directory path as an optional startup argument,	which
     is	used in	place of /etc.

     By	default, the FFAgent will read in and cache the	entire contents	of the
     /etc/hosts	file.  This is a performance optimization.  The	hosts file is
     frequently	consulted since	it is in the default LookupOrder for hosts,
     between the Cache and the DNS agent.  Caching the contents	of the file
     has an advantage when a query is made for an entry	that can be found in
     the file, but it also has a very important	advantage when searching for
     an	entry that is not in the file.	The advantage in this case is that the
     agent can very quickly rule out queries that would	otherwise require
     reading through the whole file.

     The FFAgent supports the CacheFile	configuration option, which may	be
     used to specify which files are cached in this manner.  Computers that
     act as Web	servers, in particular,	can derive a performance advantage by
     enabling the FFAgent's cache for the /etc/services	file.

     The use of	file caches in FFAgent causes lookupd to use more memory, but
     performance is improved by	a reduction in disk access.  This may be a
     worthwhile	tradeoff for server systems.  The increase in memory required
     for a file	is slightly more than the size of the file itself, the addi-
     tional memory used	for internal data structures and indexing.

     The CacheFile configuration option	takes a	list of	values.	 The special
     values all	and none may be	used to	turn on	or off caches for all files.
     Caches for	specific files may be used by using one	of the values below.
     A value prefaced with a minus ("-") disables caching for that file.  For
     example,

	   all -protocols

     enables all caches, but then disables caching of the /etc/protocols file.

     Values for	the CacheFile key may be any of	the following:

	   all					   turns on all	file caches
	   none					   turns off all file caches
	   user	(users,	passwd,	master.passwd)	   /etc/master.passwd
	   group (groups)			   /etc/groups
	   host	(hosts)				   /etc/hosts
	   network (networks)			   /etc/networks
	   service (services)			   /etc/services
	   protocol (protocols)			   /etc/protocols
	   rpc (rpcs)				   /etc/rpc
	   mount (mounts, fstab)		   /etc/fstab
	   printer (printers, printcap)		   /etc/printcap
	   bootparam (bootparams)		   /etc/bootparams
	   bootp (bootptab)			   /etc/bootptab
	   alias (aliases)			   /etc/aliases
	   ether (ethers)			   /etc/ethers
	   netgroup (netgroups)			   /etc/netgroup

   DSAgent
     The DSAgent re-directs queries to Mac OS X's Directory Services system.
     See the on-line Help for the Directory Access application for more	infor-
     mation on managing	Directory Services.

     DSAgent uses a 300	second timer for validating cached entries.  Records
     fetched using DSAgent are considered valid	in for this period of time.

   NILAgent
     The NILAgent always returns a result for a	query, so it stops any search.
     However, it returns a negative record, which carries the meaning that the
     item requested does not exist.  The use of	negative entries in a cache is
     controversial, so lookupd does not	include	the NILAgent in	its default
     lookup order.  However, adding NILAgent at	the end	of the LookupOrder can
     result in significant performance improvements in some cases.  If there
     are many network information sources being	searched it can	take a long
     time for lookupd to check them all	when you ask for something that
     doesn't exist.  By	including NILAgent at the end of the lookup order,
     lookup will cache a negative record.  The next time lookupd gets a	re-
     quest for the same	item, it will find the negative	record in the cache,
     and avoid a long and useless search.

     It	is always possible that	lookupd	may fail to find an item (and cache a
     negative record created by	NILAgent) just before someone adds that	item
     to	one of your information	systems.  In that case the negative record
     will be incorrect,	and should be removed from cache.  Unfortunately,
     there's no	way for	lookupd	to know	that without doing another potentially
     expensive search.	As a compromise, negative records only remain in the
     cache for a short time.  The NILAgent assigns all negative	records	a
     time-to-live value	of 60 seconds.	You may	change this by setting the
     TimeToLive	option for the NILAgent.

     NILAgent does not support a startup argument.

CONFIGURATION EXAMPLES
     Here's a sample configuration as it might appear in the output of the
     "nidump" utility program.

	   # nidump -r /locations/lookupd

	   name	= lookupd;
	   LogFile = /var/log/lookupd.log;
	   LookupOrder = (CacheAgent, NIAgent);
	   CHILDREN = ({
		   name	= users;
		   LookupOrder = (CacheAgent, NIAgent, FFAgent);
	   }, {
		   name	= hosts;
		   LookupOrder = (CacheAgent, NIAgent, DNSAgent, NILAgent);
		   ValidateCache = NO;
	   }, {
		   name	= netgroups;
		   LookupOrder = (CacheAgent, NIAgent, NISAgent);
	   }, {
		   name	= agents;
		   CHILDREN = ({
			   name	= NIAgent;
			   ValidationLatency = 60;
		   }, {
			   name	= NILAgent;
			   TimeToLive =	120;
		   });
	   });

PERFORMANCE TUNING AND TROUBLESHOOTING
     Simple queries can	be sent	to lookupd from	the command line using:

	   lookupd -q category [[-a key	[value ...]] ...]

     The category may be user, group, host, network, service, protocol,	rpc,
     mount, printer, bootparam,	bootp, alias, or netgroup.  The	call will
     search for	an item	of the specified category having the given value(s)
     for the specified key(s).	If no key or value options are specified, the
     call will return a	list of	all items of the specified category.
      If a key is specified with no value arguments, the call will only	return
     items that	have the specified key,	regardless of its values.

     If	statistics are enabled (see the	setting	of the StatisticsEnabled key
     in	the CONFIGURATION section above), then statistics from lookupd can be
     obtained using:

	   lookupd -statistics

     This will print version and build information, as well as a summary of
     calls and time usage.  Statistics are given for each information system,
     for each query, and for each query	within each information	system.	 For
     example:

	   Cache: 1676 1153 24285
	   Cache all group: 3 0	18
	   Cache all mount: 2 0	850
	   Cache group gid: 434	391 22
	   Cache group name: 12	10 342
	   Cache host ip_address: 5 3 0
	   Cache host name: 129	52 0

	    ...

	   netgroup name: 1 1 6867
	   network address: 4 4	3565
	   service name: 85 85 3964
	   total: 1676 1676 212371
	   user	name: 74 74 11641
	   user	number:	3 3 773
	   user	uid: 760 760 45271

     The first number printed in each line is the total	number of calls.  The
     second is the number of calls answered successfully.  The third is	the
     total time	(in milliseconds) used for that	item.  Note that the time re-
     quired for	cache validation is included in	the statistics for calls to
     the cache.

     The command:

	   lookupd -flushcache

     causes lookupd to empty the cache.

     lookupd may be run	in an interactive mode useful for testing and trou-
     bleshooting configuration problems.  Since	some directory information may
     only be available to privileged processes,	lookupd	should be run as the
     user root in interactive mode.

     When you use the interactive mode,	you start a second copy	of the lookupd
     program from a command line with a	-d option:

	   mycomputer# lookupd -d
	   lookupd version 123
	   Enter command name, "help", or "quit" to exit
	   >

     This second copy of lookupd runs independently of the system's "main"
     lookupd and does not provide information to other programs	running	on
     your system.  This	allows you to try queries and test configuration op-
     tions without disturbing normal operations.  The second copy of lookupd
     will attempt to read its configuration options from a NetInfo directory
     named /locations/lookupd_debug (NetInfo) or /etc/lookupd_debug (files).
     If	they don't exist, it will try /locations/lookupd or /etc/lookupd.

     The interactive mode command line supports	escape completion for com-
     mands, so you can type a character	or two then press the Escape key.
     lookupd will complete as much of the command as it	can (sometimes there
     are several command that start with the same characters).	To see all
     possible completions, press Control-d.  To	see all	possible commands,
     press Control-d before you	type in	any characters at all.	For on-line
     help, use the "help" command.

	   > help
	   Enter command name, "help" for general help,	or "quit" to exit help
	   help> help
	   This	is lookupd's interactive query and testing facility.
	   ...

     There are interactive commands for	all standard queries, such as user-
     WithName, hostWithInternetAddress,	and so on.  When you enter a query,
     lookupd will print	the result that	it located or "nil" if the item	was
     not found.	 lookupd also keeps track of the information source for	each
     item and a	number of other	useful pieces of information that can help you
     track internal activities.	 For example:

	   > userWithName: jru
	   Dictionary: "NIAgent: user jru"
	   _lookup_NI_checksum:	68850661
	   _lookup_NI_domain: /
	   _lookup_NI_index: 2
	   _lookup_NI_server: pacific/network
	   _lookup_info_system:	NetInfo
	   _writers_passwd: jru
	   change: 0
	   expire: 0
	   gid:	114
	   home: /Network/Servers/fiji/Users/jru
	   name: jru
	   netgroups: programmer
	   passwd: 2YEsFfX2fmC8.
	   realname: Jane Random User
	   shell: /bin/csh
	   uid:	1664
	   + Category: user
	   + Time to live: 43200
	   + Age: 0 (expires in	43200 seconds)
	   + Negative: No
	   + Cache hits: 3
	   + Retain count: 6

     When you enter a query, lookupd follows its normal	lookup order to	obtain
     an	answer.	 If you	wish to	query a	specific agent,	you can	use the	agent
     command.  This stops the normal lookup and	will direct all	further
     queries to	the agent you specify.	You can	use the	agent command again to
     switch to a different agent, or use the normalLookupOrder command to re-
     sume normal lookups.

	   > agent: NI

	   > hostWithName: fiji
	   Dictionary: "NIAgent: host fiji"
	   _lookup_NI_checksum:	68850661
	   _lookup_NI_domain: /
	   _lookup_NI_index: 1
	   _lookup_NI_server: pacific/network
	   _lookup_info_system:	NetInfo
	   bootfile: mach
	   bootparams:
	   en_address: 0:5:2:fe:ef:4b
	   ip_address: 192.42.172.168
	   name: fiji
	   netgroups: island
	   serves: fiji/local

	   > agent: DNS

	   > hostWithName: fiji
	   Dictionary: "D-0x6d470"
	   _lookup_DNS_time_to_live: 28800
	   _lookup_DNS_timestamp: 912796168
	   _lookup_domain: mydomain.com
	   _lookup_info_system:	DNS
	   ip_address: 192.42.172.168
	   name: fiji.mydomain.com fiji

	   > normalLookupOrder
	   Using normal	lookup order

     You can get timing	and usage statistics for all types of lookups using
     the statistics command.  Timing measurements can help you determine what
     might be causing slowdowns	or problems on your network.

     You can examine all items in memory using the memory and showMemoryObject
     commands.	This includes stored configuration settings, statistical
     records, and cached information.

OPEN SOURCE
     The source	code for lookupd is a available	as part	of Apple's Darwin open
     source initiative.	 lookupd is part of the	netinfo	project.  More infor-
     mation on Darwin may be found on the Web at

	   http://www.publicsource.apple.com

     The netinfo project sources include a script named	"BUILD"	that may be
     used to compile the sources.

FILES
     /var/run/lookupd.pid, /etc/lookupd

SEE ALSO
     netinfod(8), mach_init(8),	syslog(5)

Mac OS				 May 22, 2000				Mac OS

NAME | SYNOPSIS | DESCRIPTION | LOOKUP STRATEGY | CACHE | CONFIGURATION | AGENTS | CONFIGURATION EXAMPLES | PERFORMANCE TUNING AND TROUBLESHOOTING | OPEN SOURCE | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lookupd&sektion=8&manpath=Darwin+8.0.1%2fppc>

home | help