path: root/static/freebsd/man8/yp.8 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">YP(8)</td>
    <td class="head-vol">System Manager's Manual</td>
    <td class="head-rtitle">YP(8)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">yp</code> &#x2014; <span class="Nd">description
    of the YP/NIS system</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
  <tr>
    <td><code class="Nm">yp</code></td>
    <td></td>
  </tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">YP</code> subsystem allows network management
    of passwd, group, netgroup, hosts, services, rpc, bootparams and ethers file
    entries through the functions <a class="Xr">getpwent(3)</a>,
    <a class="Xr">getgrent(3)</a>, <a class="Xr">getnetgrent(3)</a>,
    <a class="Xr">gethostent(3)</a>, <a class="Xr">getnetent(3)</a>,
    <a class="Xr">getrpcent(3)</a>, and <a class="Xr">ethers(3)</a>. The
    <a class="Xr">bootparamd(8)</a> daemon makes direct NIS library calls since
    there are no functions in the standard C library for reading bootparams. NIS
    support is enabled in <a class="Xr">nsswitch.conf(5)</a>.</p>
<p class="Pp">The <code class="Nm">YP</code> subsystem is started automatically
    in <span class="Pa">/etc/rc</span> if it has been initialized in
    <span class="Pa">/etc/rc.conf</span> and if the directory
    <span class="Pa">/var/yp</span> exists (which it does in the default
    distribution). The default NIS domain must also be set with the
    <a class="Xr">domainname(1)</a> command, which will happen automatically at
    system startup if it is specified in
  <span class="Pa">/etc/rc.conf</span>.</p>
<p class="Pp">NIS is an RPC-based client/server system that allows a group of
    machines within an NIS domain to share a common set of configuration files.
    This permits a system administrator to set up NIS client systems with only
    minimal configuration data and add, remove or modify configuration data from
    a single location.</p>
<p class="Pp" id="master">The canonical copies of all NIS information are stored
    on a single machine called the NIS
    <a class="permalink" href="#master"><i class="Em">master server</i></a>. The
    databases used to store the information are called NIS
    <a class="permalink" href="#maps"><i class="Em" id="maps">maps</i></a>. In
    <span class="Ux">FreeBSD</span>, these maps are stored in
    <span class="Pa">/var/yp/</span>&#x27E8;<var class="Ar">domainname</var>&#x27E9;
    where &#x27E8;<var class="Ar">domainname</var>&#x27E9; is the name of the
    NIS domain being served. A single NIS server can support several domains at
    once, therefore it is possible to have several such directories, one for
    each supported domain. Each domain will have its own independent set of
    maps.</p>
<p class="Pp">In <span class="Ux">FreeBSD</span>, the NIS maps are Berkeley DB
    hashed database files (the same format used for the
    <a class="Xr">passwd(5)</a> database files). Other operating systems that
    support NIS use old-style <code class="Nm">ndbm</code> databases instead
    (largely because Sun Microsystems originally based their NIS implementation
    on <code class="Nm">ndbm</code>, and other vendors have simply licensed
    Sun's code rather than design their own implementation with a different
    database format). On these systems, the databases are generally split into
    <span class="Pa">.dir</span> and <span class="Pa">.pag</span> files which
    the <code class="Nm">ndbm</code> code uses to hold separate parts of the
    hash database. The Berkeley DB hash method instead uses a single file for
    both pieces of information. This means that while you may have
    <span class="Pa">passwd.byname.dir</span> and
    <span class="Pa">passwd.byname.pag</span> files on other operating systems
    (both of which are really parts of the same map),
    <span class="Ux">FreeBSD</span> will have only one file called
    <span class="Pa">passwd.byname</span>. The difference in format is not
    significant: only the NIS server, <a class="Xr">ypserv(8)</a>, and related
    tools need to know the database format of the NIS maps. Client NIS systems
    receive all NIS data in ASCII form.</p>
