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

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