CD Actual 13/CDA13.ISO/DOC/HOWTO/OTHER_FO/SGML/NIS_HOWT.GZ/NIS-HOWTO.sgml

SGML Document | 1996-02-11 | 26.5 KB | 779 lines

<!doctype linuxdoc system>

<article>

<title>The Linux NIS(YP)/NIS+/NYS HOWTO
<author>Andrea Dell'Amico, Mitchum DSouza, Erwin Embsen, Peter Eriksson
<date>v0.5, 24 January 1995

<toc>

<sect>Glossary of Terms

<p>
In this document a lot of acronyms are used. Here are the most
important acronyms and a brief explanation:

<descrip>
<tag/DBM/DataBase Management, a library of functions which
    maintain key-content pairs in a data base.

<tag/DLL/Dynamically Linked Library, a library linked to an
    executable program at run-time.

<tag/domainname/A name "key" that is used by NIS clients to be
    able to locate a suitable NIS server that serves that
    domainname key. Please note that this does not necessarily
    have anything at all to do with the DNS "domain"
    (machine name) of the machine(s).

<tag/FTP/File Transfer Protocol, a protocol used to transfer
    files between two computers.

<tag/libnsl/Name services library, a library of name service calls
    (getpwnam, getservbyname, etc...) on SVR4 Unixes.

<tag/libsocket/Socket services library, a library for the socket
    service calls (socket, bind, listen, etc...) on SVR4 Unixes.

<tag/NIS/Network Information Service, a service that provides
    information, that has to be known throughout the network,
    to all machines on the network. There is support for NIS
    in Linux's standard libc library, which in the following text
    is referred to as "traditional NIS".

<tag/NIS+/Network Information Service (Plus :-), essentially NIS on
    steroids. NIS+ is designed by Sun Microsystems Inc. as a
    replacement for NIS with better security and better handling
    of _large_ installations.

<tag/NYS/This is the name of a project and stands for NIS+, YP and Switch
    and is managed by Peter Eriksson <[e-mail]>. It contains
    among other things a complete reimplementation of the NIS (=YP) code
    that uses the Name Services Switch functionality of the NYS library.

<tag/RPC/Remote Procedure Call. RPC routines allow C programs to
    make procedure calls on other machines across the network.
    When people talk about RPC they most often mean the SunRPC
    variant.

<tag/YP/Yellow Pages(tm), a registered trademark in the UK of
    British Telecom plc.

<tag/TCP-IP/Transmission Control Protocol/Internet Protocol. It's a
    data communication protocol often used on Unix machines.
</descrip>


<sect1>Some General Information

<p>
The next three lines are quoted from the Sun(tm) System & Network
Administration Manual:

<tscreen><verb>
    "NIS was formerly known as Sun Yellow Pages (YP) but
     the name Yellow Pages(tm) is a registered trademark
     in the United Kingdom of British Telecom plc and may
     not be used without permission."
</verb></tscreen>

NIS stands for Network Information Service. It's purpose is to
provide information, that has to be known throughout the network,
to all machines on the network. Information likely to be
distributed by NIS is:

<itemize>
<item>login names/passwords/home directories (/etc/passwd)
<item>group information (/etc/group)
</itemize>

So, for example, if your password entry is recorded in the NIS
passwd database, you will be able to login on all machines on the
net which have the NIS client programs running.

Sun is a trademark of Sun Microsystems, Inc. licensed to
SunSoft, Inc.


<sect>Introduction

<p>
More and more, Linux machines are installed as part of a network of
computers. To simplify network administration, most networks (mostly
Sun-based networks) run the Network Information Service. Linux machines
can take full advantage of existing NIS service or provide NIS service
themselves. It can also (with the NYS library) act as a limited NIS+
client.

This document tries to answer questions about setting up NIS(YP) on
your Linux machine. It does not talk about how to set up NIS+. Don't
forget to read section 5.1, The RPC Portmapper.


<sect1>New versions of this document

<p>
New versions of this document will be posted periodically (about every
month) to the newsgroups comp.os.linux.announce and comp.os.linux.misc.
The document is archived on a number of Linux FTP sites, including
<tt>sunsite.unc.edu</tt> in <tt>/pub/Linux/docs/HOWTO</tt>.


<sect1>Disclaimer

