/share/man/man8/yp.8

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 588 lines · 588 code · 0 blank · 0 comment · 0 complexity · 1287dcb81f954645497f88882a0d9b7e MD5 · raw file

  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$
  30. .\"
  31. .Dd December 14, 2011
  32. .Dt YP 8
  33. .Os
  34. .Sh NAME
  35. .Nm yp
  36. .Nd description of the YP/NIS system
  37. .Sh SYNOPSIS
  38. .Nm
  39. .Sh DESCRIPTION
  40. The
  41. .Nm YP
  42. subsystem allows network management of passwd, group, netgroup, hosts,
  43. services, rpc, bootparams and ethers file
  44. entries through the functions
  45. .Xr getpwent 3 ,
  46. .Xr getgrent 3 ,
  47. .Xr getnetgrent 3 ,
  48. .Xr gethostent 3 ,
  49. .Xr getnetent 3 ,
  50. .Xr getrpcent 3 ,
  51. and
  52. .Xr ethers 3 .
  53. The
  54. .Xr bootparamd 8
  55. daemon makes direct
  56. .Tn NIS
  57. library calls since there are no
  58. functions in the standard C library for reading bootparams.
  59. .Tn NIS
  60. support is enabled in
  61. .Xr nsswitch.conf 5 .
  62. .Pp
  63. The
  64. .Nm YP
  65. subsystem is started automatically in
  66. .Pa /etc/rc
  67. if it has been initialized in
  68. .Pa /etc/rc.conf
  69. and if the directory
  70. .Pa /var/yp
  71. exists (which it does in the default distribution).
  72. The default
  73. .Tn NIS
  74. domain must also be set with the
  75. .Xr domainname 1
  76. command, which will happen automatically at system startup if it is
  77. specified in
  78. .Pa /etc/rc.conf .
  79. .Pp
  80. .Tn NIS
  81. is an
  82. .Tn RPC Ns -based
  83. client/server system that allows a group of
  84. machines within an
  85. .Tn NIS
  86. domain to share a common set of configuration files.
  87. This permits a system
  88. administrator to set up
  89. .Tn NIS
  90. client systems with only minimal configuration
  91. data and add, remove or modify configuration data from a single location.
  92. .Pp
  93. The canonical copies of all
  94. .Tn NIS
  95. information are stored on a single machine
  96. called the
  97. .Tn NIS
  98. .Em "master server" .
  99. The databases used to store the information are called
  100. .Tn NIS
  101. .Em maps .
  102. In
  103. .Fx ,
  104. these maps are stored in
  105. .Pa /var/yp/ Ns Aq Ar domainname
  106. where
  107. .Aq Ar domainname
  108. is the name of the
  109. .Tn NIS
  110. domain being served.
  111. A single
  112. .Tn NIS
  113. server can
  114. support several domains at once, therefore it is possible to have several
  115. such directories, one for each supported domain.
  116. Each domain will have
  117. its own independent set of maps.
  118. .Pp
  119. In
  120. .Fx ,
  121. the
  122. .Tn NIS
  123. maps are Berkeley DB hashed database files (the
  124. same format used for the
  125. .Xr passwd 5
  126. database files).
  127. Other operating systems that support
  128. .Tn NIS
  129. use old-style
  130. .Nm ndbm
  131. databases instead (largely because Sun Microsystems originally based
  132. their
  133. .Tn NIS
  134. implementation on
  135. .Nm ndbm ,
  136. and other vendors have simply licensed
  137. Sun's code rather than design their own implementation with a different
  138. database format).
  139. On these systems, the databases are generally split
  140. into
  141. .Pa .dir
  142. and
  143. .Pa .pag
  144. files which the
  145. .Nm ndbm
  146. code uses to hold separate parts of the hash
  147. database.
  148. The Berkeley DB hash method instead uses a single file for
  149. both pieces of information.
  150. This means that while you may have
  151. .Pa passwd.byname.dir
  152. and
  153. .Pa passwd.byname.pag
  154. files on other operating systems (both of which are really parts of the
  155. same map),
  156. .Fx
  157. will have only one file called
  158. .Pa passwd.byname .
  159. The difference in format is not significant: only the
  160. .Tn NIS
  161. server,
  162. .Xr ypserv 8 ,
  163. and related tools need to know the database format of the
  164. .Tn NIS
  165. maps.
  166. Client
  167. .Tn NIS
  168. systems receive all
  169. .Tn NIS
  170. data in
  171. .Tn ASCII
  172. form.
  173. .Pp
  174. There are three main types of
  175. .Tn NIS
  176. systems:
  177. .Bl -enum
  178. .It
  179. .Tn NIS
  180. clients,
  181. which query
  182. .Tn NIS
  183. servers for information.
  184. .It
  185. .Tn NIS
  186. master servers,
  187. which maintain the canonical copies of all
  188. .Tn NIS
  189. maps.
  190. .It
  191. .Tn NIS
  192. slave servers,
  193. which maintain backup copies of
  194. .Tn NIS
  195. maps that are periodically
  196. updated by the master.
  197. .El
  198. .Pp
  199. A
  200. .Tn NIS
  201. client establishes what is called a
  202. .Em binding
  203. to a particular
  204. .Tn NIS
  205. server using the
  206. .Xr ypbind 8
  207. daemon.
  208. The
  209. .Xr ypbind 8
  210. utility checks the system's default domain (as set by the
  211. .Xr domainname 1
  212. command) and begins broadcasting
  213. .Tn RPC
  214. requests on the local network.
  215. These requests specify the name of the domain for which
  216. .Xr ypbind 8
  217. is attempting to establish a binding.
  218. If a server that has been
  219. configured to serve the requested domain receives one of the broadcasts,
  220. it will respond to
  221. .Xr ypbind 8 ,
  222. which will record the server's address.
  223. If there are several servers
  224. available (a master and several slaves, for example),
  225. .Xr ypbind 8
  226. will use the address of the first one to respond.
  227. From that point
  228. on, the client system will direct all of its
  229. .Tn NIS
  230. requests to that server.
  231. The
  232. .Xr ypbind 8
  233. utility will occasionally
  234. .Dq ping
  235. the server to make sure it is still up
  236. and running.
  237. If it fails to receive a reply to one of its pings
  238. within a reasonable amount of time,
  239. .Xr ypbind 8
  240. will mark the domain as unbound and begin broadcasting again in the
  241. hopes of locating another server.
  242. .Pp
  243. .Tn NIS
  244. master and slave servers handle all
  245. .Tn NIS
  246. requests with the
  247. .Xr ypserv 8
  248. daemon.
  249. The
  250. .Xr ypserv 8
  251. utility is responsible for receiving incoming requests from
  252. .Tn NIS
  253. clients,
  254. translating the requested domain and map name to a path to the
  255. corresponding database file and transmitting data from the database
  256. back to the client.
  257. There is a specific set of requests that
  258. .Xr ypserv 8
  259. is designed to handle, most of which are implemented as functions
  260. within the standard C library:
  261. .Bl -tag -width ".Fn yp_master"
  262. .It Fn yp_order
  263. check the creation date of a particular map
  264. .It Fn yp_master
  265. obtain the name of the
  266. .Tn NIS
  267. master server for a given
  268. map/domain
  269. .It Fn yp_match
  270. lookup the data corresponding to a given in key in a particular
  271. map/domain
  272. .It Fn yp_first
  273. obtain the first key/data pair in a particular map/domain
  274. .It Fn yp_next
  275. pass
  276. .Xr ypserv 8
  277. a key in a particular map/domain and have it return the
  278. key/data pair immediately following it (the functions
  279. .Fn yp_first
  280. and
  281. .Fn yp_next
  282. can be used to do a sequential search of an
  283. .Tn NIS
  284. map)
  285. .It Fn yp_all
  286. retrieve the entire contents of a map
  287. .El
  288. .Pp
  289. There are a few other requests which
  290. .Xr ypserv 8
  291. is capable of handling (i.e., acknowledge whether or not you can handle
  292. a particular domain
  293. .Pq Dv YPPROC_DOMAIN ,
  294. or acknowledge only if you can handle the domain and be silent otherwise
  295. .Pq Dv YPPROC_DOMAIN_NONACK )
  296. but
  297. these requests are usually generated only by
  298. .Xr ypbind 8
  299. and are not meant to be used by standard utilities.
  300. .Pp
  301. On networks with a large number of hosts, it is often a good idea to
  302. use a master server and several slaves rather than just a single master
  303. server.
  304. A slave server provides the exact same information as a master
  305. server: whenever the maps on the master server are updated, the new
  306. data should be propagated to the slave systems using the
  307. .Xr yppush 8
  308. command.
  309. The
  310. .Tn NIS
  311. .Pa Makefile
  312. .Pq Pa /var/yp/Makefile
  313. will do this automatically if the administrator creates
  314. .Pa /var/yp/Makefile.local
  315. and empties the
  316. .Va NOPUSH
  317. variable:
  318. .Bd -literal -offset four
  319. .Li NOPUSH=
  320. .Ed
  321. .Pp
  322. .Va ( NOPUSH
  323. is set to true by default because the default configuration is
  324. for a small network with only one
  325. .Tn NIS
  326. server).
  327. The
  328. .Xr yppush 8
  329. command will initiate a transaction between the master and slave
  330. during which the slave will transfer the specified maps from the
  331. master server using
  332. .Xr ypxfr 8 .
  333. (The slave server calls
  334. .Xr ypxfr 8
  335. automatically from within
  336. .Xr ypserv 8 ;
  337. therefore it is not usually necessary for the administrator
  338. to use it directly.
  339. It can be run manually if
  340. desired, however.)
  341. Maintaining
  342. slave servers helps improve
  343. .Tn NIS
  344. performance on large
  345. networks by:
  346. .Bl -bullet
  347. .It
  348. Providing backup services in the event that the
  349. .Tn NIS
  350. master crashes
  351. or becomes unreachable
  352. .It
  353. Spreading the client load out over several machines instead of
  354. causing the master to become overloaded
  355. .It
  356. Allowing a single
  357. .Tn NIS
  358. domain to extend beyond
  359. a local network (the
  360. .Xr ypbind 8
  361. daemon might not be able to locate a server automatically if it resides on
  362. a network outside the reach of its broadcasts.
  363. It is possible to force
  364. .Xr ypbind 8
  365. to bind to a particular server with
  366. .Xr ypset 8
  367. but this is sometimes inconvenient.
  368. This problem can be avoided simply by
  369. placing a slave server on the local network.)
  370. .El
  371. .Pp
  372. The
  373. .Fx
  374. .Xr ypserv 8
  375. is specially designed to provide enhanced security (compared to
  376. other
  377. .Tn NIS
  378. implementations) when used exclusively with
  379. .Fx
  380. client
  381. systems.
  382. The
  383. .Fx
  384. password database system (which is derived directly
  385. from
  386. .Bx 4.4 )
  387. includes support for
  388. .Em "shadow passwords" .
  389. The standard password database does not contain users' encrypted
  390. passwords: these are instead stored (along with other information)
  391. in a separate database which is accessible only by the super-user.
  392. If the encrypted password database were made available as an
  393. .Tn NIS
  394. map, this security feature would be totally disabled, since any user
  395. is allowed to retrieve
  396. .Tn NIS
  397. data.
  398. .Pp
  399. To help prevent this,
  400. .Fx Ns 's
  401. .Tn NIS
  402. server handles the shadow password maps
  403. .Pa ( master.passwd.byname ,
  404. .Pa master.passwd.byuid ,
  405. .Pa shadow.byname
  406. and
  407. .Pa shadow.byuid )
  408. in a special way: the server will only provide access to these
  409. maps in response to requests that originate on privileged ports.
  410. Since only the super-user is allowed to bind to a privileged port,
  411. the server assumes that all such requests come from privileged
  412. users.
  413. All other requests are denied: requests from non-privileged
  414. ports will receive only an error code from the server.
  415. Additionally,
  416. .Fx Ns 's
  417. .Xr ypserv 8
  418. includes support for
  419. .An Wietse Venema Ns 's
  420. tcp wrapper package; with tcp
  421. wrapper support enabled, the administrator can configure
  422. .Xr ypserv 8
  423. to respond only to selected client machines.
  424. .Pp
  425. While these enhancements provide better security than stock
  426. .Tn NIS ,
  427. they are by no means 100% effective.
  428. It is still possible for
  429. someone with access to your network to spoof the server into disclosing
  430. the shadow password maps.
  431. .Pp
  432. On the client side,
  433. .Fx Ns 's
  434. .Xr getpwent 3
  435. functions will automatically search for the
  436. .Pa master.passwd
  437. maps and use them if they exist.
  438. If they do, they will be used, and
  439. all fields in these special maps (class, password age and account
  440. expiration) will be decoded.
  441. If they are not found, the standard
  442. .Pa passwd
  443. maps will be used instead.
  444. .Sh COMPATIBILITY
  445. When using a
  446. .No non- Ns Fx
  447. .Tn NIS
  448. server for
  449. .Xr passwd 5
  450. files, it is unlikely that the default MD5-based format that
  451. .Fx
  452. uses for passwords will be accepted by it.
  453. If this is the case, the value of the
  454. .Va passwd_format
  455. setting in
  456. .Xr login.conf 5
  457. should be changed to
  458. .Qq Li des
  459. for compatibility.
  460. .Pp
  461. Some systems, such as
  462. .Tn SunOS
  463. 4.x, need
  464. .Tn NIS
  465. to be running in order
  466. for their hostname resolution functions
  467. .Fn ( gethostbyname ,
  468. .Fn gethostbyaddr ,
  469. etc.) to work properly.
  470. On these systems,
  471. .Xr ypserv 8
  472. performs
  473. .Tn DNS
  474. lookups when asked to return information about
  475. a host that does not exist in its
  476. .Pa hosts.byname
  477. or
  478. .Pa hosts.byaddr
  479. maps.
  480. .Fx Ns 's
  481. resolver uses
  482. .Tn DNS
  483. by default (it can be made to use
  484. .Tn NIS ,
  485. if desired), therefore its
  486. .Tn NIS
  487. server does not do
  488. .Tn DNS
  489. lookups
  490. by default.
  491. However,
  492. .Xr ypserv 8
  493. can be made to perform
  494. .Tn DNS
  495. lookups if it is started with a special
  496. flag.
  497. It can also be made to register itself as an
  498. .Tn NIS
  499. v1 server
  500. in order to placate certain systems that insist on the presence of
  501. a v1 server
  502. .No ( Fx
  503. uses only
  504. .Tn NIS
  505. v2, but many other systems,
  506. including
  507. .Tn SunOS
  508. 4.x, search for both a v1 and v2 server when binding).
  509. .Fx Ns 's
  510. .Xr ypserv 8
  511. does not actually handle
  512. .Tn NIS
  513. v1 requests, but this
  514. .Dq "kludge mode"
  515. is useful for silencing stubborn systems that search for both
  516. a v1 and v2 server.
  517. .Pp
  518. (Please see the
  519. .Xr ypserv 8
  520. manual page for a detailed description of these special features
  521. and flags.)
  522. .Sh SEE ALSO
  523. .Xr domainname 1 ,
  524. .Xr ypcat 1 ,
  525. .Xr ypmatch 1 ,
  526. .Xr ypwhich 1 ,
  527. .Xr nsswitch.conf 5 ,
  528. .Xr yp_mkdb 8 ,
  529. .Xr ypbind 8 ,
  530. .Xr ypinit 8 ,
  531. .Xr yppoll 8 ,
  532. .Xr yppush 8 ,
  533. .Xr ypserv 8 ,
  534. .Xr ypset 8 ,
  535. .Xr ypxfr 8
  536. .Sh HISTORY
  537. The
  538. .Nm YP
  539. subsystem was written from the ground up by
  540. .An Theo de Raadt
  541. to be compatible to Sun's implementation.
  542. Bug fixes, improvements
  543. and
  544. .Tn NIS
  545. server support were later added by
  546. .An Bill Paul .
  547. The server-side code was originally written by
  548. .An Peter Eriksson
  549. and
  550. .An Tobias Reber
  551. and is subject to the GNU Public License.
  552. No Sun code was
  553. referenced.
  554. .Sh BUGS
  555. While
  556. .Fx
  557. now has both
  558. .Tn NIS
  559. client and server capabilities, it does not yet have support for
  560. .Xr ypupdated 8
  561. or the
  562. .Fn yp_update
  563. function.
  564. Both of these require secure
  565. .Tn RPC ,
  566. which
  567. .Fx
  568. does not
  569. support yet either.
  570. .Pp
  571. The
  572. .Xr getservent 3
  573. and
  574. .Xr getprotoent 3
  575. functions do not yet have
  576. .Tn NIS
  577. support.
  578. Fortunately, these files
  579. do not need to be updated that often.
  580. .Pp
  581. Many more manual pages should be written, especially
  582. .Xr ypclnt 3 .
  583. For the time being, seek out a local Sun machine and read the
  584. manuals for there.
  585. .Pp
  586. Neither Sun nor this author have found a clean way to handle
  587. the problems that occur when ypbind cannot find its server
  588. upon bootup.