	Setting up a YP/NIS client under Rock Linux Mini-HOWTO
	======================================================

Copyleft 2000 Stefan Boresch for Rock Linux.  This document is
published in source under the terms of the GNU Free Documentation License,
version 1.1.

Author: Stefan Boresch (stefan@mdy.univie.ac.at)
Location of document: http://www.mdy.univie.ac.at/rocklinux/nis-rock.txt

Revision history: This is revision $Revision: 1.9 $
(dated $Date: 2000/06/03 08:19:58 $).

I. Scope and goals of this text; where to get further information:
==================================================================

This document describes how to add a Rocklinux machine as a NIS client
to an existing NIS network. I do not cover setting up a Rocklinux
machine as a NIS server (though my guess is that this would be as easy
or hard as setting up a NIS server on any platform). This Mini-HOWTO
is only concerned with NIS, not with NIS+, the more secure version of
the NIS protocol.

This is not an introduction to YP/NIS. For a thorough and good
explanation of the concepts, try to get hold of a copy of the old
O'Reilly book "Managing NFS and NIS". Unfortunately, the book is
completely outdated and often wrong with respect to actual commands,
configuration etc.

NIS and client side NIS+ for Linux is developed and maintained by
Thorsten Kukuk.  His homepage

    http://www.suse.de/~kukuk

contains lots of information, in particular the NIS-HOWTO at

    http://www.suse.de/~kukuk/nis-howto/index.html 

Make sure that you don't look at older versions by accident! (The
current version of the NIS-HOWTO is dated March 9, 1999.)  Another
important note: The NIS-HOWTO is much more general than this text; it
covers all situations from libc5 based systems to NIS+. For Rocklinux
relevant info it suffices to look at the NIS/glibc2.x sections of the
HOWTO; in particular, ignore the libc5 or the NYS stuff!

Since YP/NIS is often used in conjunction with the automounter, I have
added some information concerning autofs/automount and NIS in Appendix 2.

II. What you need and where to get it:
======================================

