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