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