This is an archive of past FreeBSD releases; it's part of the FreeBSD Documentation Archive.
Written by Bill Swingle <unfurl@FreeBSD.org>, 21 January 2000.
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.
There are 3 types of hosts in an NIS environment; master servers, slave servers, and clients. Servers act as a central repository for host configuration information. Master servers hold the authoritative copy of this information, while slave servers mirror this information for redundancy. Clients rely on the servers to provide this information to them.
Information in many files can be shared in this manner. The master.passwd, group, and hosts 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.
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.
This might not be the ``domainname'' that you are used to. It is more accurately called the ``NIS domainname''. 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.
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.
There are several things to keep in mind when choosing 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 all of your NIS clients adversely.
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 /var/yp/[domainname] where [domainname] 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.
NIS master and slave servers handle all NIS requests with the ypserv daemon. Ypserv 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.
Setting up a master NIS server can be relatively straight forward, depending on your needs. FreeBSD comes with a handy script called ypinit that makes the initial setup procedure very easy. A few steps are needed ahead of time to make the setup process go smoothly.
Make sure your NIS domainname is set, using the domainname command. You can run ypinit for domains other than the one your host is in but if domainname is not set, now is a good time to do so.
Make sure a copy of the master.passwd file is in /var/yp. This where NIS will get the password entries it will share with it's clients. ypinit runs with errors if this file is not present. You can either start a new master.passwd or copy the existing one from /etc/master.passwd. If you do the latter, make sure the permissions are set properly to disallow world/group reading of the file.
Start the ypserv daemon. ypinit requires ypserv to be running to answer some RPC calls it makes. In its basic configuration ypserv does not need to be run with any flags.
Once you've done the above steps, run ypinit with the -m flag. You might want to specify the domain you are building a master server for if it is different than what the domainname is set to. In this example, test-domain will be our NIS domainname.
# 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 <Control D>.
master server : master.example.com
next host to add: ^D
The current list of NIS servers looks like this:
master.example.com
Is this correct? [y/n: y] y
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.
There are a few crucial lines that need to be added to your /etc/rc.conf in order for the NIS server to start properly. Make sure that these lines are included:
nis_server_enable="YES"
nis_server_flags=""
nis_yppasswdd_enable="YES"
nis_yppasswdd_flags=""
You will most likely want to run yppasswd on the NIS server. This allows users on NIS client machines to change their passwords and other user information remotely.
Setting up an NIS slave server is even more simple than setting up the master. Again the ypinit command helps out a great deal. As in the previous example we'll use ``test-domain'' as our target NIS domainname.
# 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] n
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.
Transferring netgroup...
ypxfr: Exiting: Map successfully transferred
Transferring netgroup.byuser...
ypxfr: Exiting: Map successfully transferred
Transferring netgroup.byhost...
ypxfr: Exiting: Map successfully transferred
Transferring master.passwd.byuid...
ypxfr: Exiting: Map successfully transferred
Transferring passwd.byuid...
ypxfr: Exiting: Map successfully transferred
Transferring passwd.byname...
ypxfr: Exiting: Map successfully transferred
Transferring group.bygid...
ypxfr: Exiting: Map successfully transferred
Transferring group.byname...
ypxfr: Exiting: Map successfully transferred
Transferring services.byname...
ypxfr: Exiting: Map successfully transferred
Transferring rpc.bynumber...
ypxfr: Exiting: Map successfully transferred
Transferring rpc.byname...
ypxfr: Exiting: Map successfully transferred
Transferring protocols.byname...
ypxfr: Exiting: Map successfully transferred
Transferring master.passwd.byname...
ypxfr: Exiting: Map successfully transferred
Transferring networks.byname...
ypxfr: Exiting: Map successfully transferred
Transferring networks.byaddr...
ypxfr: Exiting: Map successfully transferred
Transferring netid.byname...
ypxfr: Exiting: Map successfully transferred
Transferring hosts.byaddr...
ypxfr: Exiting: Map successfully transferred
Transferring protocols.bynumber...
ypxfr: Exiting: Map successfully transferred
Transferring ypservers...
ypxfr: Exiting: Map successfully transferred
Transferring hosts.byname...
ypxfr: Exiting: Map successfully transferred
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.
You should now have a directory called /var/yp/test-domain. 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 /etc/crontab entries on your slave servers should do the job:
20 * * * * root /usr/libexec/ypxfr passwd.byname
21 * * * * root /usr/libexec/ypxfr passwd.byuid
These two lines force the slave to sync its maps with the maps on the master server. Although this is not mandatory, because the master server tries to make sure any changes to it's NIS maps are communicated to it's slaves, 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.
An NIS client establishes what is called a binding to a particular NIS server using the ypbind daemon. Ypbind checks the system's default domain (as set by the domainname command), and begins broadcasting RPC requests on the local network. These requests specify the name of the domain for which ypbind 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 ypbind, which will record the server's address. If there are several servers available (a master and several slaves, for example), ypbind 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. Ypbind will occasionally ``ping'' 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, ypbind will mark the domain as unbound and begin broadcasting again in the hopes of locating another server.
Setting up a FreeBSD machine to be a NIS client is fairly straight forward.
Set the host's NIS domainname with the domainname command, or at boot time with this entry in /etc/rc.conf:
nisdomainname="test-domain"
To import all possible password entries from the NIS server, add this line to your /etc/master.passwd file, using vipw:
+:::::::::
Note: 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 Managing NFS and NIS.
To import all possible group entries from the NIS server, add this line to your /etc/group file:
+:*::
After completing these steps, you should be able to run ypcat passwd and see the NIS server's passwd map.
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 /var/yp/securenets.
Note: This path varies depending on the path specified with the -p option. This file contains entries that consist of a network specification and a network mask separated by white space. Lines starting with ``#'' are considered to be comments. A sample securenets file might look like this:
# 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
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 /var/yp/securenets file does not exist, ypserv will allow connections from any host.
The ypserv program also has support for Wietse Venema's tcpwrapper package. This allows the administrator to use the tcpwrapper configuration files for access control instead of /var/yp/securenets.
Note: While both of these access control mechanisms provide some security, they, like the privileged port test, are both vulnerable to ``IP spoofing'' attacks.
FreeBSD's ypserv 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 ypbind 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.
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.
You can force a host to bind to a particular server by running ypbind with the -S flag.
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 /usr/lib. If the machine is configured to use the DES libraries, it will look something like this:
% ls -l /usr/lib/*crypt*
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
If the machine is configured to use the standard FreeBSD MD5 crypt libraries they will look something like this:
% ls -l /usr/lib/*crypt*
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
If you have trouble authenticating on an NIS client, this is a pretty good place to start looking for possible problems.
For questions about FreeBSD, e-mail
<questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.