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