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