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