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