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