To turn your Rocklinux machine into a NIS client you need the
portmapper daemon, the ypbind daemon, some tools ("yp-tools"), and,
optionally, the autofs/automount stuff. The portmapper and autofs come
with Rocklinux. I have written extension packages for ypbind and
yp-tools; they just showed up in a recent development snapshot and
should be included in Rocklinux 1.3.10. (Their 'home' is
http://www.mdy.univie.ac.at/rocklinux/ypbind-mt.ext and
http://www.mdy.univie.ac.at/rocklinux/yp-tools.ext, respectively)

For those who want to do it themselves, the ypbind and yp-tools
packages can be downloaded from Thorsten's homepage (see above); however,
he recommends to look at

     ftp://ftp.kernel.org/pub/linux/utils/net/NIS/ 

to get the most up to date sources. For ypbind, make sure to get the
most up to date ypbind-mt ("multi-threaded") package. (I presume that the
old ypbind-3.3 daemon still works satisfactorily, but I doubt that
Thorsten is maintaining it any longer.)

All of the following was tried with ypbind-mt-1.6 and yp-tools-2.4 on
Rocklinux 1.3.9; these are also the versions currently used in the
extension packages.

III. Building and installing:
=============================

Just some short remarks if you build the two packages yourself.  They
build so easily, that Thorsten doesn't deem it necessary to give
specific install instructions. In fact,

./configure
make
make install

is all there is to it.  For yp-tools I recommend to use

./configure --disable-domainname

since you otherwise overwrite the Rocklinux domainname, ypdomainname
and nisdomainname commands (from the net-tools package) with those
from yp-tools.

IV. Setting it up:
==================

The following assumes that you have built and installed ypbind-mt and
yp-tools.

(1) You may want to make DES passwords your default method for new
passwords (Set

     MD5_CRYPT_ENAB no  

in /etc/login.defs; see also Appendix 1) In case you (or your users)
plan to use yppasswd (a utility to change passwords on a NIS server
from a client), you MUST do this (for a more detailed discussion see
Appendix 1)

(2) domainname must return the name of the NIS domain you want to
"bind" (connect) to, NOT the name of your DNS domain. If it doesn't
already, execute

     /bin/domainname <your_nis_domain_name>

To make the change permanent, edit /etc/DOMAINNAME. At present, the
Rocklinux install script seems to use this file to store the DNS name
of you subnet.

[Just to be on the safe side and to have addressed this controversial
topic: Historically, it was recommended for security reasons to use a
YP/NIS domainname that was different from your DNS domainname (this
recommendation is still in the official NIS-HOWTO).  If you (or your
site) follow(s) this practice and the YP/NIS domainname is set by
editing /etc/DOMAINNAME as just described, you may want to make sure
that your DNS domainname can be looked up / resolved through an entry
in /etc/hosts (assuming that you have

      order hosts,bind

in /etc/host.conf.) Otherwise, I noted that the system can get
confused; at some point the command dnsdomainname would report the
name of the YP/NIS domain, and my hostname --fqdn had turned into
<machine>.<my_nis_domain_name>.

Since, however, YP/NIS cannot be secured anyways on a public network, 
it is reasonable to assume that only machines behind a firewall, i.e.,
on a private network will use it.  In this case, there is no reason
not to use the same name for the YP/NIS and the DNS domainname]

(3) If it is not running already, start the portmapper
(/etc/init.d/portmap start) and add it with runlvedit to all your
multi-user modes (I have it activated in runlevels 2, 3 and 5)

(4a) Make sure that you have a /var/yp directory (ypbind from
ypbind-mt-1.6 creates it on startup; also the make install from
yp-tools creates one; nevertheless, it doesn't harm to check!)

(4b) Edit /etc/yp.conf. The extension package puts a self-documenting
example into /etc; those building ypbind themselves can find the
sample in ypbind-mt-1.6/etc/ .  The comments in the sample file are
equivalent to the man page. I found that the broadcast option doesn't
work.  (I don't know why; this is something which works flawlessly
with the old ypbind-3.3 of my Redhat 6.0 and 6.1 installations) My
/etc/yp.conf, therefore, looks as follows:

     ypserver <hostname1>
     ypserver <hostname2>

where <hostname1> and <hostname2> are the names of my NIS master and
slave servers.  In addition, I followed the advice in the comments of
the sample file and added <hostname1> and <hostname2> to the /etc/hosts
file.

(4c) Depending on your site policies, you may have to obtain
permission to "bind" to NIS server (i.e., change things on the server
side).  Remember to check this possibility again if for some reasons
you "can't get it to work"... (A usual/reasonable site policy is to
allow all machines from the local subnet to bind, so you should not
have trouble even if your machine has an IP address not used before.)

(4d) Test things "manually": Execute

     /usr/sbin/ypbind

which should put itself in the background without error or diagnostic
messages. A ps should show four /usr/sbin/ypbind processes running.  Type

     ypwhich

and you should get the name of your server. If the command hangs or
returns an error, recheck all steps up till now and try again. (It seems
that you need a kill(all) -9 to stop ypbind!) If this still doesn't work,
look at the troubleshooting hints in the NIS-HOWTO and at Thorsten's
homepage, then let me know what I should add to this document ;-).

If everything worked so far, the command 

     ypcat passwd

should show you the passwd file stored on the NIS server. NOTE that
your system will NOT YET USE this information!!! 

Two things remain to be done: Get your machine to actually use the yp/nis
informations, and create a startup script for ypbind.

(5) The /etc/nsswitch.conf

To make your system use NIS information, you have to edit the file
/etc/nsswitch.conf.  I used a slightly different approach from the one
suggested in the NIS-HOWTO -- here's my file:

#
# ROCK: /etc/nsswitch.conf
#
# Example configuration of GNU Name Service Switch functionality.
#
 
passwd:         db files nis     # <== nis added
group:          db files nis     # <== nis added
shadow:         db files
 
hosts:          files dns
networks:       files dns
 
protocols:      db files
services:       db files
ethers:         db files
rpc:            db files
 
netgroup:       db files 

When you compare this to the file coming with Rocklinux 1.3.9, you see
that only two entries are changed: passwd and group now also have the
nis entry. Of course, if you are into NIS, you will want to add and/or
change many, many more entries; however, this is a NIS configuration
issue and not specific to Rocklinux. 

To test whether your system noticed the change execute

       getent passwd

You should see a list of all passwd entries: your local (shadow) entries
first; then the NIS passwd entries from your server.

Since we used "nis" instead of "compat" there was no need to edit
/etc/passwd and /etc/group as described in the NIS-HOWTO. (On the
downside, you can't do any of the fine-tuning described in the
NIS-HOWTO (Sect. 6.6) either...)

The nsswitch file allows you to control a lot of other services (I
don't really use them..).  If you want hostname lookups via NIS (I
don't), you probably need to edit /etc/host.conf as well.

(6) Startup script

Thorsten provides a sample startup script in ./ypbind-mt-1.6/etc
called ypbind.init. This is a good place to start, but the script is
intended for use in a Suse or Redhat environment.  This is the no frills
version I use (the ypbind-mt.ext package has placed it into /etc/init.d)

#!/bin/sh
#
#
# ROCK Linux: /etc/init.d/ypbind
#
# Desc: The ypbind Daemon
#
 
# description: This is a daemon which runs on NIS/YP clients and binds
#              them to a NIS domain. It must be running for systems
#              based on glibc to work as NIS clients, but it should not
#              be enabled on systems which are not using NIS.
 
 
# See how we were called.
case "$1" in
  start)
        echo -n "Binding to the NIS domain... "
        /usr/sbin/ypbind
        echo
        ;;
  stop)
        echo -n "Shutting down NIS services: "
        /usr/bin/killall -q -9 ypbind
        # Remove binding files, if ypbind "forgets" it
        rm -f /var/yp/binding/*
        echo
        ;;
  restart)
        $0 stop
        $0 start
        ;;
  *)
        echo "*** Usage: ypbind {start|stop|restart}"
        exit 1
esac
 
exit 0 

When you integrate this with runlvedit into your suite of init
scripts, make sure that it is run AFTER the portmapper is started; in
addition, double check that domainname is set at this point (in vanilla
Rocklinux this is done in /etc/init.d/boot, so you should not have to
worry about this.)

(7) You are done :-) However, you probably want to use autofs in
combination with NIS (how else are your users going to see their
home directories?)  Take a brief look at Appendix 2.

Appendix 1: MD5 vs. DES passwords and YP/NIS
============================================

As you probably know, the traditional DES based crypt(3) for password
encryption is more and more replaced by an MD5 based algorithm. Redhat
6.0 and 6.1, which I have in production use, and FreeBSD, which I tried
a bit, put lots of emphasis on compatibility issues in mixed
environments, in particular NIS setups. At least to me, this was
worrying. In addition, FreeBSD needs to install an additional library
if DES crypt(3) support is wanted/needed.

However, for Rocklinux, as a glibc 2.x based system, this is a
non-issue. From my tests, DES and MD5 passwords can coexist in the
same passwd (shadow) file; similarly, local passwords can be MD5 based
and NIS passwords DES based. The default behavior which algorithm to
use is controlled by the line

     MD5_CRYPT_ENAB no  # this is the default (use DES), yes (as in
                        # Rocklinux 1.3.9 activates MD5)

in /etc/login.defs. Due to the described flexibility of the glibc, there
is, in principle, no reason to turn off the use of MD5 passwords when
setting up the machine as a NIS client.

Nevertheless, I made DES passwords the default scheme on the client
machine, and I recommend doing so for two reasons.  (1) According to
Thorsten Kukuk (see his homepage), the yp-server is still more or less
expecting 8-letter passwords; only the latest server version (1.3.11)
can go beyond this limit, but this feature is untested.  My server is
older, so I would almost certainly run into problems if I used the MD5
algorithm. One could circumvent this by not using/allowing yppasswd
from clients that use MD5 passwords by default, but why cripple the
convenience of a NIS setup? (2) If you upgraded your NIS server and MD5
passwords did indeed work, there might still be "legacy machines" which
don't support them.  (In our network, for example, there are a few
venerable Indys running IRIX 5.3.)

Appendix 2: autofs 
==================

From the beginning NIS and autofs (automounting of directories) went
hand in hand. To auto-magically mount a user's home directory as
needed, one needs autofs in addition to the NIS client
tools. Rocklinux up to 1.3.9 came with autofs v.3, which had been
broken in combination with the development kernels. Starting with
Rocklinux 1.3.10, autofs4 will be used.  To be on the safe side, here
is a quick description of installing autofs4 yourself.

Your kernel needs to support the autofs daemon; with the 2.3.99
kernels and higher you want autofs4 support enabled.  As the userland
tools, you need to get autofs-4.0.0pre6 (or later) from your favorite
kernel mirror (look in pub/linux/daemons/autofs/testing-v4), compile
and install it (I encountered no problems). The one remaining problem
is that many autofs init scripts (including the one that came with
Rocklinux 1.3.9) start the automounter (/usr/sbin/automount) in such a
manner that the combination of a local /etc/auto.master file and
YP/NIS maps for the individual mountpoints (e.g., the users' home
directories) is not allowed for.  My local quick and dirty fix was to
apply the following patch to /etc/init.d/autofs (of Rocklinux 1.3.9):

--- autofs      Fri Apr 14 16:44:32 2000
+++ autofs~     Tue Apr 11 04:38:19 2000
@@ -34,7 +34,7 @@
                 elif [ -f $map ]; then
                     echo "automount $dir file $map $options $localoptions"
                 else
-                    echo "automount $dir yp `basename $map` $options $localoptions"
+                    echo "automount $dir `basename $map` $options $localoptions"
                 fi
             fi
         done      

No guarantee that this doesn't break other things.  People needing
fancier setups might want to look at the autofs init scripts coming
with Redhat >= 6.0.