<p>
Although this document has been put together to the best of our
knowledge it may, and probably does contain errors. Please read any
README files that are bundled with any of the various pieces of
software described in this document for more detailed and accurate
information. We will attempt to keep this document as error free as
possible.


<sect1>Feedback

<p>
If you have any comments, questions or suggestions please email
them to <tt>Erwin Embsen <[e-mail]></tt>. Definitely contact
him if you find errors or obvious omissions.


<sect1>Acknowledgements

<p>
We would like to thank all the people who have contributed (directly
or indirectly) to this document. In alphabetical order:

<tscreen><verb>
Andrea Dell'Amico <[e-mail]>
Mitchum DSouza    <[e-mail]>
Erwin Embsen      <[e-mail]>
Byron A Jeff      <[e-mail]>
Peter Eriksson    <[e-mail]>
</verb></tscreen>

Theo de Raadt <[e-mail]> is responsible for the original
yp-clients code.  Swen Thuemmler <[e-mail]> ported the
yp-clients code to Linux and also ported the yp-routines in libc
(again based on Theo's work).


<sect>NIS or NIS+ ?

<p>
The choice between NIS and NIS+ is easy - use NIS if you don't have to
use NIS+ or have severe security needs. NIS+ is _much_ more problematic
to administer (it's pretty easy to handle on the client side, but the
server side is horrible). Another problem is that the support for NIS+
under Linux is still under developement - one major thing it still
lacks is support for data encryption/authentication which is _the_
major thing why anyone would want to use NIS+...


<sect1>Traditional NIS or the NYS library ?

<p>
The choice between Traditional NIS or the NIS code in the NYS library
is a choice between laziness and maturity vs. flexibility and love of
adventure.

The "traditional NIS" code is in the standard C library and has been
around longer and sometimes suffers from it's age and slight
inflexibility.

The NIS code in the NYS library, on the other hand requires you either
to recompile and relink all your programs to the libnsl library, or
recompile the libc library to include the libnsl code into the libc
library (or maybe you can go get a precompiled version of libc from
someone who has already done it).

Another difference is that the traditional NIS code has some support
for NIS Netgroups, which the NYS code doesn't (yet). On the other hand
the NYS code allows you to handle Shadow Passwords in a transparent
way.


<sect>How it works

<p>
Within a network there must be at least one machine acting as a NIS
server. You can have multiple NIS servers, each serving different NIS
"domains" - or you can have cooperating NIS servers, where one is said
to be the master NIS server, and all the other are so-called slave NIS
servers (for a certain NIS "domain", that is!) - or you can have a mix
of them...

Slave servers only have copies of the NIS databases and receive these
copies from the master NIS server whenever changes are made to the
master's databases.  Depending on the number of machines in your
network and the reliability of your network, you might decide to
install one or more slave servers.  Whenever a NIS server goes down or
is too slow in responding to requests, a NIS client connected to that
server will try to find one that is up or quicker.

NIS databases are in so-called DBM format, derived from ASCII
databases.  For example, the files <tt>/etc/passwd</tt> and
<tt>/etc/group</tt> can be directly converted to DBM format using
ASCII-to-DBM translation software ("dbload", it's included with the
server software). The master NIS server should have both, the ASCII
databases and the DBM databases.

Slave servers  will be notified of any change to the NIS maps, (via the
"yppush" program), and automatically retrieve the necessary changes in
order to synchronize their databases. NIS clients does not need to do
this since they always talks to the NIS server to read the information
stored in it's DBM databases.

The author of the YP clients for linux has informed us that the newest
ypbind (from yp-clients.tar.gz) is able to get the server from a
configuration file - thus no need to broadcast (which is insecure - due
to the fact that anyone may install a NIS server and answer the
broadcast queries...)



<sect>What do you need to set up NIS?

<sect1>The RPC Portmapper

<p>
To run any of the software mentioned below you will need to run the
program /usr/sbin/rpc.portmap. Some Linux distributions already have
the code in /etc/rc.d/rc.inet2 to start up this daemon.  All you have
to do is comment it out and reboot your Linux machine to activate it.

The RPC portmapper (portmap(8c)) is a server that converts RPC program
numbers into TCP/IP (or UDP/IP) protocol port numbers. It must be
running in order to make RPC calls (which is what the NIS client
software does) to RPC servers (like a NIS server) on that machine.
When an RPC server is started, it will tell portmap what port number it
is listening to, and what RPC program numbers it is prepared to serve.
When a client wishes to make an RPC call to a given program number, it
will first contact portmap on the server machine to determine the port
number where RPC packets should be sent.

Normally, standard RPC servers are started by inetd(8C), so portmap
must be started before inetd is invoked.


<sect1>Determine whether you are a Server, Slave or Client.

<p>
To answer this question you have to consider two cases:

<enum>
<item>Your machine is going to be part of a network with existing NIS servers
<item>You do not have any NIS servers in the network yet
</enum>

In the first case, you only need the client programs (ypbind, ypwhich,
ypcat, yppoll, ypmatch). The most important program is ypbind. This
program must be running at all times, that is, it should always appear
in the list of processes. It's a so-called daemon process and needs to
be started from the system's startup file (eg. /etc/rc.local).
As soon as ypbind is running, your system has become a NIS client.

In the second case, if you don't have NIS servers, then you will also
need a NIS server program (usually called ypserv). Section 6 describes
how to set up a NIS server on your Linux machine using the "ypserv"
implementation by Peter Eriksson (<tt><[e-mail]></tt>). Note
that this implementation does NOT support the master-slave concept
talked about in section 3. Using this software, all your NIS servers
will be master servers. There is also another free NIS server
available, called "yps", written by Tobias Reber in Germany which does
support the master-slave concept, but has other limitations.


<sect1>The Software

<p>
The system library "/usr/lib/libc.a" (version 4.4.2 and better) or the
shared library "/usr/lib/libc.sa" and its related DLL contain all
necessary system calls to succesfully compile the NIS client and server
software.

Some people reported that NIS only works with "/usr/lib/libc.a" version
4.5.21 and better so if you want to play it safe don't user older
libc's.  The NIS client software can be obtained from:

<tscreen><verb>
  Site                   Directory                        File Name

  ftp.uni-paderborn.de   /pcsoft2/linux/local/yp          yp-clients.tar.gz
  ftp.funet.fi           /pub/OS/Linux/BETA/NYS/clients   yp-clients.tar.gz
  ftp.lysator.liu.se     /pub/NYS/clients                 yp-clients.tar.gz
  sunsite.unc.edu        /pub/Linux/system/Network/admin  yp-clients.tar.gz
</verb></tscreen>

Once you obtained the software, please follow the instructions which
come with the software.


<sect1>Setting up a NIS Client using Traditional NIS

<p>
Assuming you have succesfully compiled the software you are now ready
to install the software. A suitable place for the ypbind daemon is
the directory /usr/sbin.

You'll need to do this as root of course. The other binaries (ypwhich,
ypcat, yppoll, ypmatch) should go in a directory accessible by all
users, for example /usr/etc or /usr/local/bin.  It might be a good idea
to test ypbind before incorporating it in /etc/rc.d/rc.inet2.

