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