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