To test ypbind do the following:

<itemize>
<item>Make sure you have your domain name set. If it is not set then
    issue the command:

    <tscreen><verb>
        /bin/domainname-yp nis.domain
    </verb></tscreen>

    where <tt>nis.domain</tt> should be some string, _NOT_ normally
    associated with the domain name of your machine! The reason for
    this is that it makes it a little harder for external crackers
    to retreive the password database from your NIS servers. If you
    don't know what the NIS domain name is on your network, ask
    your system/network administrator.

<item>Start up "/usr/sbin/rpc.portmap" if it is not already running.

<item>Create the directory "/var/yp" if it does not exist.

<item>Start up "/usr/sbin/ypbind"

<item>Use the command "rpcinfo -p localhost" to check if ypbind
      was able to register its service with the portmapper. The
      rpcinfo should produce something like:

      <tscreen><verb>
       program vers proto   port
        100000    2   tcp    111  portmapper
        100000    2   udp    111  portmapper
        100007    2   udp    637  ypbind
        100007    2   tcp    639  ypbind
        300019    1   udp    660
      </verb></tscreen>

<item>You may also run "rpcinfo -u localhost ypbind". This command
      should produce something like:

      <tscreen><verb>
        program 100007 version 2 ready and waiting
      </verb></tscreen>

