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.Fn gethostbyname , 438.Fn gethostbyaddr , 439etc) to work properly. 440On these systems, 441.Xr ypserv 8 442performs 443.Tn DNS 444lookups when asked to return information about 445a host that doesn't exist in its 446.Pa hosts.byname 447or 448.Pa hosts.byaddr 449maps. 450.Fx Ns 's 451resolver uses 452.Tn DNS 453by default (it can be made to use 454.Tn NIS Ns , 455if desired), therefore its 456.Tn NIS 457server doesn't do 458.Tn DNS 459lookups 460by default. 461However, 462.Xr ypserv 8 463can be made to perform 464.Tn DNS 465lookups if it is started with a special 466flag. 467It can also be made to register itself as an 468.Tn NIS 469v1 server 470in order to placate certain systems that insist on the presence of 471a v1 server 472.No ( Fx 473uses only 474.Tn NIS 475v2, but many other systems, 476including 477.Tn SunOS 4784.x, search for both a v1 and v2 server when binding). 479.Fx Ns 's 480.Xr ypserv 8 481does not actually handle 482.Tn NIS 483v1 requests, but this ``kludge mode'' 484is useful for silencing stubborn systems that search for both 485a v1 and v2 server. 486.Pp 487(Please see the 488.Xr ypserv 8 489manual page for a detailed description of these special features 490and flags.) 491.Sh BUGS 492While 493.Fx 494now has both 495.Tn NIS 496client and server capabilities, it does not yet have support for 497.Xr ypupdated 8 498or the 499.Fn yp_update 500function. 501Both of these require secure 502.Tn RPC Ns , 503which 504.Fx 505doesn't 506support yet either. 507.Pp 508The 509.Xr getservent 3 510and 511.Xr getprotoent 3 512functions do not yet have 513.Tn NIS 514support. 515Fortunately, these files 516don't need to be updated that often. 517.Pp 518Many more manual pages should be written, especially 519.Xr ypclnt 3 . 520For the time being, seek out a local Sun machine and read the 521manuals for there. 522.Pp 523Neither Sun nor this author have found a clean way to handle 524the problems that occur when ypbind cannot find its server 525upon bootup. 526.Sh HISTORY 527The 528.Nm YP 529subsystem was written from the ground up by 530.An Theo de Raadt 531to be compatible to Sun's implementation. 532Bug fixes, improvements 533and 534.Tn NIS 535server support were later added by 536.An Bill Paul Ns . 537The server-side code was originally written by 538.An Peter Eriksson 539and 540.An Tobias Reber 541and is subject to the GNU Public License. 542No Sun code was 543referenced. 544