Add section on NIS/YP

Submitted by:	unfurl

1 files changed, 513 insertions, 2 deletions

diff --git a/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
index 626b776df2..67abd9cd56 100644
--- a/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,7 +1,7 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.16 1999/11/07 01:54:42 chris Exp $
+     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.17 2000/01/06 02:39:25 kuriyama Exp $
 -->
 
 <chapter id="advanced-networking">
@@ -919,6 +919,518 @@ ISDN BRI line</programlisting>
 	use.</para>
     </sect2>
   </sect1>
+
+  <sect1 id="nis">
+    <title>NIS/YP</title>
+
+    <para><emphasis>Written by &a.unfurl;, 21 January 2000.</emphasis></para>
+
+    <sect2>
+      <title>What is it?</title>
+  
+      <para> 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.</para>
+    </sect2>
+  
+    <sect2>
+      <title>How does it work?</title>
+        
+      <para>There are 3 types of hosts in an NIS enviornment; master
+	servers, slave servers, and clients.  Servers act as a central
+	repository for host configuration information.  Master servers
+	hold the authoritatve copy of this information, while slave
+	servers mirror this information for redundancy.  Clients rely on
+	the servers to provide this information to them.</para>
+
+      <para>Information in many files can be shared in this manner.  The
+	<filename>master.passwd</filename>, <filename>group</filename>,
+	and <filename>hosts</filename> files are commonly shared via NIS.
+	Whenever a process on a client needs information that would
+	normally be found in these files locally, it makes a query to the
+	server it is bound to, to get this information.</para>
+    </sect2>
+    
+    <sect2>
+      <title>Using NIS/YP</title>
+  
+      <sect3>
+        <title>Planning</title>
+  
+        <para>If you are setting up a NIS scheme for the first time, it
+	  is a good idea to think through how you want to go about it.  No
+	  matter what the size of your network, there are a few decisions
+	  that need to be made.</para>
+  
+        <sect4>
+          <title>Choosing a NIS Domain Name</title>
+  
+          <para>This might not be the &ldquo;domainname&rdquo; that you
+	    are used to.  It is more accurately called the
+	    &ldquo;NIS domainname&rdquo;.  When a client broadcasts its
+	    requests for info, it includes the name of the NIS domain
+	    that it is part of.  This is how multiple servers on one
+	    network can tell which server should answer which request.
+	    Think of the NIS domainname as the name for a group of hosts
+	    that are related in someway way.</para>
+  
+	  <para>Some organizations choose to use their Internet domainname
+	    for their NIS domainname. This is not recommended as it can
+	    cause confusion when trying to debug network problems.  The
+	    NIS domainname should be unique within your network and it is
+	    helpful if it describes the group of machines it represents.
+	    For example, the Art department at Acme Inc. might be in the
+	    "acme-art" NIS domain.</para>
+        </sect4>
+  
+        <sect4>
+          <title>Physical Server Requirements</title>
+            
+	  <para>There are several things to keep in mind when chosing a
+	    machine to use as a NIS server.  One of the unfortunate things
+	    about NIS is the level of dependency the clients have on the
+	    server.  If a client cannot contact the server for its NIS
+	    domain, very often the machine becomes unusable.  The lack of
+	    user and group information causes most systems to temporarily
+	    freeze up.  With this in mind you should make sure to choose a
+	    machine that won't be prone to being rebooted regularly, or
+	    one that might be used for development.  The NIS server should
+	    ideally be a stand alone machine whose sole purpose in life is
+	    to be an NIS server.  If you have a network that is not very
+	    heavily used, it is acceptable to put the NIS server on a
+	    machine running other services, just keep in mind that if the
+	    NIS server becomes unavailable, it will affect
+	    <emphasis>all</emphasis> of your NIS clients adversely.</para>
+        </sect4>
+      </sect3>
+
+      <sect3>
+        <title>NIS Servers</title>
+
+	<para> The canonical copies of all NIS information are stored on
+	  a single machine called the NIS master server.  The databases
+	  used to store the information are called NIS maps.  In FreeBSD,
+	  these maps are stored in
+	  <filename>/var/yp/[domainname]</filename> where
+	  <filename>[domainname]</filename> 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.</para>
+
+	<para>NIS master and slave servers handle all NIS requests with
+	  the <command>ypserv</command> daemon.  <command>Ypserv</command>
+	  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.</para>
+
+        <sect4>
+	  <title>Setting up a NIS master server</title>
+
+	  <para>Setting up a master NIS server can be relativly straight
+	    forward, depending on your needs.  FreeBSD comes with a handy
+	    script called <command>ypinit</command> that makes the initial
+	    setup procedure very easy.  A few steps are needed ahead of
+	    time to make the setup process go smoothly.</para>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para>Make sure your NIS domainname is set, using the
+		<command>domainname</command> command.  You can run
+		<command>ypinit</command> for domains other than the one
+		your host is in but if <literal>domainname</literal> is
+		not set, now is a good time to do so.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>Make sure a copy of the
+	        <filename>master.passwd</filename> file is in
+		<filename>/var/yp</filename>.  This where NIS will get the
+		password entries it will share with it's clients.
+		<command>ypinit</command> runs with errors if this file is
+		not present.  You can either start a new
+		<filename>master.passwd</filename> or copy the existing
+		one from <filename>/etc/master.passwd</filename>.  If you
+		do the latter, make sure the permissions are set properly
+		to disallow world/group reading of the file.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>Start the <command>ypserv</command> daemon.
+		<command>ypinit</command> requires
+		<command>ypserv</command> to be running to answer some RPC
+		calls it makes.  In its basic configuration
+		<command>ypserv</command> does not need to be run with any
+		flags.</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>Once you've done the above steps, run
+	    <command>ypinit</command> with the <option>-m</option> flag.
+	    You might want to specify the domain you are building a master
+	    server for if it is different than what the
+	    <literal>domainname</literal> is set to.  In this example,
+	    <filename>test-domain</filename> will be our NIS
+	    domainname.</para>
+
+	  <screen>
+# ypinit -m test-domain
+Server Type: MASTER Domain: test-domain
+
+Creating an YP server will require that you answer a few questions.
+Questions will all be asked at the beginning of the procedure.
+
+Do you want this procedure to quit on non-fatal errors? [y/n: n]  n
+
+Ok, please remember to go back and redo manually whatever fails.
+If you don't, something might not work. 
+
+At this point, we have to construct a list of this domains YP servers.
+master.example.com is already known as master server.
+Please continue to add any slave servers, one per line. When you are
+done with the list, type a &lt;Control D&gt;.
+        master server   :  master.example.com
+        next host to add:  <userinput>^D</userinput>
+The current list of NIS servers looks like this:
+
+master.example.com
+
+Is this correct?  [y/n: y]  <userinput>y</userinput>
+Building /var/yp/test-domain/ypservers...
+Running /var/yp/Makefile...
+NIS Map update started on Fri Dec  3 16:54:12 PST 1999 for domain test-domain
+Updating hosts.byname...
+Creating new /var/yp/passwd file from /var/yp/master.passwd...
+Updating netid.byname...
+Updating hosts.byaddr...
+Updating networks.byaddr...
+Updating networks.byname...
+Updating protocols.bynumber...
+Updating protocols.byname...
+Updating rpc.byname...
+Updating rpc.bynumber...
+Updating services.byname...
+Updating group.byname...
+Updating group.bygid...
+Updating passwd.byname...
+Updating passwd.byuid...
+Updating master.passwd.byname...
+Updating master.passwd.byuid...
+NIS Map update completed.
+
+master.example.com has been setup as an YP master server without any errors.</screen>
+
+	  <para>There are a few crucial lines that need to be added to
+	    your <filename>/etc/rc.conf</filename> in order for the NIS
+	    server to start properly.  Make sure that these lines are
+	    included:</para>
+
+	  <programlisting>
+nis_server_enable="YES"
+nis_server_flags=""
+nis_yppasswdd_enable="YES"
+nis_yppasswdd_flags=""</programlisting>
+
+	  <para>You will most likely want to run
+	    <command>yppasswd</command> on the NIS server.  This allows
+	    users on NIS client machines to change their passwords and
+	    other user information remotely. </para>
+	</sect4>
+
+        <sect4>
+	  <title>Setting up a NIS slave server</title>
+
+	  <para>Setting up an NIS slave server is even more simple than
+	    setting up the master. Again the <command>ypinit</command>
+	    command helps out a great deal. As in the previous example
+	    we'll use &ldquo;test-domain&rdquo; as our target NIS
+	    domainname.</para>
+
+	  <screen>
+# ypinit -s master.example.com test-domain
+
+Server Type: SLAVE Domain: test-domain Master: master.example.com
+
+Creating an YP server will require that you answer a few questions.
+Questions will all be asked at the beginning of the procedure.
+
+Do you want this procedure to quit on non-fatal errors? [y/n: n]  <userinput>n</userinput>
+
+Ok, please remember to go back and redo manually whatever fails.
+If you don't, something might not work. 
+There will be no further questions. The remainder of the procedure
+should take a few minutes, to copy the databases from master.example.com.
+Transfering netgroup...
+ypxfr: Exiting: Map successfully transfered
+Transfering netgroup.byuser...
+ypxfr: Exiting: Map successfully transfered
+Transfering netgroup.byhost...
+ypxfr: Exiting: Map successfully transfered
+Transfering master.passwd.byuid...
+ypxfr: Exiting: Map successfully transfered
+Transfering passwd.byuid...
+ypxfr: Exiting: Map successfully transfered
+Transfering passwd.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering group.bygid...
+ypxfr: Exiting: Map successfully transfered
+Transfering group.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering services.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering rpc.bynumber...
+ypxfr: Exiting: Map successfully transfered
+Transfering rpc.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering protocols.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering master.passwd.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering networks.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering networks.byaddr...
+ypxfr: Exiting: Map successfully transfered
+Transfering netid.byname...
+ypxfr: Exiting: Map successfully transfered
+Transfering hosts.byaddr...
+ypxfr: Exiting: Map successfully transfered
+Transfering protocols.bynumber...
+ypxfr: Exiting: Map successfully transfered
+Transfering ypservers...
+ypxfr: Exiting: Map successfully transfered
+Transfering hosts.byname...
+ypxfr: Exiting: Map successfully transfered
+
+slave.example.com has been setup as an YP slave server without any errors. 
+Don't forget to update map ypservers on master.example.com.</screen>
+        
+	  <para>You should now have a directory called 
+	    <filename>/var/yp/test-domain</filename>.  Copies of the NIS
+	    master server's maps should be in this directory.  You will
+	    need to make sure that these stay updated.  The following
+	    entries on your slave servers should do the job:</para>
+        
+	  <programlisting>
+20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
+21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>
+
+	  <para>These two lines force the slave to update its maps with
+	    the ones on the master server, keeping them in sync.  This is
+	    not mandatory because the slave <literal>ypserv</literal>
+	    tries to keep its NIS maps up to date, but the password
+	    information is so vital to systems that depend on the server,
+	    that it is a good idea to force the updates.  This is more
+	    important on busy networks where map updates might not always
+	    complete.</para>
+	</sect4>
+      </sect3>
+
+      <sect3>
+        <title>NIS Clients</title>
+	
+	<para> An NIS client establishes what is called a binding to a
+	  particular NIS server using the
+	  <application>ypbind</application> daemon.
+	  <application>Ypbind</application> checks the system's default
+	  domain (as set by the <command>domainname</command> command),
+	  and begins broadcasting RPC requests on the local network.
+	  These requests specify the name of the domain for which
+	  <command>ypbind</command> 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
+	  <command>ypbind</command>,  which will record the server's
+	  address.  If there are several servers available (a master and
+	  several slaves, for example), <command>ypbind</command> 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.  <application>Ypbind</application> will
+	  occasionally &ldquo;ping&rdquo; 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,
+	  <command>ypbind</command> will mark the domain as unbound and
+	  begin broadcasting again in the hopes of locating another
+	  server.</para>
+
+	<sect4>
+	  <title>Setting up an NIS client</title>
+	  
+	  <para>Setting up a FreeBSD machine to be a NIS client is fairly
+	    straight forward.</para>
+	
+	  <itemizedlist>
+	    <listitem>
+	      <para>Set the host's NIS domainname with the
+		<command>domainname</command> command, or at boot time
+		with this entry in
+		<filename>/etc/rc.conf</filename>:</para>
+
+	      <programlisting>nisdomainname="test-domain"</programlisting>
+	    </listitem>
+
+	    <listitem>
+	      <para>To import all possible password entries from the NIS
+		server, add this line to your
+		<filename>/etc/master.passwd</filename> file, using
+		<command>vipw</command>:</para>
+
+	      <programlisting>+:::::::::</programlisting>
+
+	      <note>
+		<para>This line will afford anyone with a valid account in
+		  the NIS server's password maps an account.  There are
+		  many ways to configure your NIS client by changing this
+		  line.  For more detailed reading see O'Reilly's book on
+		  <literal>Managing NFS and NIS</literal>.</para>
+	      </note>
+	    </listitem>
+
+	    <listitem>
+	      <para>To import all possible group entries from the NIS
+		server, add this line to your
+		<filename>/etc/group</filename> file:</para>
+
+	      <programlisting>+:*::</programlisting>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>After completing these steps, you should be able to run
+	    <command>ypcat passwd</command> and see the NIS server's
+	    passwd map.</para>
+	</sect4>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>NIS Security</title>
+
+      <para>In general, any remote user can issue an RPC to ypserv and
+	retrieve the contents of your NIS maps, provided the remote user
+	knows your domainname.  To prevent such unauthorized transactions,
+	ypserv supports a feature called securenets which can be used to
+	restrict access to a given set of hosts.  At startup, ypserv will
+	attempt to load the securenets information from a file called
+	<filename>/var/yp/securenets</filename>.</para>
+	
+      <note>
+	<para>This path varies depending on the path specified with the
+	  <option>-p</option> option.  This file contains entries that
+	  consist of a network specification and a network mask separated
+	  by white space.  Lines starting with &ldquo;#&rdquo; are
+	  considered to be comments.  A sample securenets file might look
+	  like this:</para>
+      </note>
+
+      <programlisting>
+# allow connections from local host -- mandatory
+127.0.0.1     255.255.255.255
+# allow connections from any host
+# on the 192.168.128.0 network
+192.168.128.0 255.255.255.0
+# allow connections from any host
+# between 10.0.0.0 to 10.0.15.255
+10.0.0.0      255.255.240.0</programlisting>
+
+      <para>If ypserv receives a request from an address that matches one
+	of these rules, it will process the request normally.  If the
+	address fails to match a rule, the request will be ignored and a
+	warning message will be logged.  If the
+	<filename>/var/yp/securenets</filename> file does not exist,
+	ypserv will allow connections from any host.</para>
+
+      <para>The ypserv program also has support for Wietse Venema's
+	<application>tcpwrapper</application> package.  This allows the
+	administrator to use the tcpwrapper configuration files for access
+	control instead of <filename>/var/yp/securenets</filename>.</para>
+
+      <note>
+	<para>While both of these access control mechanisms provide some
+	  security, they, like the privileged port test, are both
+	  vulnerable to &ldquo;IP spoofing&rdquo; attacks.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>NIS v1 compatibility</title>
+
+      <para> FreeBSD's <application>ypserv</application> has some support
+	for serving NIS v1 clients.  FreeBSD's NIS implementation only
+	uses the NIS v2 protocol, however other implementations include
+	support for the v1 protocol for backwards compatibility with older
+	systems.  The <application>ypbind</application> daemons supplied
+	with these systems will try to establish a binding to an NIS v1
+	server even though they may never actually need it (and they may
+	persist in broadcasting in search of one even after they receive a
+	response from a v2 server).  Note that while support for normal
+	client calls is provided, this version of ypserv does not handle
+	v1 map transfer requests; consequently, it can not be used as a
+	master or slave in conjunction with older NIS servers that only
+	support the v1 protocol.  Fortunately, there probably are not any
+	such servers still in use today.</para>
+    </sect2>
+
+    <sect2>
+      <title>NIS servers that are also NIS clients</title>
+
+      <para> Care must be taken when running ypserv in a multi-server
+	domain where the server machines are also NIS clients.  It is
+	generally a good idea to force the servers to bind to themselves
+	rather than allowing them to broadcast bind requests and possibly
+	become bound to each other.  Strange failure modes can result if
+	one server goes down and others are dependent upon on it.
+	Eventually all the clients will time out and attempt to bind to
+	other servers, but the delay involved can be considerable and the
+	failure mode is still present since the servers might bind to each
+	other all over again.</para>
+
+      <para>You can force a host to bind to a particular server by running
+	<command>ypbind</command> with the <option>-S</option>
+	flag.</para>
+    </sect2>
+
+    <sect2>
+      <title>libscrypt vs. libdescrypt</title>
+
+      <para>One of the most common issues that people run into when trying
+	to implement NIS is crypt library compatibility.  If your NIS
+	server is using the DES crypt libraries, it will only support
+	clients that are using DES as well. To check which one your server
+	and clients are using look at the symlinks in
+	<filename>/usr/lib</filename>.  If the machine is configured to
+	use the DES libraries, it will look something like this:</para>
+
+      <screen>
+&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
+lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libdescrypt.a
+lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so
+lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2
+lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a
+-r--r--r--  1 root  wheel  13018 Nov  8 14:27 /usr/lib/libdescrypt.a
+lrwxr-xr-x  1 root  wheel     16 Nov  8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2
+-r--r--r--  1 root  wheel  12965 Nov  8 14:27 /usr/lib/libdescrypt.so.2
+-r--r--r--  1 root  wheel  14750 Nov  8 14:27 /usr/lib/libdescrypt_p.a</screen>
+
+      <para>If the machine is configured to use the standard FreeBSD MD5
+	crypt libraries they will look somethine like this:</para>
+
+      <screen>
+&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
+lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libscrypt.a
+lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so
+lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2
+lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a
+-r--r--r--  1 root  wheel   6194 Nov  8 14:27 /usr/lib/libscrypt.a
+lrwxr-xr-x  1 root  wheel     14 Nov  8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2
+-r--r--r--  1 root  wheel   7579 Nov  8 14:27 /usr/lib/libscrypt.so.2
+-r--r--r--  1 root  wheel   6684 Nov  8 14:27 /usr/lib/libscrypt_p.a</screen>
+	
+      <para>If you have trouble authenticating on an NIS client, this is a
+	pretty good place to start looking for possible problems.</para>
+    </sect2>
+  </sect1>
 </chapter>
 
 <!-- 
@@ -931,4 +1443,3 @@ ISDN BRI line</programlisting>
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
-