11622 clean up rarer mandoc lint warnings

          --- old/usr/src/man/man1m/ypserv.1m
          +++ new/usr/src/man/man1m/ypserv.1m
   1    1  '\" te
   2    2  .\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3    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    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    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    6  .TH YPSERV 1M "Dec 15, 2004"
   7    7  .SH NAME
   8    8  ypserv, ypxfrd \- NIS server and binder processes
   9    9  .SH SYNOPSIS
  10      -.LP
  11   10  .nf
  12   11  \fB/usr/lib/netsvc/yp/ypserv\fR [\fB-dv\fR] [\fB-i\fR | \fB-I\fR] [\fB-r\fR | \fB-R\fR]
  13   12  .fi
  14   13  
  15   14  .LP
  16   15  .nf
  17   16  \fB/usr/lib/netsvc/yp/ypxfrd\fR
  18   17  .fi
  19   18  
  20   19  .SH DESCRIPTION
  21      -.sp
  22      -.LP
  23   20  The Network Information Service (\fBNIS\fR) provides a simple network lookup
  24   21  service consisting of databases and processes. The databases are \fBndbm\fR
  25   22  files in a directory tree rooted at \fB/var/yp\fR. See \fBndbm\fR(3C). These
  26   23  files are described in \fBypfiles\fR(4). The processes are
  27   24  \fB/usr/lib/netsvc/yp/ypserv\fR, the \fBNIS\fR database lookup server, and
  28   25  \fB/usr/lib/netsvc/yp/ypbind\fR, the \fBNIS\fR binder. The programmatic
  29   26  interface to the \fBNIS\fR service is described in \fBypclnt\fR(3NSL).
  30   27  Administrative tools are described in \fByppoll\fR(1M), \fByppush\fR(1M),
  31   28  \fBypset\fR(1M), \fBypxfr\fR(1M), and \fBypwhich\fR(1). Tools to see the
  32   29  contents of \fBNIS\fR maps are described in \fBypcat\fR(1), and

  33   30  \fBypmatch\fR(1). Database generation and maintenance tools are described in
  34   31  \fBypinit\fR(1M), \fBypmake\fR(1M), and \fBmakedbm\fR(1M).
  35   32  .sp
  36   33  .LP
  37   34  The \fBypserv\fR utility is a daemon process typically activated at system
  38   35  startup from \fBsvc:/network/nis/server:default\fR. Alternatively, you can, as
  39   36  the root user, start \fBNIS\fR services using \fBypstart\fR(1M) from the
  40   37  command-line. \fBypserv\fR runs only on \fBNIS\fR server machines with a
  41   38  complete \fBNIS\fR database. You can halt all \fBNIS\fR services using the
  42   39  \fBypstop\fR(1M) command.
  43   40  .sp
  44   41  .LP
  45   42  The \fBypxfrd\fR utility transfers entire \fBNIS\fR maps in an efficient
  46   43  manner. For systems that use this daemon, map transfers are 10 to 100 times
  47   44  faster, depending on the map. To use this daemon, be sure \fBypxfrd\fR is
  48   45  running on the master server. See \fB/usr/lib/netsvc/yp/ypstart\fR. \fBypxfr\fR
  49   46  attempts to use \fBypxfrd\fR first. If that fails, it prints a warning, then
  50   47  uses the older transfer method.
  51   48  .sp
  52   49  .LP
  53   50  The \fBypserv\fR daemon's primary function is to look up information in its
  54   51  local database of \fBNIS\fR maps.
  55   52  .sp
  56   53  .LP
  57   54  The operations performed by \fBypserv\fR are defined for the implementor by the
  58   55  \fIYP Protocol Specification\fR, and for the programmer by the header file
  59   56  <\fBrpcsvc/yp_prot.h\fR>.
  60   57  .sp
  61   58  .LP
  62   59  Communication to and from \fBypserv\fR is by means of \fBRPC\fR calls. Lookup
  63   60  functions are described in \fBypclnt\fR(3NSL), and are supplied as C-callable
  64   61  functions in the \fBlibnsl\fR(3LIB) library. There are four lookup functions,
  65   62  all of which are performed on a specified map within some \fBNIS\fR domain:
  66   63  \fByp_match\fR(3NSL), \fByp_first\fR(3NSL), \fByp_next\fR(3NSL), and
  67   64  \fByp_all\fR(3NSL). The \fByp_match\fR operation takes a key, and returns the
  68   65  associated value. The \fByp_first\fR operation returns the first key-value pair
  69   66  from the map, and \fByp_next\fR can be used to enumerate the remainder.
  70   67  \fByp_all\fR ships the entire map to the requester as the response to a single
  71   68  \fBRPC\fR request.
  72   69  .sp
  73   70  .LP
  74   71  A number of special keys in the \fBDBM\fR files can alter the way in which
  75   72  \fBypserv\fR operates. The keys of interest are:
  76   73  .sp
  77   74  .ne 2
  78   75  .na
  79   76  \fB\fBYP_INTERDOMAIN\fR\fR
  80   77  .ad
  81   78  .RS 21n
  82   79  The presence of this key causes \fBypserv\fR to forward to a \fBDNS\fR server
  83   80  host lookups that cannot be satisfied by the \fBDBM\fR files.
  84   81  .RE
  85   82  
  86   83  .sp
  87   84  .ne 2
  88   85  .na
  89   86  \fB\fBYP_SECURE\fR\fR
  90   87  .ad
  91   88  .RS 21n
  92   89  This key causes \fBypserv\fR to answer only questions coming from clients on
  93   90  reserved ports.
  94   91  .RE
  95   92  
  96   93  .sp
  97   94  .ne 2
  98   95  .na
  99   96  \fB\fBYP_MULTI_\fR\fIhostname\fR\fR
 100   97  .ad
 101   98  .RS 21n
 102   99  This is a special key in the form, \fBYP_MULTI_\fR\fIhostname
 103  100  addr1,...,addrN.\fR A client looking for \fIhostname\fR receives the closest
 104  101  address.
 105  102  .RE
 106  103  
 107  104  .sp
 108  105  .LP
 109  106  Two other functions supply information about the map, rather than map entries:
 110  107  \fByp_order\fR(3NSL), and \fByp_master\fR(3NSL). In fact, both order number and
 111  108  master name exist in the map as key-value pairs, but the server will not return
 112  109  either through the normal lookup functions. If you examine the map with
 113  110  \fBmakedbm\fR(1M), however, they are visible. Other functions are used within
 114  111  the \fBNIS\fR service subsystem itself, and are not of general interest to
 115  112  \fBNIS\fR clients. These functions include \fBdo_you_serve_this_domain?\fR,
 116  113  \fBtransfer_map\fR, and \fBreinitialize_internal_state\fR.
 117  114  .sp
 118  115  .LP
 119  116  On start up, \fBypserv\fR checks for the existence of the NIS to LDAP (N2L)
 120  117  configuration file \fB/var/yp/NISLDAPmapping\fR. If it is present then a master
 121  118  server starts in N2L mode. If the file is not present it starts in
 122  119  "traditional" (non N2L) mode. Slave servers always start in traditional mode.
 123  120  .sp
 124  121  .LP
 125  122  In N2L mode, a new set of map files, with an \fBLDAP_\fR prefix, are generated,
 126  123  based on the contents of the LDAP DIT. The old map files, NIS source files and
 127  124  \fBypmake\fR(1M) are not used.
 128  125  .sp
 129  126  .LP
 130  127  It is possible that \fBypmake\fR(1M) can be accidentally run in N2L mode. If
 131  128  the occurs, the old style map files are overwritten. That the map files are
 132  129  overwritten is harmless. However, any resulting \fByppush\fR(1M) operation will
 133  130  push information based on the DIT rather than the source files. The user may
 134  131  not expect information based on the DIT. \fBypserv\fR keeps track of the last
 135  132  modification date of the old style map files. If the map files have been
 136  133  updated, a warning is logged that suggests that the user call \fByppush\fR
 137  134  directly instead of \fBypmake\fR.
 138  135  .sp
 139  136  .LP
 140  137  If a server attempts to run in N2L mode and a LDAP server cannot be contacted,
 141  138  it behaves as follows:
 142  139  .RS +4
 143  140  .TP
 144  141  1.
 145  142  When \fBypserv\fR is started, a warning will be logged.
 146  143  .RE
 147  144  .RS +4
 148  145  .TP
 149  146  2.
 150  147  When a NIS read access is made and the TTL entry has expired, a warning is
 151  148  logged.Information that is returned from the cache has not been updated.
 152  149  .RE
 153  150  .RS +4
 154  151  .TP
 155  152  3.
 156  153  When a NIS write access is made, a warning is logged. The cache will not be
 157  154  updated, and a NIS failure will be returned.
 158  155  .RE
 159  156  .sp

 160  157  .LP
 161  158  If \fBypxfrd\fR is running in N2L mode and is asked to transfer a map,
 162  159  \fBypxfrd\fR first checks whether the map is out of date. If the map is out of
 163  160  date, \fBypxfrd\fR initiates an update from the DIT. \fBypxfrd\fR cannot wait
 164  161  for the update to complete. If \fBypxfrd\fR waited, the client end \fBypxfr\fR
 165  162  operation could time out. To prevent \fBypxfrd\fR from timing out, the existing
 166  163  map is transferred from the cache. The most up to date map will be transferred
 167  164  on subsequent \fBypxfrd\fR operations.
 168  165  .SH OPTIONS
 169  166  .SS "ypserv"
 170      -.sp
 171  167  .ne 2
 172  168  .na
 173  169  \fB\fB-d\fR\fR
 174  170  .ad
 175  171  .RS 7n
 176  172  The \fBNIS\fR service should go to the \fBDNS\fR for more host information.
 177  173  This requires the existence of a correct \fB/etc/resolv.conf\fR file pointing
 178  174  to a \fBDNS\fR server. This option turns on \fBDNS\fR forwarding regardless of
 179  175  whether or not the \fBYP_INTERDOMAIN\fR flag is set in the \fBhosts\fR maps.
 180  176  See \fBmakedbm\fR(1M). In the absence of an \fB/etc/resolv.conf\fR file,

 181  177  \fBypserv\fR complains, but ignores the \fB-d\fR option.
 182  178  .RE
 183  179  
 184  180  .sp
 185  181  .ne 2
 186  182  .na
 187  183  \fB\fB-i\fR\fR
 188  184  .ad
 189  185  .RS 7n
 190  186  If in N2L mode, initialize the NIS related parts of the \fBDIT\fR based on the
 191  187  current, non \fBLDAP_\fR prefixed, map files. The \fBLDAP_\fR prefixed maps are
 192  188  not created or updated. If you require that \fBLDAP_\fR prefixed maps be
 193  189  updated or created, then use the \fB-ir\fR option.
 194  190  .sp
 195  191  The \fB-i\fR option does not attempt to create any NIS domain or container
 196  192  objects. If any NIS domain or container objects have not already been created,
 197  193  then errors will occur, as entries are written to nonexistent containers.
 198  194  .RE
 199  195  
 200  196  .sp
 201  197  .ne 2
 202  198  .na
 203  199  \fB\fB-I\fR\fR
 204  200  .ad
 205  201  .RS 7n
 206  202  Identical to \fB-i\fR, except that any missing domain and container objects are
 207  203  created.
 208  204  .RE
 209  205  
 210  206  .sp
 211  207  .ne 2
 212  208  .na
 213  209  \fB\fB-r\fR\fR
 214  210  .ad
 215  211  .RS 7n
 216  212  If in N2L mode, then refresh the \fBLDAP_\fR prefixed map files based on the
 217  213  contents of the \fBDIT\fR.
 218  214  .RE
 219  215  
 220  216  .sp
 221  217  .ne 2
 222  218  .na
 223  219  \fB\fB-ir\fR\fR
 224  220  .ad
 225  221  .RS 7n
 226  222  If both \fB-i\fR and \fB-r\fR are specified in N2L mode, then the \fBDIT\fR
 227  223  will first be initialized from the current non \fBLDAP_\fR prefixed map files.
 228  224  A new set of \fBLDAP_\fR prefixed maps will then be generated from the contents
 229  225  of the \fBDIT\fR. A new set of \fBLDAP_\fR prefixed maps is required when
 230  226  moving from traditional NIS to N2L mode NIS.
 231  227  .RE
 232  228  
 233  229  .sp
 234  230  .ne 2
 235  231  .na
 236  232  \fB\fB-Ir\fR\fR
 237  233  .ad
 238  234  .RS 7n
 239  235  Identical to \fB-ir\fR, except that any missing domain and container objects
 240  236  are created.
 241  237  .RE
 242  238  
 243  239  .sp
 244  240  .ne 2
 245  241  .na
 246  242  \fB\fB-v\fR\fR
 247  243  .ad
 248  244  .RS 7n
 249  245  Operate in the verbose mode, printing diagnostic messages to stderr.
 250  246  .RE
 251  247  
 252  248  .sp
 253  249  .LP
 254  250  When run with the \fB-i\fR, \fB-r\fR, \fB-I\fR, \fB-ir\fR or \fB-Ir\fR options,
 255  251  the \fBypserv\fR command runs in the foreground and exits once map
 256  252  initialization has been completed. Once the \fBypserv\fR command exits, the
 257  253  user knows the maps are ready and can restart \fBypserv\fR and the other
 258  254  \fByp\fR daemons by running \fBypstart\fR(1M).
 259  255  .sp

 260  256  .LP
 261  257  If there is a requirement to initialize the \fBDIT\fR from the NIS source
 262  258  files, which may have been modified since the maps were last remade, run
 263  259  \fBypmake\fR before running \fBypserv\fR \fB-i\fR or \fBypserv\fR \fB-ir\fR.
 264  260  \fBypmake\fR regenerated old style NIS maps. Then \fBypserv\fR \fB-ir\fR dumps
 265  261  them into the \fBDIT\fR. When the \fB-ir\fR option is used, the \fBLDAP_\fR
 266  262  prefixe maps are also generated or updated. Since these maps will be more
 267  263  recent than the old style maps, \fBypmake\fR will not be reported as erroneous
 268  264  when it is run.
 269  265  .SH FILES
 270      -.sp
 271  266  .ne 2
 272  267  .na
 273  268  \fB\fB/var/yp/securenets\fR\fR
 274  269  .ad
 275  270  .sp .6
 276  271  .RS 4n
 277  272  Defines the hosts and networks that are granted access to information in the
 278  273  served domain. It is read at startup time by both \fBypserv\fR and
 279  274  \fBypxfrd\fR.
 280  275  .RE

 281  276  
 282  277  .sp
 283  278  .ne 2
 284  279  .na
 285  280  \fB\fB/var/yp/ypserv.log\fR\fR
 286  281  .ad
 287  282  .sp .6
 288  283  .RS 4n
 289  284  If the \fB/var/yp/ypserv.log\fR file exists when \fBypserv\fR starts up, log
 290  285  information is written to it when error conditions arise.
 291  286  .RE
 292  287  
 293  288  .sp

 294  289  .ne 2
 295  290  .na
 296  291  \fB\fB/var/yp/binding/domainname/ypservers\fR\fR
 297  292  .ad
 298  293  .sp .6
 299  294  .RS 4n
 300  295  Lists the \fBNIS\fR server hosts that \fBypbind\fR can bind to.
 301  296  .RE
 302  297  
 303  298  .SH SEE ALSO
 304      -.sp
 305      -.LP
 306  299  \fBsvcs\fR(1), \fBypcat\fR(1), \fBypmatch\fR(1), \fBypwhich\fR(1),
 307  300  \fBdomainname\fR(1M), \fBmakedbm\fR(1M), \fBsvcadm\fR(1M), \fBypbind\fR(1M),
 308  301  \fBypinit\fR(1M), \fBypmake\fR(1M), \fByppoll\fR(1M), \fByppush\fR(1M),
 309  302  \fBypset\fR(1M), \fBypstart\fR(1M), \fBypstop\fR(1M), \fBypxfr\fR(1M),
 310  303  \fBndbm\fR(3C), \fBypclnt\fR(3NSL), \fBlibnsl\fR(3LIB),
 311  304  \fBNISLDAPmapping\fR(4), \fBsecurenets\fR(4), \fBypfiles\fR(4),
 312  305  \fBypserv\fR(4), \fBattributes\fR(5), \fBsmf\fR(5)
 313      -.sp
 314      -.LP
 315  306  
 316      -.sp
 317      -.LP
 318      -\fI\fR
 319  307  .SH NOTES
 320      -.sp
 321      -.LP
 322  308  \fBypserv\fR supports multiple domains. The \fBypserv\fR process determines the
 323  309  domains it serves by looking for directories of the same name in the directory
 324  310  \fB/var/yp\fR. It replies to all broadcasts requesting yp service for that
 325  311  domain.
 326  312  .sp
 327  313  .LP
 328  314  The Network Information Service (\fBNIS\fR) was formerly known as Sun Yellow
 329  315  Pages (\fBYP\fR). The functionality of the two remains the same; only the name
 330  316  has changed. The name Yellow Pages is a registered trademark in the United
 331  317  Kingdom of British Telecommunications PLC, and must not be used without

 332  318  permission.
 333  319  .sp
 334  320  .LP
 335  321  \fBNIS\fR uses \fBndbm()\fR files to store maps. Therefore, it is subject to
 336  322  the 1024 byte limitations described in the USAGE and NOTES sections of the
 337  323  \fBndbm\fR(3C) man page.
 338  324  .sp
 339  325  .LP
 340  326  The NIS server service is managed by the service management facility,
 341  327  \fBsmf\fR(5), under the service identifier:
 342  328  .sp
 343  329  .in +2
 344  330  .nf
 345  331  svc:/network/nis/server:default
 346  332  .fi
 347  333  .in -2
 348  334  .sp
 349  335  
 350  336  .sp
 351  337  .LP
 352  338  Administrative actions on this service, such as enabling, disabling, or
 353  339  requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
 354  340  status can be queried using the \fBsvcs\fR(1) command.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX