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