<p class="Pp">There are three main types of NIS systems:</p>
<ol class="Bl-enum">
  <li>NIS clients, which query NIS servers for information.</li>
  <li>NIS master servers, which maintain the canonical copies of all NIS
    maps.</li>
  <li>NIS slave servers, which maintain backup copies of NIS maps that are
      periodically updated by the master.</li>
</ol>
<p class="Pp" id="binding">A NIS client establishes what is called a
    <a class="permalink" href="#binding"><i class="Em">binding</i></a> to a
    particular NIS server using the <a class="Xr">ypbind(8)</a> daemon. The
    <a class="Xr">ypbind(8)</a> utility checks the system's default domain (as
    set by the <a class="Xr">domainname(1)</a> command) and begins broadcasting
    RPC requests on the local network. These requests specify the name of the
    domain for which <a class="Xr">ypbind(8)</a> is attempting to establish a
    binding. If a server that has been configured to serve the requested domain
    receives one of the broadcasts, it will respond to
    <a class="Xr">ypbind(8)</a>, which will record the server's address. If
    there are several servers available (a master and several slaves, for
    example), <a class="Xr">ypbind(8)</a> will use the address of the first one
    to respond. From that point on, the client system will direct all of its NIS
    requests to that server. The <a class="Xr">ypbind(8)</a> utility will
    occasionally &#x201C;ping&#x201D; the server to make sure it is still up and
    running. If it fails to receive a reply to one of its pings within a
    reasonable amount of time, <a class="Xr">ypbind(8)</a> will mark the domain
    as unbound and begin broadcasting again in the hopes of locating another
    server.</p>
<p class="Pp">NIS master and slave servers handle all NIS requests with the
    <a class="Xr">ypserv(8)</a> daemon. The <a class="Xr">ypserv(8)</a> utility
    is responsible for receiving incoming requests from NIS clients, translating
    the requested domain and map name to a path to the corresponding database
    file and transmitting data from the database back to the client. There is a
    specific set of requests that <a class="Xr">ypserv(8)</a> is designed to
    handle, most of which are implemented as functions within the standard C
    library:</p>
<dl class="Bl-tag">
  <dt id="yp_order"><a class="permalink" href="#yp_order"><code class="Fn">yp_order</code></a>()</dt>
  <dd>check the creation date of a particular map</dd>
  <dt id="yp_master"><a class="permalink" href="#yp_master"><code class="Fn">yp_master</code></a>()</dt>
  <dd>obtain the name of the NIS master server for a given map/domain</dd>
  <dt id="yp_match"><a class="permalink" href="#yp_match"><code class="Fn">yp_match</code></a>()</dt>
  <dd>lookup the data corresponding to a given in key in a particular
    map/domain</dd>
  <dt id="yp_first"><a class="permalink" href="#yp_first"><code class="Fn">yp_first</code></a>()</dt>
  <dd>obtain the first key/data pair in a particular map/domain</dd>
  <dt id="yp_next"><a class="permalink" href="#yp_next"><code class="Fn">yp_next</code></a>()</dt>
  <dd>pass <a class="Xr">ypserv(8)</a> a key in a particular map/domain and have
      it return the key/data pair immediately following it (the functions
      <code class="Fn">yp_first</code>() and <code class="Fn">yp_next</code>()
      can be used to do a sequential search of an NIS map)</dd>
  <dt id="yp_all"><a class="permalink" href="#yp_all"><code class="Fn">yp_all</code></a>()</dt>
  <dd>retrieve the entire contents of a map</dd>
</dl>
<p class="Pp">There are a few other requests which <a class="Xr">ypserv(8)</a>
    is capable of handling (i.e., acknowledge whether or not you can handle a
    particular domain (<code class="Dv">YPPROC_DOMAIN</code>), or acknowledge
    only if you can handle the domain and be silent otherwise
    (<code class="Dv">YPPROC_DOMAIN_NONACK</code>)) but these requests are
    usually generated only by <a class="Xr">ypbind(8)</a> and are not meant to
    be used by standard utilities.</p>
<p class="Pp">On networks with a large number of hosts, it is often a good idea
    to use a master server and several slaves rather than just a single master
    server. A slave server provides the exact same information as a master
    server: whenever the maps on the master server are updated, the new data
    should be propagated to the slave systems using the
    <a class="Xr">yppush(8)</a> command. The NIS
    <span class="Pa">Makefile</span> (<span class="Pa">/var/yp/Makefile</span>)
    will do this automatically if the administrator creates
    <span class="Pa">/var/yp/Makefile.local</span> and empties the
    <var class="Va">NOPUSH</var> variable:</p>
<div class="Bd Pp Bd-indent Li">
<pre><code class="Li">NOPUSH=</code></pre>
</div>
<p class="Pp">(<var class="Va">NOPUSH</var> is set to true by default because
    the default configuration is for a small network with only one NIS server).
    The <a class="Xr">yppush(8)</a> command will initiate a transaction between
    the master and slave during which the slave will transfer the specified maps
    from the master server using <a class="Xr">ypxfr(8)</a>. (The slave server
    calls <a class="Xr">ypxfr(8)</a> automatically from within
    <a class="Xr">ypserv(8)</a>; therefore it is not usually necessary for the
    administrator to use it directly. It can be run manually if desired,
    however.) Maintaining slave servers helps improve NIS performance on large
    networks by:</p>
<ul class="Bl-bullet">
  <li>Providing backup services in the event that the NIS master crashes or
      becomes unreachable</li>
  <li>Spreading the client load out over several machines instead of causing the
      master to become overloaded</li>
  <li>Allowing a single NIS domain to extend beyond a local network (the
      <a class="Xr">ypbind(8)</a> daemon might not be able to locate a server
      automatically if it resides on a network outside the reach of its
      broadcasts. It is possible to force <a class="Xr">ypbind(8)</a> to bind to
      a particular server with <a class="Xr">ypset(8)</a> but this is sometimes
      inconvenient. This problem can be avoided simply by placing a slave server
      on the local network.)</li>
</ul>
<p class="Pp" id="shadow">The <span class="Ux">FreeBSD</span>
    <a class="Xr">ypserv(8)</a> is specially designed to provide enhanced
    security (compared to other NIS implementations) when used exclusively with
    <span class="Ux">FreeBSD</span> client systems. The
    <span class="Ux">FreeBSD</span> password database system (which is derived
    directly from <span class="Ux">4.4BSD</span>) includes support for
    <a class="permalink" href="#shadow"><i class="Em">shadow passwords</i></a>.
    The standard password database does not contain users' encrypted passwords:
    these are instead stored (along with other information) in a separate
    database which is accessible only by the super-user. If the encrypted
    password database were made available as an NIS map, this security feature
    would be totally disabled, since any user is allowed to retrieve NIS
  data.</p>
<p class="Pp">To help prevent this, <span class="Ux">FreeBSD</span>'s NIS server
    handles the shadow password maps
    (<span class="Pa">master.passwd.byname</span>,
    <span class="Pa">master.passwd.byuid</span>,
    <span class="Pa">shadow.byname</span> and
    <span class="Pa">shadow.byuid</span>) in a special way: the server will only
    provide access to these maps in response to requests that originate on
    privileged ports. Since only the super-user is allowed to bind to a
    privileged port, the server assumes that all such requests come from
    privileged users. All other requests are denied: requests from
    non-privileged ports will receive only an error code from the server.
    Additionally, <span class="Ux">FreeBSD</span>'s <a class="Xr">ypserv(8)</a>
    includes support for <span class="An">Wietse Venema</span>'s tcp wrapper
    package; with tcp wrapper support enabled, the administrator can configure
    <a class="Xr">ypserv(8)</a> to respond only to selected client machines.</p>
<p class="Pp">While these enhancements provide better security than stock NIS,
    they are by no means 100% effective. It is still possible for someone with
    access to your network to spoof the server into disclosing the shadow
    password maps.</p>
<p class="Pp">On the client side, <span class="Ux">FreeBSD</span>'s
    <a class="Xr">getpwent(3)</a> functions will automatically search for the
    <span class="Pa">master.passwd</span> maps and use them if they exist. If
    they do, they will be used, and all fields in these special maps (class,
    password age and account expiration) will be decoded. If they are not found,
    the standard <span class="Pa">passwd</span> maps will be used instead.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1>
