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