</itemize>

Finally, do not forget that for host lookups you must set (or add)
"nis" to the lookup order line in your /etc/host.conf file. Please read
the manpage "resolv+.8" for more details.

At this point you should be able to use NIS client programs like ypcat,
etc...  For example, "ypcat passwd" will give you the entire NIS
password database.

IMPORTANT: If you skipped the test procedure then make sure you have set
the domain name, and created the directory:

<tscreen><verb>
    /var/yp
</verb></tscreen>

This directory MUST exist for ypbind to start up succesfully.

If the test worked you may now want to change the files /etc/rc.d/rc.M
and /etc/rc.d/rc.inet2 on your system so that ypbind will be started up
at boot time and your system will act as a NIS client. Edit the file
/etc/rc.d/rc.M and look for the commands which set the domain name.
Change the domain name into the name of your domain. Also, edit the
file /etc/rc.d/rc.inet2, comment out the lines which start up the
rpc.portmap daemon, and add the following lines just after the place
where rpc.portmap is started:

<tscreen><verb>
    #
    # Start the ypbind daemon
    #
    if [ -f ${NET}/ypbind -a -d /var/yp ]; then
        echo -n " ypbind"
        ${NET}/ypbind
    fi
</verb></tscreen>

Unlike Sun's implementation of NIS you do not need to edit /etc/passwd
and /etc/group to take advantage of NIS. Sun's implementation needs a
line "+:*:0:0:::" in /etc/passwd and a line "+:*:0:" in /etc/group to
tell NIS to search the NIS password and group databases.

IMPORTANT: Note that the command finger will report "no such user"
messages if you do not add the line "+:*:0:0:::" to /etc/passwd.
Putting the line "+:*:0:0:::" back in /etc/passwd fixes finger.

Well, that's it. Reboot the machine and watch the boot messages to see
if ypbind is actually started.

IMPORTANT: Note that the netgroup  feature is implemented starting
from libc 4.5.26. Netgroups allow access control for every machine and
every user in the NIS domain, and they require an entry like:

<tscreen><verb>
    +@this_machine_users
</verb></tscreen>

in /etc/passwd. But if you have a version of libc erlier than 4.5.26,
every  user  in  the  NIS password database can access your linux
machine if you run "ypbind".


<sect>What you need to set up NYS?

<sect1>Determine whether you are a Server, Slave or Client.

<p>
To answer this question you have to consider two cases:

<itemize>
<item>Your machine is going to be part of a network with
      existing NIS servers

<item>You do not have any NIS servers in the network yet
</itemize>

In the first case you have two choices:

<itemize>
<item>Either you relink all client and daemon programs with the
    NYS library <tt>libnsl.so</tt> (or statically link them with
    <tt>libnsl.a</tt>). This means adding the line:

    <tscreen><verb>
        LIBS=-lnsl
    </verb></tscreen>

    to your Makefile signifing you want to link the Network
    Services Library. Basically all network deamons and the
    "login" program need to be recompiled.

<item>Or you can recompile the standard C library <tt>libc</tt> to include
    the NYS client library functions into the normal libc library,
    and then relink all statically linked programs (the dynamically
    linked programs automatically get the new version of libc).
    See section 6.5 below for more information about this option.
</itemize>

Similarly like in the case of traditional NIS, if you don't have NIS
servers, then you will also need a NIS server program (usually called
ypserv) and you have to designate one of the machines in your network
as a master NIS server. Again, you might want to set up at least one
slave server as well.


<sect1>The Software

<p>
You need to retrieve and compile the NYS services library libnsl.so.
If you don't have the DLL tools installed you may retrieve a
precompiled shared, static and stub library from the same site
mentioned below. Note, however, that the precompiled version may be
(and probably is) older than the latest source code release.

The NYS library (source and precompiled version)  can be obtained from:

<tscreen><verb>
    Site                Directory                      File Name

    ftp.lysator.liu.se  /pub/NYS/libs                  nys-0.27.4.tar.gz
    ftp.lysator.liu.se  /pub/NYS/binaries/lib          libnsl.so.1.0.a26

    ftp.funet.fi        /pub/OS/Linux/BETA/NYS/libs    nys-0.27.4.tar.gz
    ftp.funet.fi        /pub/OS/Linux/BETA/NYS/lib     libnsl.so.1.0.a26