<p class="Pp">When using a
    <span class="No">non-</span><span class="Ux">FreeBSD</span> NIS server for
    <a class="Xr">passwd(5)</a> files, it is unlikely that the default MD5-based
    format that <span class="Ux">FreeBSD</span> uses for passwords will be
    accepted by it. If this is the case, the value of the
    <var class="Va">passwd_format</var> setting in
    <a class="Xr">login.conf(5)</a> should be changed to
    &quot;<code class="Li">des</code>&quot; for compatibility.</p>
<p class="Pp">Some systems, such as SunOS 4.x, need NIS to be running in order
    for their hostname resolution functions
    (<code class="Fn">gethostbyname</code>(),
    <code class="Fn">gethostbyaddr</code>(), etc.) to work properly. On these
    systems, <a class="Xr">ypserv(8)</a> performs DNS lookups when asked to
    return information about a host that does not exist in its
    <span class="Pa">hosts.byname</span> or <span class="Pa">hosts.byaddr</span>
    maps. <span class="Ux">FreeBSD</span>'s resolver uses DNS by default (it can
    be made to use NIS, if desired), therefore its NIS server does not do DNS
    lookups by default. However, <a class="Xr">ypserv(8)</a> can be made to
    perform DNS lookups if it is started with a special flag. It can also be
    made to register itself as an NIS v1 server in order to placate certain
    systems that insist on the presence of a v1 server
    (<span class="Ux">FreeBSD</span> uses only NIS v2, but many other systems,
    including SunOS 4.x, search for both a v1 and v2 server when binding).
    <span class="Ux">FreeBSD</span>'s <a class="Xr">ypserv(8)</a> does not
    actually handle NIS v1 requests, but this &#x201C;kludge mode&#x201D; is
    useful for silencing stubborn systems that search for both a v1 and v2
    server.</p>
<p class="Pp">(Please see the <a class="Xr">ypserv(8)</a> manual page for a
    detailed description of these special features and flags.)</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">domainname(1)</a>, <a class="Xr">ypcat(1)</a>,
    <a class="Xr">ypmatch(1)</a>, <a class="Xr">ypwhich(1)</a>,
    <a class="Xr">nsswitch.conf(5)</a>, <a class="Xr">yp_mkdb(8)</a>,
    <a class="Xr">ypbind(8)</a>, <a class="Xr">ypinit(8)</a>,
    <a class="Xr">yppoll(8)</a>, <a class="Xr">yppush(8)</a>,
    <a class="Xr">ypserv(8)</a>, <a class="Xr">ypset(8)</a>,
    <a class="Xr">ypxfr(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">YP</code> subsystem was written from the
    ground up by <span class="An">Theo de Raadt</span> to be compatible to Sun's
    implementation. Bug fixes, improvements and NIS server support were later
    added by <span class="An">Bill Paul</span>. The server-side code was
    originally written by <span class="An">Peter Eriksson</span> and
    <span class="An">Tobias Reber</span> and is subject to the GNU Public
    License. No Sun code was referenced.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">While <span class="Ux">FreeBSD</span> now has both NIS client and
    server capabilities, it does not yet have support for
    <a class="Xr">ypupdated(8)</a> or the <code class="Fn">yp_update</code>()
    function. Both of these require secure RPC, which
    <span class="Ux">FreeBSD</span> does not support yet either.</p>
<p class="Pp">The <a class="Xr">getservent(3)</a> and
    <a class="Xr">getprotoent(3)</a> functions do not yet have NIS support.
    Fortunately, these files do not need to be updated that often.</p>
<p class="Pp">Many more manual pages should be written, especially
    <a class="Xr">ypclnt(3)</a>. For the time being, seek out a local Sun
    machine and read the manuals for there.</p>
<p class="Pp">Neither Sun nor this author have found a clean way to handle the
    problems that occur when ypbind cannot find its server upon bootup.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">December 14, 2011</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>