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