nis.subproj/yp.8

   1 .\" Copyright (c) 1992/3 Theo de Raadt <deraadt@fsa.ca>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The name of the author may not be used to endorse or promote
  13 .\"    products derived from this software without specific prior written
  14 .\"    permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
  17 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  20 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     from: @(#)yp.8  1.0 (deraadt) 4/26/93
  29 .\" $FreeBSD: src/share/man/man8/yp.8,v 1.36 2005/01/21 08:36:40 ru Exp $
  30 .\"
  31 .\" @APPLE_LICENSE_HEADER_START@
  32 .\"
  33 .\" Portions Copyright (c) 2003-2013 Apple Inc.  All Rights Reserved.
  34 .\"
  35 .\" This file contains Original Code and/or Modifications of Original Code
  36 .\" as defined in and that are subject to the Apple Public Source License
  37 .\" Version 2.0 (the 'License'). You may not use this file except in
  38 .\" compliance with the License. Please obtain a copy of the License at
  39 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  40 .\" file.
  41 .\"
  42 .\" The Original Code and all software distributed under the License are
  43 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  44 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  45 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  46 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  47 .\" Please see the License for the specific language governing rights and
  48 .\" limitations under the License.
  49 .\"
  50 .\" @APPLE_LICENSE_HEADER_END@
  51 .\"
  52 .Dd April 5, 1993
  53 .Dt YP 8
  54 .Os
  55 .Sh NAME
  56 .Nm yp
  57 .Nd description of the YP/NIS system
  58 .Sh SYNOPSIS
  59 .Nm
  60 .Sh DESCRIPTION
  61 The
  62 .Nm YP
  63 subsystem allows network access to directory information hosted by
  64 .Tn NIS
  65 servers.
  66 OS X support is provided through the functions
  67 .Xr getpwent 3 ,
  68 .Xr getgrent 3 ,
  69 .Xr getfsent 3 ,
  70 .Xr getnetgrent 3 ,
  71 .Xr gethostent 3 ,
  72 .Xr getnetent 3 ,
  73 .Xr getrpcent 3 ,
  74 .Xr getprotoent 3 ,
  75 .Xr getservent 3 ,
  76 .Xr ethers 3
  77 and other related functions.
  78 Queries to
  79 .Tn NIS
  80 servers are sent by the
  81 .Nm opendirectoryd
  82 daemon.
  83 The configuration of
  84 .Tn NIS
  85 clients is further described in the
  86 .Xr opendirectoryd 8
  87 manual page.
  88 .Pp
  89 The
  90 .Nm YP
  91 subsystem is started automatically by
  92 .Xr launchd 8
  93 if an
  94 .Tn NIS
  95 domain is specified in the
  96 .Pa /etc/defaultdomain
  97 configuration file,
  98 and if the directory
  99 .Pa /var/yp
 100 exists (which it does in the default distribution).
 101 .Pp
 102 .Tn NIS
 103 is an
 104 .Tn RPC Ns -based
 105 client/server system that allows a group of
 106 machines within an
 107 .Tn NIS
 108 domain to share a common set of configuration files.
 109 This permits a system
 110 administrator to set up
 111 .Tn NIS
 112 client systems with only minimal configuration
 113 data and add, remove or modify configuration data from a single location.
 114 .Pp
 115 The canonical copies of all
 116 .Tn NIS
 117 information are stored on a single machine
 118 called the
 119 .Tn NIS
 120 .Em "master server" .
 121 The databases used to store the information are called
 122 .Tn NIS
 123 .Em maps .
 124 A single
 125 .Tn NIS
 126 server can
 127 support several domains at once, therefore it is possible to have several
 128 such directories, one for each supported domain.
 129 Each domain will have
 130 its own independent set of maps.
 131 .Pp
 132 Client
 133 .Tn NIS
 134 systems receive all
 135 .Tn NIS
 136 data in
 137 .Tn ASCII
 138 form.
 139 .Pp
 140 There are three main types of
 141 .Tn NIS
 142 systems:
 143 .Bl -enum
 144 .It
 145 .Tn NIS
 146 clients,
 147 which query
 148 .Tn NIS
 149 servers for information.
 150 .It
 151 .Tn NIS
 152 master servers,
 153 which maintain the canonical copies of all
 154 .Tn NIS
 155 maps.
 156 .It
 157 .Tn NIS
 158 slave servers,
 159 which maintain backup copies of
 160 .Tn NIS
 161 maps that are periodically
 162 updated by the master.
 163 .El
 164 .Pp
 165 OS X systems may be configured as
 166 .Tn NIS
 167 clients, but not as master or slave servers.
 168 .Pp
 169 A
 170 .Tn NIS
 171 client establishes what is called a
 172 .Em binding
 173 to a particular
 174 .Tn NIS
 175 server using the
 176 .Xr ypbind 8
 177 daemon.
 178 The
 179 .Xr ypbind 8
 180 utility checks the system's default domain (as set by the
 181 .Xr domainname 1
 182 command) and begins broadcasting
 183 .Tn RPC
 184 requests on the local network.
 185 These requests specify the name of the domain for which
 186 .Xr ypbind 8
 187 is attempting to establish a binding.
 188 If a server that has been
 189 configured to serve the requested domain receives one of the broadcasts,
 190 it will respond to
 191 .Xr ypbind 8 ,
 192 which will record the server's address.
 193 If there are several servers
 194 available (a master and several slaves, for example),
 195 .Xr ypbind 8
 196 will use the address of the first one to respond.
 197 From that point
 198 on, the client system will direct all of its
 199 .Tn NIS
 200 requests to that server.
 201 The
 202 .Xr ypbind 8
 203 utility will occasionally
 204 .Dq ping
 205 the server to make sure it is still up
 206 and running.
 207 If it fails to receive a reply to one of its pings
 208 within a reasonable amount of time,
 209 .Xr ypbind 8
 210 will mark the domain as unbound and begin broadcasting again in the
 211 hopes of locating another server.
 212 .Pp
 213 .Tn NIS
 214 master and slave servers handle all
 215 .Tn NIS
 216 requests with the
 217 .Xr ypserv 8
 218 daemon.
 219 The
 220 .Xr ypserv 8
 221 utility is responsible for receiving incoming requests from
 222 .Tn NIS
 223 clients,
 224 translating the requested domain and map name to a path to the
 225 corresponding database file and transmitting data from the database
 226 back to the client.
 227 There is a specific set of requests that
 228 .Xr ypserv 8
 229 is designed to handle, most of which are implemented as functions
 230 within the standard system libraries:
 231 .Bl -tag -width ".Fn yp_master"
 232 .It Fn yp_order
 233 check the creation date of a particular map
 234 .It Fn yp_master
 235 obtain the name of the
 236 .Tn NIS
 237 master server for a given
 238 map/domain
 239 .It Fn yp_match
 240 lookup the data corresponding to a given in key in a particular
 241 map/domain
 242 .It Fn yp_first
 243 obtain the first key/data pair in a particular map/domain
 244 .It Fn yp_next
 245 pass
 246 .Xr ypserv 8
 247 a key in a particular map/domain and have it return the
 248 key/data pair immediately following it (the functions
 249 .Fn yp_first
 250 and
 251 .Fn yp_next
 252 can be used to do a sequential search of an
 253 .Tn NIS
 254 map)
 255 .It Fn yp_all
 256 retrieve the entire contents of a map
 257 .El
 258 .Pp
 259 There are a few other requests which
 260 .Xr ypserv 8
 261 is capable of handling (i.e., acknowledge whether or not you can handle
 262 a particular domain
 263 .Pq Dv YPPROC_DOMAIN ,
 264 or acknowledge only if you can handle the domain and be silent otherwise
 265 .Pq Dv YPPROC_DOMAIN_NONACK )
 266 but
 267 these requests are usually generated only by
 268 .Xr ypbind 8
 269 and are not meant to be used by standard utilities.
 270 .Sh HISTORY
 271 The
 272 .Nm YP
 273 subsystem was written from the ground up by
 274 .An Theo de Raadt
 275 to be compatible to Sun's implementation.
 276 Bug fixes, improvements
 277 and
 278 .Tn NIS
 279 server support were later added by
 280 .An Bill Paul .
 281 The server-side code was originally written by
 282 .An Peter Eriksson
 283 and
 284 .An Tobias Reber
 285 and is subject to the GNU Public License.
 286 No Sun code was
 287 referenced.
 288 .Pp
 289 OS X
 290 .Tn NIS
 291 client software is derived from FreeBSD.