April 18, 1996

1.0: About the Naming Service Utilities
  1.1: What is NSCD?
  1.2: What is FNS?
2.0: Debugging the Naming Service Utilities
  2.1: Debugging NSCD
  2.2: Debugging FNS
3.0: Common How Tos
  3.1: How to Use nscd
  3.2: How to Tune nscd
  3.3: How to Set Up FNS
  3.5: How to Set Up Printer Services Without Installing FNS
4.0: Some Frequently Asked Questions
5.0: Patches
  5.1: nscd Patches
  5.2: FNS Patches
6.0: Known Bugs & RFEs
  6.1: Bugs
7.0: References
  7.1: Important Man Pages
  7.2: Sunsolve Documents
  7.3: Sun Educational Services
  7.4: Solaris Documentation
  7.5: Third Party Documentation
  7.6: RFCs
8.0: Supportability
9.0: Additional Support

1.0 About the Naming Services Utilities

 1.0: About the Naming Services Utilities

========================================

This Tip Sheet documents a wide variety of information concerning the
naming service utilities, nscd and FNS, as they are implemented in the
Solaris operating system. It is intended as both an introduction to
these utilities and as a guide to the most common problems. There are
a few other references for these utilities, which are noted in section
7.0.

Beginning with Solaris 2.5, two new packages related to naming
services were introduced: nscd and FNS.

 1.1: What is NSCD?

------------------

NSCD, or the naming services caching daemon, is a performance
improvement tool. It is a daemon that temporarily caches passwd, group
and host information originating from any of the naming services (NIS,
NIS+, DNS or files). Usually, programs are forced to go out to the
network for each new naming service lookup. By allowing nscd to cache
naming service lookup results, you get improved performance, as some
of these network lookups are no longer necessary.

NSCD can be tuned depending on the exact needs of your network, as is
explained in Section 3.2.

 1.2: What is FNS?

-----------------

FNS, or the Federated Naming Services, is a naming interface built on
top of NIS+. The interface is an extension of XFN, the X/Open
standard. For programming purposes, the XFN interface is documented in
/usr/include/xfn/xfn.h.

You can think of FNS as a sort of index of naming services. It
provides a uniform interface by which you can access lots of different
things such as: email addresses, file systems, printers, calendars and
hosts names. Here are some examples of FNS composite names:

  org/test.com./fs                                Test.com's File System
  org/test.com./service/printer                   Test.com's Printer
  org/test.com./hosts/machine1                    Test.com's machine1
  org/test.com./user/joe/fs                       Joe's File System
  org/test.com./user/joe/service/calendar         Joe's Calendar
  org/test.com./user/joe/service/printer          Joe's Printer

FNS can also be connected up with global naming services, like DNS and
X.500. This is done with the '...' directive, which says to go to a
global naming service. Using this, you can access other FNS domains,
beyond your own. A few examples:

  .../test.com/org/test.com./fs
  .../test.com/org/test.com./service/printer

For this to work right, the DNS (or X.25) domain that you are trying
to access must have had specific records set up for FNS. Chapter 7 of
the _Federated Naming Service Guide_ gives an excellent example of how
to do this.

Note that the name appearing right after ... (test.com) is the name of
a DNS domain, while the name appearing right after org (test.com.)  is
the name of a NIS+ domain.

Finally, it is also notable that FNS gives you shorthand names that
allow you to more easily access certain records. For example:

  myorgunit/service/calendar              default calendar for current org
  thishost/service/calendar               default calendar for current host

When FNS is originally set up, as described in Section 3.3, contexts
are created for the organization (that is your NIS+ domain) and all
of the users and hosts in that organization. Setting up specific
references to calendars, printers, global file systems, and other
tasks will require specific administration.

2.0 Debugging the Naming Service Utilities

 2.1: Debugging NSCD

-------------------

To turn on extra debugging in nscd, edit the /etc/nscd.conf file and
increase the debug level:

  debug-level value

debug-level can go as high as 10. When this option is turned on, nscd
will run in the foreground rather than as a daemon. You should see
information on what is getting cached and what items are getting
timed out, and this can provide insight into nscd inconsistencies or
related errors.

 2.2: Debugging FNS

------------------

At its heart, FNS is a set of NIS+ tables and thus you should use the
mechanisms described in the NIS+ Tip Sheet for debugging. A few
examples follow.

