1 '\" te
   2 .\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH YPSERV 1M "Dec 15, 2004"
   7 .SH NAME
   8 ypserv, ypxfrd \- NIS server and binder processes
  10 .LP
  11 .nf
  12 \fB/usr/lib/netsvc/yp/ypserv\fR [\fB-dv\fR] [\fB-i\fR | \fB-I\fR] [\fB-r\fR | \fB-R\fR]
  13 .fi
  15 .LP
  16 .nf
  17 \fB/usr/lib/netsvc/yp/ypxfrd\fR
  18 .fi
  21 .sp
  22 .LP
  23 The Network Information Service (\fBNIS\fR) provides a simple network lookup
  24 service consisting of databases and processes. The databases are \fBndbm\fR
  25 files in a directory tree rooted at \fB/var/yp\fR. See \fBndbm\fR(3C). These
  26 files are described in \fBypfiles\fR(4). The processes are
  27 \fB/usr/lib/netsvc/yp/ypserv\fR, the \fBNIS\fR database lookup server, and
  28 \fB/usr/lib/netsvc/yp/ypbind\fR, the \fBNIS\fR binder. The programmatic
  29 interface to the \fBNIS\fR service is described in \fBypclnt\fR(3NSL).
  30 Administrative tools are described in \fByppoll\fR(1M), \fByppush\fR(1M),
  31 \fBypset\fR(1M), \fBypxfr\fR(1M), and \fBypwhich\fR(1). Tools to see the
  32 contents of \fBNIS\fR maps are described in \fBypcat\fR(1), and
  33 \fBypmatch\fR(1). Database generation and maintenance tools are described in
  34 \fBypinit\fR(1M), \fBypmake\fR(1M), and \fBmakedbm\fR(1M).
  35 .sp
  36 .LP
  37 The \fBypserv\fR utility is a daemon process typically activated at system
  38 startup from \fBsvc:/network/nis/server:default\fR. Alternatively, you can, as
  39 the root user, start \fBNIS\fR services using \fBypstart\fR(1M) from the
  40 command-line. \fBypserv\fR runs only on \fBNIS\fR server machines with a
  41 complete \fBNIS\fR database. You can halt all \fBNIS\fR services using the
  42 \fBypstop\fR(1M) command.
  43 .sp
  44 .LP
  45 The \fBypxfrd\fR utility transfers entire \fBNIS\fR maps in an efficient
  46 manner. For systems that use this daemon, map transfers are 10 to 100 times
  47 faster, depending on the map. To use this daemon, be sure \fBypxfrd\fR is
  48 running on the master server. See \fB/usr/lib/netsvc/yp/ypstart\fR. \fBypxfr\fR
  49 attempts to use \fBypxfrd\fR first. If that fails, it prints a warning, then
  50 uses the older transfer method.
  51 .sp
  52 .LP
  53 The \fBypserv\fR daemon's primary function is to look up information in its
  54 local database of \fBNIS\fR maps.
  55 .sp
  56 .LP
  57 The operations performed by \fBypserv\fR are defined for the implementor by the
  58 \fIYP Protocol Specification\fR, and for the programmer by the header file
  59 <\fBrpcsvc/yp_prot.h\fR>.
  60 .sp
  61 .LP
  62 Communication to and from \fBypserv\fR is by means of \fBRPC\fR calls. Lookup
  63 functions are described in \fBypclnt\fR(3NSL), and are supplied as C-callable
  64 functions in the \fBlibnsl\fR(3LIB) library. There are four lookup functions,
  65 all of which are performed on a specified map within some \fBNIS\fR domain:
  66 \fByp_match\fR(3NSL), \fByp_first\fR(3NSL), \fByp_next\fR(3NSL), and
  67 \fByp_all\fR(3NSL). The \fByp_match\fR operation takes a key, and returns the
  68 associated value. The \fByp_first\fR operation returns the first key-value pair
  69 from the map, and \fByp_next\fR can be used to enumerate the remainder.
  70 \fByp_all\fR ships the entire map to the requester as the response to a single
  71 \fBRPC\fR request.
  72 .sp
  73 .LP
  74 A number of special keys in the \fBDBM\fR files can alter the way in which
  75 \fBypserv\fR operates. The keys of interest are:
  76 .sp
  77 .ne 2
  78 .na
  80 .ad
  81 .RS 21n
  82 The presence of this key causes \fBypserv\fR to forward to a \fBDNS\fR server
  83 host lookups that cannot be satisfied by the \fBDBM\fR files.
  84 .RE
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBYP_SECURE\fR\fR
  90 .ad
  91 .RS 21n
  92 This key causes \fBypserv\fR to answer only questions coming from clients on
  93 reserved ports.
  94 .RE
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBYP_MULTI_\fR\fIhostname\fR\fR
 100 .ad
 101 .RS 21n
 102 This is a special key in the form, \fBYP_MULTI_\fR\fIhostname
 103 addr1,...,addrN.\fR A client looking for \fIhostname\fR receives the closest
 104 address.
 105 .RE
 107 .sp
 108 .LP
 109 Two other functions supply information about the map, rather than map entries:
 110 \fByp_order\fR(3NSL), and \fByp_master\fR(3NSL). In fact, both order number and
 111 master name exist in the map as key-value pairs, but the server will not return
 112 either through the normal lookup functions. If you examine the map with
 113 \fBmakedbm\fR(1M), however, they are visible. Other functions are used within
 114 the \fBNIS\fR service subsystem itself, and are not of general interest to
 115 \fBNIS\fR clients. These functions include \fBdo_you_serve_this_domain?\fR,
 116 \fBtransfer_map\fR, and \fBreinitialize_internal_state\fR.
 117 .sp
 118 .LP
 119 On start up, \fBypserv\fR checks for the existence of the NIS to LDAP (N2L)
 120 configuration file \fB/var/yp/NISLDAPmapping\fR. If it is present then a master
 121 server starts in N2L mode. If the file is not present it starts in
 122 "traditional" (non N2L) mode. Slave servers always start in traditional mode.
 123 .sp
 124 .LP
 125 In N2L mode, a new set of map files, with an \fBLDAP_\fR prefix, are generated,
 126 based on the contents of the LDAP DIT. The old map files, NIS source files and
 127 \fBypmake\fR(1M) are not used.
 128 .sp
 129 .LP
 130 It is possible that \fBypmake\fR(1M) can be accidentally run in N2L mode. If
 131 the occurs, the old style map files are overwritten. That the map files are
 132 overwritten is harmless. However, any resulting \fByppush\fR(1M) operation will
 133 push information based on the DIT rather than the source files. The user may
 134 not expect information based on the DIT. \fBypserv\fR keeps track of the last
 135 modification date of the old style map files. If the map files have been
 136 updated, a warning is logged that suggests that the user call \fByppush\fR
 137 directly instead of \fBypmake\fR.
 138 .sp
 139 .LP
 140 If a server attempts to run in N2L mode and a LDAP server cannot be contacted,
 141 it behaves as follows:
 142 .RS +4
 143 .TP
 144 1.
 145 When \fBypserv\fR is started, a warning will be logged.
 146 .RE
 147 .RS +4
 148 .TP
 149 2.
 150 When a NIS read access is made and the TTL entry has expired, a warning is
 151 logged.Information that is returned from the cache has not been updated.
 152 .RE
 153 .RS +4
 154 .TP
 155 3.
 156 When a NIS write access is made, a warning is logged. The cache will not be
 157 updated, and a NIS failure will be returned.
 158 .RE
 159 .sp
 160 .LP
 161 If \fBypxfrd\fR is running in N2L mode and is asked to transfer a map,
 162 \fBypxfrd\fR first checks whether the map is out of date. If the map is out of
 163 date, \fBypxfrd\fR initiates an update from the DIT. \fBypxfrd\fR cannot wait
 164 for the update to complete. If \fBypxfrd\fR waited, the client end \fBypxfr\fR
 165 operation could time out. To prevent \fBypxfrd\fR from timing out, the existing
 166 map is transferred from the cache. The most up to date map will be transferred
 167 on subsequent \fBypxfrd\fR operations.
 169 .SS "ypserv"
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fB-d\fR\fR
 174 .ad
 175 .RS 7n
 176 The \fBNIS\fR service should go to the \fBDNS\fR for more host information.
 177 This requires the existence of a correct \fB/etc/resolv.conf\fR file pointing
 178 to a \fBDNS\fR server. This option turns on \fBDNS\fR forwarding regardless of
 179 whether or not the \fBYP_INTERDOMAIN\fR flag is set in the \fBhosts\fR maps.
 180 See \fBmakedbm\fR(1M). In the absence of an \fB/etc/resolv.conf\fR file,
 181 \fBypserv\fR complains, but ignores the \fB-d\fR option.
 182 .RE
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fB-i\fR\fR
 188 .ad
 189 .RS 7n
 190 If in N2L mode, initialize the NIS related parts of the \fBDIT\fR based on the
 191 current, non \fBLDAP_\fR prefixed, map files. The \fBLDAP_\fR prefixed maps are
 192 not created or updated. If you require that \fBLDAP_\fR prefixed maps be
 193 updated or created, then use the \fB-ir\fR option.
 194 .sp
 195 The \fB-i\fR option does not attempt to create any NIS domain or container
 196 objects. If any NIS domain or container objects have not already been created,
 197 then errors will occur, as entries are written to nonexistent containers.
 198 .RE
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fB-I\fR\fR
 204 .ad
 205 .RS 7n
 206 Identical to \fB-i\fR, except that any missing domain and container objects are
 207 created.
 208 .RE
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fB-r\fR\fR
 214 .ad
 215 .RS 7n
 216 If in N2L mode, then refresh the \fBLDAP_\fR prefixed map files based on the
 217 contents of the \fBDIT\fR.
 218 .RE
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fB-ir\fR\fR
 224 .ad
 225 .RS 7n
 226 If both \fB-i\fR and \fB-r\fR are specified in N2L mode, then the \fBDIT\fR
 227 will first be initialized from the current non \fBLDAP_\fR prefixed map files.
 228 A new set of \fBLDAP_\fR prefixed maps will then be generated from the contents
 229 of the \fBDIT\fR. A new set of \fBLDAP_\fR prefixed maps is required when
 230 moving from traditional NIS to N2L mode NIS.
 231 .RE
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fB-Ir\fR\fR
 237 .ad
 238 .RS 7n
 239 Identical to \fB-ir\fR, except that any missing domain and container objects
 240 are created.
 241 .RE
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fB-v\fR\fR
 247 .ad
 248 .RS 7n
 249 Operate in the verbose mode, printing diagnostic messages to stderr.
 250 .RE
 252 .sp
 253 .LP
 254 When run with the \fB-i\fR, \fB-r\fR, \fB-I\fR, \fB-ir\fR or \fB-Ir\fR options,
 255 the \fBypserv\fR command runs in the foreground and exits once map
 256 initialization has been completed. Once the \fBypserv\fR command exits, the
 257 user knows the maps are ready and can restart \fBypserv\fR and the other
 258 \fByp\fR daemons by running \fBypstart\fR(1M).
 259 .sp
 260 .LP
 261 If there is a requirement to initialize the \fBDIT\fR from the NIS source
 262 files, which may have been modified since the maps were last remade, run
 263 \fBypmake\fR before running \fBypserv\fR \fB-i\fR or \fBypserv\fR \fB-ir\fR.
 264 \fBypmake\fR regenerated old style NIS maps. Then \fBypserv\fR \fB-ir\fR dumps
 265 them into the \fBDIT\fR. When the \fB-ir\fR option is used, the \fBLDAP_\fR
 266 prefixe maps are also generated or updated. Since these maps will be more
 267 recent than the old style maps, \fBypmake\fR will not be reported as erroneous
 268 when it is run.
 269 .SH FILES
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fB/var/yp/securenets\fR\fR
 274 .ad
 275 .sp .6
 276 .RS 4n
 277 Defines the hosts and networks that are granted access to information in the
 278 served domain. It is read at startup time by both \fBypserv\fR and
 279 \fBypxfrd\fR.
 280 .RE
 282 .sp
 283 .ne 2
 284 .na
 285 \fB\fB/var/yp/ypserv.log\fR\fR
 286 .ad
 287 .sp .6
 288 .RS 4n
 289 If the \fB/var/yp/ypserv.log\fR file exists when \fBypserv\fR starts up, log
 290 information is written to it when error conditions arise.
 291 .RE
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fB/var/yp/binding/domainname/ypservers\fR\fR
 297 .ad
 298 .sp .6
 299 .RS 4n
 300 Lists the \fBNIS\fR server hosts that \fBypbind\fR can bind to.
 301 .RE
 304 .sp
 305 .LP
 306 \fBsvcs\fR(1), \fBypcat\fR(1), \fBypmatch\fR(1), \fBypwhich\fR(1),
 307 \fBdomainname\fR(1M), \fBmakedbm\fR(1M), \fBsvcadm\fR(1M), \fBypbind\fR(1M),
 308 \fBypinit\fR(1M), \fBypmake\fR(1M), \fByppoll\fR(1M), \fByppush\fR(1M),
 309 \fBypset\fR(1M), \fBypstart\fR(1M), \fBypstop\fR(1M), \fBypxfr\fR(1M),
 310 \fBndbm\fR(3C), \fBypclnt\fR(3NSL), \fBlibnsl\fR(3LIB),
 311 \fBNISLDAPmapping\fR(4), \fBsecurenets\fR(4), \fBypfiles\fR(4),
 312 \fBypserv\fR(4), \fBattributes\fR(5), \fBsmf\fR(5)
 313 .sp
 314 .LP
 316 .sp
 317 .LP
 318 \fI\fR
 319 .SH NOTES
 320 .sp
 321 .LP
 322 \fBypserv\fR supports multiple domains. The \fBypserv\fR process determines the
 323 domains it serves by looking for directories of the same name in the directory
 324 \fB/var/yp\fR. It replies to all broadcasts requesting yp service for that
 325 domain.
 326 .sp
 327 .LP
 328 The Network Information Service (\fBNIS\fR) was formerly known as Sun Yellow
 329 Pages (\fBYP\fR). The functionality of the two remains the same; only the name
 330 has changed. The name Yellow Pages is a registered trademark in the United
 331 Kingdom of British Telecommunications PLC, and must not be used without
 332 permission.
 333 .sp
 334 .LP
 335 \fBNIS\fR uses \fBndbm()\fR files to store maps. Therefore, it is subject to
 336 the 1024 byte limitations described in the USAGE and NOTES sections of the
 337 \fBndbm\fR(3C) man page.
 338 .sp
 339 .LP
 340 The NIS server service is managed by the service management facility,
 341 \fBsmf\fR(5), under the service identifier:
 342 .sp
 343 .in +2
 344 .nf
 345 svc:/network/nis/server:default
 346 .fi
 347 .in -2
 348 .sp
 350 .sp
 351 .LP
 352 Administrative actions on this service, such as enabling, disabling, or
 353 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
 354 status can be queried using the \fBsvcs\fR(1) command.