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