usr.sbin/ypserv/ypserv.8

   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.5 2006/03/26 22:56:58 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 .Ss Security
 220 In general, any remote user can issue an RPC to
 221 .Nm
 222 and retrieve the contents of your
 223 .Tn NIS
 224 maps, provided the remote user
 225 knows your domain name.
 226 To prevent such unauthorized transactions,
 227 .Nm
 228 supports a feature called
 229 .Pa securenets
 230 which can be used to restrict access to a given set of hosts.
 231 At startup,
 232 .Nm
 233 will attempt to load the securenets information from a file
 234 called
 235 .Pa /var/yp/securenets .
 236 (Note that this path varies depending on the path specified with
 237 the
 238 .Fl p
 239 option, which is explained below.)
 240 This file contains entries
 241 that consist of a network specification and a network mask separated
 242 by white space.
 243 Lines starting with
 244 .Dq \&#
 245 are considered to be comments.
 246 A
 247 sample securenets file might look like this:
 248 .Bd -unfilled -offset indent
 249 # allow connections from local host -- mandatory
 250 127.0.0.1     255.255.255.255
 251 # allow connections from any host
 252 # on the 192.168.128.0 network
 253 192.168.128.0 255.255.255.0
 254 # allow connections from any host
 255 # between 10.0.0.0 to 10.0.15.255
 256 10.0.0.0      255.255.240.0
 257 .Ed
 258 .Pp
 259 If
 260 .Nm
 261 receives a request from an address that matches one of these rules,
 262 it will process the request normally.
 263 If the address fails to match
 264 a rule, the request will be ignored and a warning message will be
 265 logged.
 266 If the
 267 .Pa /var/yp/securenets
 268 file does not exist,
 269 .Nm
 270 will allow connections from any host.
 271 .Pp
 272 The
 273 .Nm
 274 program also has support for Wietse Venema's
 275 .Em tcpwrapper
 276 package, though it is not compiled in by default since
 277 the
 278 .Em tcpwrapper
 279 package is not distributed with
 280 .Dx .
 281 However, if you have
 282 .Pa libwrap.a
 283 and
 284 .Pa tcpd.h ,
 285 you can easily recompile
 286 .Nm
 287 with them.
 288 This allows the administrator to use the tcpwrapper
 289 configuration files
 290 .Pa ( /etc/hosts.allow
 291 and
 292 .Pa /etc/hosts.deny )
 293 for access control instead of
 294 .Pa /var/yp/securenets .
 295 .Pp
 296 Note: while both of these access control mechanisms provide some
 297 security, they, like the privileged port test, are both vulnerable
 298 to
 299 .Dq IP spoofing
 300 attacks.
 301 .Ss NIS v1 compatibility
 302 This version of
 303 .Nm
 304 has some support for serving
 305 .Tn NIS
 306 v1 clients.
 307 The
 308 .Dx
 309 .Tn NIS
 310 implementation only uses the
 311 .Tn NIS
 312 v2 protocol, however other implementations
 313 include support for the v1 protocol for backwards compatibility
 314 with older systems.
 315 The
 316 .Xr ypbind 8
 317 daemons supplied with these systems will try to establish a binding
 318 to an
 319 .Tn NIS
 320 v1 server even though they may never actually need it (and they may
 321 persist in broadcasting in search of one even after they receive a
 322 response from a v2 server). Note that while
 323 support for normal client calls is provided, this version of
 324 .Nm
 325 does not handle v1 map transfer requests; consequently, it cannot
 326 be used as a master or slave in conjunction with older
 327 .Tn NIS
 328 servers that
 329 only support the v1 protocol.
 330 Fortunately, there probably aren't any
 331 such servers still in use today.
 332 .Ss NIS servers that are also NIS clients
 333 Care must be taken when running
 334 .Nm
 335 in a multi-server domain where the server machines are also
 336 .Tn NIS
 337 clients.
 338 It is generally a good idea to force the servers to
 339 bind to themselves rather than allowing them to broadcast bind
 340 requests and possibly become bound to each other: strange failure
 341 modes can result if one server goes down and
 342 others are dependent upon on it.
 343 (Eventually all the clients will
 344 time out and attempt to bind to other servers, but the delay
 345 involved can be considerable and the failure mode is still present
 346 since the servers might bind to each other all over again).
 347 .Pp
 348 Refer to the
 349 .Xr ypbind 8
 350 man page for details on how to force it to bind to a particular
 351 server.
 352 .Sh OPTIONS
 353 The following options are supported by
 354 .Nm :
 355 .Bl -tag -width flag
 356 .It Fl n
 357 This option affects the way
 358 .Nm
 359 handles yp_match requests for the
 360 .Pa hosts.byname
 361 and
 362 .Pa hosts.byaddress
 363 maps.
 364 By default, if
 365 .Nm
 366 can't find an entry for a given host in its hosts maps, it will
 367 return an error and perform no further processing.
 368 With the
 369 .Fl n
 370 flag,
 371 .Nm
 372 will go one step further: rather than giving up immediately, it
 373 will try to resolve the hostname or address using a DNS nameserver
 374 query.
 375 If the query is successful,
 376 .Nm
 377 will construct a fake database record and return it to the client,
 378 thereby making it seem as though the client's yp_match request
 379 succeeded.
 380 .Pp
 381 This feature is provided for compatibility with SunOS 4.1.x,
 382 which has brain-damaged resolver functions in its standard C
 383 library that depend on
 384 .Tn NIS
 385 for hostname and address resolution.
 386 The
 387 .Dx
 388 resolver can be configured to do DNS
 389 queries directly, therefore it is not necessary to enable this
 390 option when serving only
 391 .Dx
 392 .Tn NIS
 393 clients.
 394 .It Fl d
 395 Cause the server to run in debugging mode.
 396 Normally,
 397 .Nm
 398 reports only unusual errors (access violations, file access failures)
 399 using the
 400 .Xr syslog 3
 401 facility.
 402 In debug mode, the server does not background
 403 itself and prints extra status messages to stderr for each
 404 request that it receives.
 405 Also, while running in debug mode,
 406 .Nm
 407 will not spawn any additional subprocesses as it normally does
 408 when handling yp_all requests or doing DNS lookups.
 409 (These actions
 410 often take a fair amount of time to complete and are therefore handled
 411 in subprocesses, allowing the parent server process to go on handling
 412 other requests.)
 413 This makes it easier to trace the server with
 414 a debugging tool.
 415 .It Fl p Ar path
 416 Normally,
 417 .Nm
 418 assumes that all
 419 .Tn NIS
 420 maps are stored under
 421 .Pa /var/yp .
 422 The
 423 .Fl p
 424 flag may be used to specify an alternate
 425 .Tn NIS
 426 root path, allowing
 427 the system administrator to move the map files to a different place
 428 within the filesystem.
 429 .El
 430 .Sh FILES
 431 .Bl -tag -width Pa -compact
 432 .It Pa /var/yp/[domainname]/[maps]
 433 the
 434 .Tn NIS
 435 maps
 436 .It Pa /etc/host.conf
 437 resolver configuration file
 438 .It Pa /var/yp/securenets
 439 host access control file
 440 .El
 441 .Sh SEE ALSO
 442 .Xr ypcat 1 ,
 443 .Xr db 3 ,
 444 .Xr rpc.yppasswdd 8 ,
 445 .Xr yp 8 ,
 446 .Xr ypbind 8 ,
 447 .Xr ypinit 8 ,
 448 .Xr yppush 8 ,
 449 .Xr ypxfr 8
 450 .Sh HISTORY
 451 This version of
 452 .Nm
 453 first appeared in
 454 .Fx 2.2 .
 455 .Sh AUTHORS
 456 .An Bill Paul Aq wpaul@ctr.columbia.edu