external/bsd/libbind/dist/doc/irs.conf.5

   1 .\"     $NetBSD$
   2 .\"
   3 .\" Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
   4 .\"
   5 .\" Permission to use, copy, modify, and/or distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15 .\" PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" Id: irs.conf.5,v 1.3 2009/01/22 23:49:23 tbox Exp
  18 .\"
  19 .Dd November 16, 1997
  20 .Dt IRS.CONF 5
  21 .Os BIND 8.1
  22 .Sh NAME
  23 .Nm irs.conf
  24 .Nd Information Retrieval System configuration file
  25 .Sh SYNOPSIS
  26 .Nm irs.conf
  27 .Sh DESCRIPTION
  28 The
  29 .Xr irs 3
  30 functions are a set of routines in the C library which provide access to
  31 various system maps.
  32 The maps that irs currently controls are the following: passwd, group,
  33 services, protocols, hosts, networks and netgroup.
  34 When a program first calls a function that accesses one of these maps,
  35 the irs configuration file is read,
  36 and the source of each map is determined for the life of the process.
  37 .Pp
  38 If this file does not exist,
  39 the irs routines default to using local sources for all information,
  40 with the exception of the host and networks maps,
  41 which use the Domain Name System (DNS).
  42 .Pp
  43 Each record in the file consists of one line.
  44 A record consists of a map-name, an access-method and possibly a (comma
  45 delimited) set of options,
  46 separated by tabs or spaces.
  47 Blank lines, and text between a # and a newline are ignored.
  48 .Pp
  49 Available maps:
  50 .Bd -literal -offset indent
  51 Map name        Information in map
  52 =========       ==================================
  53 passwd          User authentication information
  54 group           User group membership information
  55 services        Network services directory
  56 protocols       Network protocols directory
  57 hosts           Network hosts directory
  58 networks        Network "network names" directory
  59 netgroup        Network "host groups" directory
  60 .Ed
  61 .Pp
  62 Available access methods:
  63 .Bd -literal -offset indent
  64 Access method   Description
  65 =============   =================================================
  66 local           Use a local file, usually in /etc
  67 dns             Use the domain name service (includes hesiod)
  68 nis             Use the Sun-compatible Network Information Service
  69 irp             Use the IRP daemon on the localhost.
  70 .Ed
  71 .Pp
  72 Available options:
  73 .Bd -literal -offset indent
  74 Option          Description
  75 ========        ================================================
  76 continue        don't stop searching if you can't find something
  77 merge           don't stop searching if you CAN find something
  78 .Ed
  79 .Pp
  80 The continue option creates
  81 .Dq "union namespaces"
  82 whereby subsequent access methods of the same map type can be tried
  83 if a name cannot be found using earlier access methods.
  84 This can be quite confusing in the case of host names,
  85 since the name to address and address to name mappings can be visibly
  86 asymmetric even though the data used by any given access method is
  87 entirely consistent.  This behavior is, therefore, not the default.
  88 .Pp
  89 The merge option only affects lookups in the groups map.
  90 If set, subsequent access methods will be tried in order to cause
  91 local users to appear in NIS (or other remote) groups in addition
  92 to the local groups.
  93 .Sh EXAMPLE
  94 .Bd -literal -offset indent
  95 # Get password entries from local file, or failing that, NIS
  96 passwd          local   continue
  97 passwd          nis
  98
  99 # Build group membership from both local file, and NIS.
 100 group           local   continue,merge
 101 group           nis
 102
 103 # Services comes from just the local file.
 104 services        local
 105
 106 protocols       local
 107
 108 # Hosts comes first from DNS, failing that, the local file
 109 hosts           dns     continue
 110 hosts           local
 111
 112 # Networks comes first from the local file, and failing
 113 # that the, irp daemon
 114 networks        local   continue
 115 networks        irp
 116
 117 netgroup        local
 118 .Ed
 119 .Sh NOTES
 120 If a local user needs to be in the local host's
 121 .Dq wheel
 122 group but not in every host's
 123 .Dq wheel
 124 group, put them in the local host's
 125 .Pa /etc/group
 126 .Dq wheel
 127 entry and set up the
 128 .Dq groups
 129 portion of your
 130 .Pa /etc/irs.conf
 131 file as:
 132 .Bd -literal -offset indent
 133 group   local   continue,merge
 134 group   nis
 135 .Ed
 136 .Pp
 137 NIS takes a long time to time out.
 138 Especially for hosts if you use the
 139 .Fl d
 140 option to your server's
 141 .Dq ypserv
 142 daemon.
 143 .Pp
 144 It is important that the
 145 .Pa irs.conf
 146 file contain an entry for each map.
 147 If a map is not mentioned in the
 148 .Pa irs.conf
 149 file, all queries to that map will fail.
 150 .Pp
 151 The classic NIS mechanism for specifying union namespaces is to add an entry
 152 to a local map file whose name is ``+''.  In IRS, this is done via ``continue''
 153 and/or ``merge'' map options.  While this results in a small incompatibility
 154 when local map files are imported from non-IRS systems to IRS systems, there
 155 are compensating advantages in security and configurability.
 156 .Sh FILES
 157 .Bl -tag -width /etc/irs.confXXXX -compact
 158 .It Pa /etc/irs.conf
 159 The file
 160 .Nm irs.conf
 161 resides in
 162 .Pa /etc .
 163 .El
 164 .Sh SEE ALSO
 165 .Xr groups 5 ,
 166 .Xr hosts 5 ,
 167 .Xr netgroup 5 ,
 168 .Xr networks 5 ,
 169 .Xr passwd 5 ,
 170 .Xr protocols 5 ,
 171 .Xr services 5