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