</verb></tscreen>

Precompiled "login" and "su" programs may also be fetched from

<tscreen><verb>
    Site                Directory                      File Name

    ftp.lysator.liu.se  /pub/NYS/binaries/bin          login
    ftp.lysator.liu.se  /pub/NYS/binaries/bin          su

    ftp.funet.fi        /pub/OS/Linux/BETA/NYS/bin     login
    ftp.funet.fi        /pub/OS/Linux/BETA/NYS/bin     su
</verb></tscreen>

Similarly, example configuration files may be retrieved from

<tscreen><verb>
    Site                Directory                      File Name

    ftp.lysator.liu.se  /pub/NYS/binaries/etc          *conf
    ftp.funet.fi        /pub/OS/Linux/BETA/NYS/etc     *conf
</verb></tscreen>

For compilation of the nsl library, please follow the instructions
which come with the software. If you wish to compile the shared DLL
library you must have the DLL tools installed in the standard place
(/usr/dll). The DLL tools (the package tools-2.11.tar.gz or later) can
be obtained from many sites.


<sect1>Setting up a NYS Client using NYS

<p>
Unlike traditional NIS, there is no setting up required for a NIS
client. All that is required is that the NIS configuration file
(/etc/yp.conf) points to the correct server(s) for its information.
Also, the Name Services Switch configuration file (/etc/nsswitch.conf)
must be correctly set up.

Please refer to the examples provided with the source code.


<sect1>The nsswitch.conf File

<p>
The Network Services switch file /etc/nsswitch.conf determines the
order of lookups performed when a certain piece of information is
requested, just like the /etc/host.conf file which determines the way
host lookups are performed. Again, look at at the example file provided
in the source distribution. For example, the line

<tscreen><verb>
    hosts: files nis dns
</verb></tscreen>

specifies that host lookup functions should first look in the local
/etc/hosts file, followed by a NIS lookup and finally thru the domain
name service (/etc/resolv.conf and named), at which point if no match
is found an error is returned.


<sect1>Making your binaries NYS aware

<p>
Instead of relinking each binary with the NYS library (libnsl.so), a
cleaner solution has been achieved by providing the user with the
ability to build a NYS aware libc. This means all you need to do is
recompile a new libc and replace your existing /lib/libc.so.x.y.z for
all (non-static compiled) programs to be NYS aware.

This merge also gives you the advantage over the traditional NIS
implementation in the linux libc in that it allows transparent shadow
passwords support (via the /etc/nisswitch.conf file).

Follow the simple steps below to rebuild a NYS aware libc.

<itemize>
<item>Make sure you have the latest DLL tools installed. Refer to
      the the GCC-FAQ for more info on where to get this.

<item>Get the latest libc sources. (again see GCC-FAQ)

<item>Get the latest nys sources from

      <tscreen><verb>
          ftp.lysator.liu.se:/pub/NYS/libs
      </verb></tscreen>

      and extract it under this libc-linux source directory.
      The current NYS distribution is "nys-0.27.4.tar.gz".

<item>Do the ./configure as before and first answer "n" to the
      question

      <tscreen><verb>
          Values correct (y/n) [y] ?
      </verb></tscreen>

      Then go thru all the other questions and the last question
      will now be

      <tscreen><verb>
          Build a NYS libc from nys-0.27 (y default) ?
      </verb></tscreen>

      answer "y" to this.

<item>Then issue the command

      <tscreen><verb>
          % make
      </verb></tscreen>

</itemize>

The library generated after compilation is named something like

<tscreen><verb>
    libc.so.4.5.26
</verb></tscreen>

and placed under the directory jump/libc-nys. To install this library
our advise would be copying it to /lib with a name lexiographically
greater than the version number it currently has. Just appending the
letter "a" should do the trick.  For example:

<tscreen><verb>
    % cp jump/libc-nys/libc.so.4.5.26 /lib/libc.so.4.5.26a
</verb></tscreen>

Alternatively, append "nys" to it so you can quickly identify it.
Now run the command

<tscreen><verb>
    % ldconfig
</verb></tscreen>

which will reset your cache to use the new library. The dynamic linker
strategy may be examined with the command "ldconfig -p".