List all FNS objects:

  # nisls ctx_dir.domain.

[Where domain is your domain name]

Look at the permissions on the FNS host context:

  # niscat -o fns_host.ctx_dir

You'll also want to consult chapter 6 of the _Federated Naming
Services Guide_ for a very specific list of errors and possible
solutions.

3.0 Common How Tos

 3.1: How to Use nscd

--------------------

On a brand new 2.5 system, nscd should be started immediately from
the /etc/rc2.d/S76nscd boot file, provided that the files
/etc/nscd.conf and /usr/sbin/nscd both exist. This should be the
standard configuration.

You don't need to do anything special to use it. You should
automatically see slight improvement in your passwd, group and host
lookups because common references are getting cached.

The only caveat is that nscd will not cache a map if you are using
NIS+ and the NIS+ map is not readable by unauthenticated users. This
is done to preserve the security of your NIS+ maps. If you find that
your passwd, group and host maps all fit this criteria, you might simply
wish to disable nscd.

To disable nscd, simply rename it:

  # mv /usr/sbin/nscd /usr/sbin/nscd.DISABLED

 3.2: How to Tune nscd

---------------------

Tuning nscd is very well documented in the nscd.conf man page. The
primary thing that you should consider is how frequently your files
and maps are updated.

If any individual file (passwd, group, hosts) is never updated, you
can turn off file checking for that file, i.e.:

  check-files                   passwd          no

This is only a big win if you access the files via NFS.

If your NIS, NIS+ or DNS maps are updated infrequently, you might wish
to tune up the positive TTL, which lists how long nscd should hold on
to affirmative answers (i.e., a successful lookup of user joe) and
maybe the negative TTL, which lists how long nscd should hold on to
negative answers (i.e. a "user unknown" response of user fred). Both of
these variables are given in seconds. The following example tunes the
positive TTL up to 12 hours, which can be useful if you only push out
NIS maps twice a day:

  positive-time-to-live         passwd          43200

Simply be aware that while tuning up these values will increase
efficiency, since nscd will have to query the network less, tuning up
the positive TTL will slow down modifications of the passwd, group and
hosts maps, while tuning up the negative TTL will slow down additions
to the passwd, group and hosts map.

 3.3: How to Set Up FNS

----------------------

Before you can set up FNS, you must have NIS+ installed and the FNS
administrator must have proper NIS+ admin credentials. It is highly
suggested that you create the FNS maps on a separate machine from the
one that is already serving your NIS+ maps. You should also make sure
that you have plenty of disk and swap space to support FNS on this
server.

The instructions in chapter 6 of the _Federated Naming Service Guide_
are more than sufficient to set up FNS. From your root server, you
must:

Set NIS_GROUP equal to the NIS+ group that will administer FNS:

  # set NIS_GROUP=fns_admin.domain export NIS_GROUP

[In this and all following examples, "domain" should be set equal to
your domain name.]

Run nismkdir to create the directory for your FNS tables and
correlate it with your FNS server:

  # nismkdir -m fns_server ctx_dir.domain.

[where "fns_server" is set equal to the server you have decided to run
FNS on.]

Create the standard FNS setup with the fncreate command:

  # fncreate -t org org/domain./

This will create context for all passwords and hosts in your NIS+ table.

Finally, sync your records:

  # /usr/lib/nis/nisping -C ctx_dir.domain.

Again, note that chapter 6 of the _Federated Naming Services Guide_
gives information on this and many more complex FNS setups.

 3.4: How to Create FNS records

------------------------------

After you've created your FNS domain, you've set up the context for
all your passwd and host entries. However, you haven't really taken
full advantage of the possibilities that FNS allows. The instructions below
explain
how to set up some additional records in FNS. It is meant to give you
an understanding of what you can do in FNS, but you should examine the
_Federated Naming Services Guide_ for more complete information.

To create a printer:

  # fncreate_printer  thisorgunit printer bsdaddr=printhost,printer

Note that you must substitute the name of your printer for "printer"
and the name of your printserver for "printhost".

To link a user to a printer:

  # fnbind thisorgunit/service/printer user/joe/service/printer

To create an alternate name for a user in FNS:

  # fnbind user/joe user/Joe.Smith

To link a calendar:

  # fnbind -r thisorgunit/service/calendar onc_calendar onc_cal_str root@server

