]> git.saurik.com Git - apple/libinfo.git/blob - nis.subproj/yp.8
Libinfo-542.40.3.tar.gz
[apple/libinfo.git] / 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.