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.\" 33.Dd February 3, 2008 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 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 64utility 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 does not hurt and it is considered 112good general practice. 113.Pp 114The 115.Nm 116utility is started by 117.Pa /etc/rc.d/ypserv 118if it has been enabled 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 : 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 277utility also has support for Wietse Venema's 278.Em tcpwrapper 279package. 280This allows the administrator to use the tcpwrapper 281configuration files 282.Pa ( /etc/hosts.allow 283and 284.Pa /etc/hosts.deny ) 285for access control instead of 286.Pa /var/yp/securenets . 287.Pp 288Note: while both of these access control mechanisms provide some 289security, they, like the privileged port test, are both vulnerable 290to 291.Dq IP spoofing 292attacks. 293.Ss NIS v1 compatibility 294This version of 295.Nm 296has some support for serving 297.Tn NIS 298v1 clients. 299The 300.Dx 301.Tn NIS 302implementation only uses the 303.Tn NIS 304v2 protocol, however other implementations 305include support for the v1 protocol for backwards compatibility 306with older systems. 307The 308.Xr ypbind 8 309daemons supplied with these systems will try to establish a binding 310to an 311.Tn NIS 312v1 server even though they may never actually need it (and they may 313persist in broadcasting in search of one even after they receive a 314response from a v2 server). 315Note that while 316support for normal client calls is provided, this version of 317.Nm 318does not handle v1 map transfer requests; consequently, it cannot 319be used as a master or slave in conjunction with older 320.Tn NIS 321servers that 322only support the v1 protocol. 323Fortunately, there probably are not any 324such servers still in use today. 325.Ss NIS servers that are also NIS clients 326Care must be taken when running 327.Nm 328in a multi-server domain where the server machines are also 329.Tn NIS 330clients. 331It is generally a good idea to force the servers to 332bind to themselves rather than allowing them to broadcast bind 333requests and possibly become bound to each other: strange failure 334modes can result if one server goes down and 335others are dependent upon on it. 336(Eventually all the clients will 337time out and attempt to bind to other servers, but the delay 338involved can be considerable and the failure mode is still present 339since the servers might bind to each other all over again). 340.Pp 341Refer to the 342.Xr ypbind 8 343man page for details on how to force it to bind to a particular 344server. 345.Sh OPTIONS 346The following options are supported by 347.Nm : 348.Bl -tag -width flag 349.It Fl n 350This option affects the way 351.Nm 352handles yp_match requests for the 353.Pa hosts.byname 354and 355.Pa hosts.byaddress 356maps. 357By default, if 358.Nm 359cannot find an entry for a given host in its hosts maps, it will 360return an error and perform no further processing. 361With the 362.Fl n 363flag, 364.Nm 365will go one step further: rather than giving up immediately, it 366will try to resolve the hostname or address using a DNS nameserver 367query. 368If the query is successful, 369.Nm 370will construct a fake database record and return it to the client, 371thereby making it seem as though the client's yp_match request 372succeeded. 373.Pp 374This feature is provided for compatibility with SunOS 4.1.x, 375which has brain-damaged resolver functions in its standard C 376library that depend on 377.Tn NIS 378for hostname and address resolution. 379The 380.Dx 381resolver can be configured to do DNS 382queries directly, therefore it is not necessary to enable this 383option when serving only 384.Dx 385.Tn NIS 386clients. 387.It Fl d 388Cause the server to run in debugging mode. 389Normally, 390.Nm 391reports only unusual errors (access violations, file access failures) 392using the 393.Xr syslog 3 394facility. 395In debug mode, the server does not background 396itself and prints extra status messages to stderr for each 397request that it receives. 398Also, while running in debug mode, 399.Nm 400will not spawn any additional subprocesses as it normally does 401when handling yp_all requests or doing DNS lookups. 402(These actions 403often take a fair amount of time to complete and are therefore handled 404in subprocesses, allowing the parent server process to go on handling 405other requests.) 406This makes it easier to trace the server with 407a debugging tool. 408.It Fl P Ar port 409Force ypserv to bind to a specific TCP/UDP port, rather than selecting 410its own. 411.It Fl p Ar path 412Normally, 413.Nm 414assumes that all 415.Tn NIS 416maps are stored under 417.Pa /var/yp . 418The 419.Fl p 420flag may be used to specify an alternate 421.Tn NIS 422root path, allowing 423the system administrator to move the map files to a different place 424within the file system. 425.El 426.Sh FILES 427.Bl -tag -width Pa -compact 428.It Pa /var/yp/[domainname]/[maps] 429the 430.Tn NIS 431maps 432.It Pa /etc/nsswitch.conf 433name switch configuration file 434.It Pa /var/yp/securenets 435host access control file 436.El 437.Sh SEE ALSO 438.Xr ypcat 1 , 439.Xr db 3 , 440.Xr hosts_access 5 , 441.Xr rc.conf 5 , 442.Xr rpc.yppasswdd 8 , 443.Xr tcpd 8 , 444.Xr yp 8 , 445.Xr ypbind 8 , 446.Xr ypinit 8 , 447.Xr yppush 8 , 448.Xr ypxfr 8 449.Sh HISTORY 450This version of 451.Nm 452first appeared in 453.Fx 2.2 . 454.Sh AUTHORS 455.An Bill Paul Aq Mt wpaul@ctr.columbia.edu 456