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