Note that this order is slightly different from previous ones due to
the -r option. This example makes it so that people get the
'root@server' calendar when they look for the calendar designation for
your orgunit (i.e. NIS+ domain).

To link a FS for a user:

  # fncreate_fs user/joe/fs server:/export/home/joe

To create links for a global filesystem:

  # fncreate_fs org/test.com./fs/papers server:/disk17/papers
  # fncreate_fs org/test.com./fs/games server:/disk97/papers

 3.5: How to Set Up Printer Services Without Installing FNS

----------------------------------------------------------

If you wish to do printing via FNS, without worrying about all of the
intricacies of a full FNS setup, you can do a minimal setup. Note that
you must be using NIS+ for this to work, as with all FNS setups.

First, create a minimal FNS setup:

  # fncreate -o -t org org//

Then, create a context for each printer you wish to use:

  # fncreate_printer  thisorgunit printer bsdaddr=printhost,printer

Note that you must substitute the name of your printer for "printer"
and the name of your printserver for "printhost".

 4.0: Some Frequently Asked Questions

====================================

Q: What can I do with FNS?

A: As is noted above, FNS can provide you with a sort of index of
naming services. This can be extremely useful for looking up specific
records without have to remember minutia like what specific machine
that record is on. A few examples of FNS usage follow.

Bundled programs like calendar manager can get certain input, like a
user name (joe) and then build a FNS composite name out of it
(thisorgunit/user/joe/service/calendar). Thus, while this is totally
transparent to the user, the program will be taking advantage of the
FNS database. As FNS becomes more mature, it is likely that more
programs will have the ability to do this type of FNS name composition
and usage.

Programs written at your site can do specific lookups to FNS. This
interface is described fully in chapters 10-12 of the _Federated
Naming Services Guide_.

NFS, when combined with a "/xfn -xfn" automount entry, makes special
use of the FNS FS objects, to create a transparent file system. You
need to use fncreate_fs to set up the structure of this filesystem
(see 3.4), but once this is done, you have a single filesystem that
appears the same on every machine in your FNS organization. You can
reach these FNS filesystems with paths like the following:

  /xfn/users/joe/fs
  /xfn/org/test.com./fs/games
  /xfn/org/test.com./fs/papers

5.0 Patches

 5.1: nscd Patches

-----------------

103279-02 SunOS 5.5: nscd breaks password shadowing with NIS+
103280-02 SunOS 5.5_x86: nscd breaks password shadowing with NIS+

  Fix a bug that could cause nscd to inadvertently compromise shadow
  passwd security.

103187-04 SunOS 5.5: libc fixes
103188-02 SunOS 5.5_x86: libc fixes

  Among other things, fixes a minor error that could cause nscd to
  react badly if another application closed a FD that it was using.

 5.2: FNS Patches

----------------

There are currently no patches for the Federated Naming Service.

6.0 Known Bugs And RFEs

 6.1: Bugs

---------

1224744   nscd hides changes when /etc/resolv.conf is modified

  In the original 2.5 release of nscd, it did not correctly update the
  cache in the case of resolv.conf changing. This will be corrected in
  versions of nscd after 2.5.

7.0 References

 7.1: Important Man Pages

------------------------

fncreate
fnlist
fnlookup
fns
fns_initial_context
fns_policies
nis+
nscd
nscd.conf
xfn

 7.2: Sunsolve Documents

-----------------------

None.

 7.3: Sun Educational Services

-----------------------------

None.

 7.4: Solaris Documentation

--------------------------

_Federated Naming Services Guide_

 7.5: Third Party Documentation

------------------------------

None.

 7.6: RFCs

---------

None.

 8.0: Supportability

===================

SunService is not responsible for the initial configuration of your
FNS, nor for answering basic questions about how to put such a FNS
configuration together.

We can help resolve problems where FNS or nscd are not behaving
correctly, but in such cases the contact must be a system
administrator who has a good understanding of the way that nscd or FNS
work.

 9.0: Additional Support

=======================

For initial configuration, or FNS setup, please contact your local
SunService office for possible consulting offerings. Sun's Customer
Relations organization can put you in touch with your local
SunIntegration or Sales office. You can reach Customer Relations at
800-821-4643.

SunWeb Home SunWeb Search SunSolve Home Simple Search

Sun Proprietary/Confidential: Internal Use Only
Feedback to SunSolve Team