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