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