1.\" Copyright (c) 1995 2.\" Bill Paul <wpaul@ctr.columbia.edu>. 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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by Bill Paul. 15.\" 4. Neither the name of the author nor the names of any co-contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd February 4, 1995 34.Dt YPSERV 8 35.Os 36.Sh NAME 37.Nm ypserv 38.Nd NIS database server 39.Sh SYNOPSIS 40.Nm 41.Op Fl n 42.Op Fl d 43.Op Fl p Ar path 44.Sh DESCRIPTION 45.Tn NIS 46is an RPC-based service designed to allow a number of UNIX-based 47machines to share a common set of configuration files. 48Rather than 49requiring a system administrator to update several copies of files 50such as 51.Pa /etc/hosts , 52.Pa /etc/passwd 53and 54.Pa /etc/group , 55which tend to require frequent changes in most environments, 56.Tn NIS 57allows groups of computers to share one set of data which can be 58updated from a single location. 59.Pp 60The 61.Nm 62utility is the server that distributes 63.Tn NIS 64databases to client systems within an 65.Tn NIS 66.Em domain . 67Each client in an 68.Tn NIS 69domain must have its domainname set to 70one of the domains served by 71.Nm 72using the 73.Xr domainname 1 74command. 75The clients must also run 76.Xr ypbind 8 77in order to attach to a particular server, since it is possible to 78have several servers within a single 79.Tn NIS 80domain. 81.Pp 82The databases distributed by 83.Nm 84are stored in 85.Pa /var/yp/[domainname] 86where 87.Pa domainname 88is the name of the domain being served. 89There can be several 90such directories with different domainnames, and you need only one 91.Nm 92daemon to handle them all. 93.Pp 94The databases, or 95.Pa maps 96as they are often called, 97are created by 98.Pa /var/yp/Makefile 99using several system files as source. 100The database files are in 101.Xr db 3 102format to help speed retrieval when there are many records involved. 103In 104.Fx , 105the maps are always readable and writable only by root for security 106reasons. 107Technically this is only necessary for the password 108maps, but since the data in the other maps can be found in 109other world-readable files anyway, it does not hurt and it is considered 110good general practice. 111.Pp 112The 113.Nm 114utility is started by 115.Pa /etc/rc.d/ypserv 116if it has been enabled in 117.Pa /etc/rc.conf . 118.Sh SPECIAL FEATURES 119There are some problems associated with distributing a 120.Fx 121password 122database via 123.Tn NIS : 124.Fx 125normally only stores encrypted passwords 126in 127.Pa /etc/master.passwd , 128which is readable and writable only by root. 129By turning this file 130into an 131.Tn NIS 132map, this security feature would be completely defeated. 133.Pp 134To make up for this, the 135.Fx 136version of 137.Nm 138handles the 139.Pa master.passwd.byname 140and 141.Pa master.passwd.byuid 142maps in a special way. 143When the server receives a request to access 144either of these two maps, it will check the TCP port from which the 145request originated and return an error if the port number is greater 146than 1023. 147Since only the superuser is allowed to bind to TCP ports 148with values less than 1024, the server can use this test to determine 149whether or not the access request came from a privileged user. 150Any requests made by non-privileged users are therefore rejected. 151.Pp 152Furthermore, the 153.Xr getpwent 3 154routines in the 155.Fx 156standard C library will only attempt to retrieve 157data from the 158.Pa master.passwd.byname 159and 160.Pa master.passwd.byuid 161maps for the superuser: if a normal user calls any of these functions, 162the standard 163.Pa passwd.byname 164and 165.Pa passwd.byuid 166maps will be accessed instead. 167The latter two maps are constructed by 168.Pa /var/yp/Makefile 169by parsing the 170.Pa master.passwd 171file and stripping out the password fields, and are therefore 172safe to pass on to unprivileged users. 173In this way, the shadow password 174aspect of the protected 175.Pa master.passwd 176database is maintained through 177.Tn NIS . 178.Sh NOTES 179.Ss Setting Up Master and Slave Servers 180.Xr ypinit 8 181is a convenient script that will help setup master and slave 182.Tn NIS 183servers. 184.Ss Limitations 185There are two problems inherent with password shadowing in 186.Tn NIS 187that users should 188be aware of: 189.Bl -enum -offset indent 190.It 191The 192.Sq TCP port less than 1024 193test is trivial to defeat for users with 194unrestricted access to machines on your network (even those machines 195which do not run UNIX-based operating systems). 196.It 197If you plan to use a 198.Fx 199system to serve 200.No non- Ns Fx 201clients that 202have no support for password shadowing (which is most of them), you 203will have to disable the password shadowing entirely by uncommenting the 204.Em UNSECURE=True 205entry in 206.Pa /var/yp/Makefile . 207This will cause the standard 208.Pa passwd.byname 209and 210.Pa passwd.byuid 211maps to be generated with valid encrypted password fields, which is 212necessary in order for 213.No non- Ns Fx 214clients to perform user 215authentication through 216.Tn NIS . 217.El 218.Pp 219.Ss Security 220In general, any remote user can issue an RPC to 221.Nm 222and retrieve the contents of your 223.Tn NIS 224maps, provided the remote user 225knows your domain name. 226To prevent such unauthorized transactions, 227.Nm 228supports a feature called 229.Pa securenets 230which can be used to restrict access to a given set of hosts. 231At startup, 232.Nm 233will attempt to load the securenets information from a file 234called 235.Pa /var/yp/securenets . 236(Note that this path varies depending on the path specified with 237the 238.Fl p 239option, which is explained below.) 240This file contains entries 241that consist of a network specification and a network mask separated 242by white space. 243Lines starting with 244.Dq \&# 245are considered to be comments. 246A 247sample securenets file might look like this: 248.Bd -unfilled -offset indent 249# allow connections from local host -- mandatory 250127.0.0.1 255.255.255.255 251# allow connections from any host 252# on the 192.168.128.0 network 253192.168.128.0 255.255.255.0 254# allow connections from any host 255# between 10.0.0.0 to 10.0.15.255 25610.0.0.0 255.255.240.0 257.Ed 258.Pp 259If 260.Nm 261receives a request from an address that matches one of these rules, 262it will process the request normally. 263If the address fails to match 264a rule, the request will be ignored and a warning message will be 265logged. 266If the 267.Pa /var/yp/securenets 268file does not exist, 269.Nm 270will allow connections from any host. 271.Pp 272The 273.Nm 274utility also has support for Wietse Venema's 275.Em tcpwrapper 276package. 277This allows the administrator to use the tcpwrapper 278configuration files 279.Pa ( /etc/hosts.allow 280and 281.Pa /etc/hosts.deny ) 282for access control instead of 283.Pa /var/yp/securenets . 284.Pp 285Note: while both of these access control mechanisms provide some 286security, they, like the privileged port test, are both vulnerable 287to 288.Dq IP spoofing 289attacks. 290.Pp 291.Ss NIS v1 compatibility 292This version of 293.Nm 294has some support for serving 295.Tn NIS 296v1 clients. 297The 298.Fx 299.Tn NIS 300implementation only uses the 301.Tn NIS 302v2 protocol, however other implementations 303include support for the v1 protocol for backwards compatibility 304with older systems. 305The 306.Xr ypbind 8 307daemons supplied with these systems will try to establish a binding 308to an 309.Tn NIS 310v1 server even though they may never actually need it (and they may 311persist in broadcasting in search of one even after they receive a 312response from a v2 server). 313Note that while 314support for normal client calls is provided, this version of 315.Nm 316does not handle v1 map transfer requests; consequently, it cannot 317be used as a master or slave in conjunction with older 318.Tn NIS 319servers that 320only support the v1 protocol. 321Fortunately, there probably are not any 322such servers still in use today. 323.Ss NIS servers that are also NIS clients 324Care must be taken when running 325.Nm 326in a multi-server domain where the server machines are also 327.Tn NIS 328clients. 329It is generally a good idea to force the servers to 330bind to themselves rather than allowing them to broadcast bind 331requests and possibly become bound to each other: strange failure 332modes can result if one server goes down and 333others are dependent upon on it. 334(Eventually all the clients will 335time out and attempt to bind to other servers, but the delay 336involved can be considerable and the failure mode is still present 337since the servers might bind to each other all over again). 338.Pp 339Refer to the 340.Xr ypbind 8 341man page for details on how to force it to bind to a particular 342server. 343.Sh OPTIONS 344The following options are supported by 345.Nm : 346.Bl -tag -width flag 347.It Fl n 348This option affects the way 349.Nm 350handles yp_match requests for the 351.Pa hosts.byname 352and 353.Pa hosts.byaddress 354maps. 355By default, if 356.Nm 357cannot find an entry for a given host in its hosts maps, it will 358return an error and perform no further processing. 359With the 360.Fl n 361flag, 362.Nm 363will go one step further: rather than giving up immediately, it 364will try to resolve the hostname or address using a DNS nameserver 365query. 366If the query is successful, 367.Nm 368will construct a fake database record and return it to the client, 369thereby making it seem as though the client's yp_match request 370succeeded. 371.Pp 372This feature is provided for compatibility with SunOS 4.1.x, 373which has brain-damaged resolver functions in its standard C 374library that depend on 375.Tn NIS 376for hostname and address resolution. 377The 378.Fx 379resolver can be configured to do DNS 380queries directly, therefore it is not necessary to enable this 381option when serving only 382.Fx 383.Tn NIS 384clients. 385.It Fl d 386Cause the server to run in debugging mode. 387Normally, 388.Nm 389reports only unusual errors (access violations, file access failures) 390using the 391.Xr syslog 3 392facility. 393In debug mode, the server does not background 394itself and prints extra status messages to stderr for each 395request that it receives. 396Also, while running in debug mode, 397.Nm 398will not spawn any additional subprocesses as it normally does 399when handling yp_all requests or doing DNS lookups. 400(These actions 401often take a fair amount of time to complete and are therefore handled 402in subprocesses, allowing the parent server process to go on handling 403other requests.) 404This makes it easier to trace the server with 405a debugging tool. 406.It Fl p Ar path 407Normally, 408.Nm 409assumes that all 410.Tn NIS 411maps are stored under 412.Pa /var/yp . 413The 414.Fl p 415flag may be used to specify an alternate 416.Tn NIS 417root path, allowing 418the system administrator to move the map files to a different place 419within the file system. 420.El 421.Sh FILES 422.Bl -tag -width Pa -compact 423.It Pa /var/yp/[domainname]/[maps] 424the 425.Tn NIS 426maps 427.It Pa /etc/nsswitch.conf 428name switch configuration file 429.It Pa /var/yp/securenets 430host access control file 431.El 432.Sh SEE ALSO 433.Xr ypcat 1 , 434.Xr db 3 , 435.Xr hosts_access 5 , 436.Xr rpc.yppasswdd 8 , 437.Xr yp 8 , 438.Xr ypbind 8 , 439.Xr ypinit 8 , 440.Xr yppush 8 , 441.Xr ypxfr 8 442.Sh HISTORY 443This version of 444.Nm 445first appeared in 446.Fx 2.2 . 447.Sh AUTHORS 448.An Bill Paul Aq wpaul@ctr.columbia.edu 449