manpagez: man pages & more
man lookupd(8)
Home | html | info | man
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
     returns 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
     retrieved 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
     options) for all categories, and override them for individual categories.
     Details on configuring lookupd are found in the CONFIGURATION section
     below.

     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
     default lookup order starts with the cache agent for each lookup cate-
     gory.  Caching may be disabled for all categories or for specific cate-
     gories 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
     enabled and adjusting the ValidationLatency.  If an agent has just
     fetched a database version number or read a time stamp in order to vali-
     date one item in the cache, then it can use that value for a few seconds
     to validate 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 number means that lookupd will avoid re-checking time stamps,
     sequence numbers, 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
     addresses very rarely change, you might want to turn off cache validation
     for the host cache to save time and reduce network traffic.  This is
     especially 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
     default values of configuration parameters.  The files that may be cre-
     ated 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
         default 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
         applies 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
     detail 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
     information services.

     CacheAgent does not support a startup argument (as described at the
     beginning 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
     option 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
     address.

     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
     domain 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
     NetInfo 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
                                  address, 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
     options.  NISAgent validates entries by checking the map order numbers.

     Note that lookupd has separate agents for the Flat Files (see FFAgent
     below) 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
     extensions 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
     request 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
     required 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
     options 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
     resume 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

Mac OS X 10.4 - Generated Fri Apr 29 08:12:17 CDT 2005
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.