That's basically it. All your programs should now be NYS aware. Please
note that usually the program "login" is compiled static and thus
cannot access the new NYS functions from the NYS aware libc. You must
either recompile "login" without the -static flag, or else statically
link it to the libnsl.a library.


<sect>Setting up a NIS Server

<sect1>The Server Program ypserv

<p>
This document only describes how to set up the "ypserv" NIS server.
The "yps" server setup is similar, _but_ not exactly the same so
beware if you try to apply these instructions to "yps"!

The NIS server software can be found on:

<tscreen><verb>
    Site                Directory                          File Name

    ftp.lysator.liu.se  /pub/NYS/servers                   ypserv-0.11.tar.gz
    ftp.funet.fi        /pub/OS/Linux/BETA/NYS/servers     ypserv-0.11.tar.gz
    mcsun.eu.net        /os/linux/BETA/NYS/servers         ypserv-0.11.tar.gz
    ftp.univie.ac.at    /unix/system/linux/funet/BETA/NYS/servers
                                                           ypserv-0.11.tar.gz
</verb></tscreen>

The server setup is the same for both traditional NIS and NYS.

Compile the software to generate the "ypserv", "dbcat" and "dbload"
programs.  Firstly, determine what files you require to be available
via NIS and then add or remove the appropriate entries to the
ypMakefile. Install the file <tt>ypMakefile</tt> into <tt>/var/yp</tt>
as the file <tt>Makefile</tt>.

Now build the DBM files by typing:

<tscreen><verb>
    % cd /var/yp; make
</verb></tscreen>

Make sure the portmapper (rpc.portmap) is running, and start the
server "ypserv". The command


<tscreen><verb>
    % rpcinfo -u localhost ypserv
</verb></tscreen>

should output something like

<tscreen><verb>
    program 100004 version 2 ready and waiting
</verb></tscreen>

That's it, your server is up and running.


<sect1>The Program yppasswdd

<p>
Whenever users change their passwords, the NIS password database and
probably other NIS databases, which depend on the NIS password
database, should be updated.  The program "yppasswdd" is a server that
handles password changes and makes sure that the NIS information will
be updated accordingly. The software for "yppasswdd" can be found on:

<tscreen><verb>
    Site                   Directory                      File Name

    ftp.lysator.liu.se    /pub/NYS                        yppasswdd-0.5.tar.gz
    ftp.funet.fi          /pub/OS/Linux/BETA/NYS/servers  yppasswdd-0.5.tar.gz
</verb></tscreen>

Once you obtained the software, please follow the instructions which
come with the software.


<sect>Verifying the NIS/NYS Installation

<p>
If everything is fine (as it should be), you should be able to verify
your installation with a few simple commands. Assuming, for example,
your passwd file is being supplied by NIS, the command

<tscreen><verb>
    % ypcat passwd
</verb></tscreen>

should give you the contents of your NIS passwd file. The command

<tscreen><verb>
    % ypmatch userid passwd
</verb></tscreen>

(where userid is the login name of an arbitrary user) should give you
the user's entry in the NIS passwd file. The "ypcat" and "ypmatch"
programs should be included with your distribution of traditional
NIS or NYS.


<sect>Common Problems and Troubleshooting NIS

<p>
Here are some common problems reported by various users:

<enum>
<item>The libraries for 4.5.19 are broken. NIS won't work with it.

<item>If you upgrade the libraries from 4.5.19 to 4.5.24 then the
       su command breaks. You need to get the su command from the
       slackware 1.2.0 distribution. Incidentally that's where you
       can get the updated libraries.

<item>You could run into trouble with NIS and DNS on the same machine.
       My DNS server occasionally will not bring up NIS. Haven't yet
       tracked down why.

<item>When a NIS server goes down and comes up again ypbind starts
       complaining with messages like:

    <verb>
         yp_match: clnt_call:
                     RPC: Unable to receive; errno = Connection refused
    </verb>

       and logins are refused for those who are registered in the
       NIS database. Try to login as root and if you succeed, then kill
       ypbind and start it up again.
</enum>


<sect>Frequently Asked Questions

<p>
Most of your questions should be answered by now. If there are still
questions unanswered you might want to post a message to

<tscreen><verb>
    comp.os.linux.help
</verb></tscreen>

or contact one of the authors of this HOWTO.

</article>