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