Chapter 7. Unified Name Service
Prev |  | Next

## Chapter 7. Unified Name Service

The Unified Name Service (UNS) is a name service layer provided with the IRIX operating system to translate and simplify name service requests. Name servers provide network services that enable clients to name resources or objects in the network and share this information with other network objects.

In the past, each new name service was implemented in an application using code in the standard C library. As a new name service was added to a network, configuration files representing information about system resources and accounts were added along with a number of library routines. When the concept of distributed name space administration was conceived, the process became more complex.

To simplify this, the unification layer provided by UNS was developed. All IRIX networked programs can use UNS to implement other name services.

The following subjects are discussed in this chapter:

- “About Unified Name Service ”

- “Overview of UNS Operations”

- “How UNS Works With NIS”

- “How UNS Works With BIND”

- “How UNS Works With NFS”

- “How UNS Works With LDAP”

- “Setting Up a UNS Configuration”

- “UNS Protocol Libraries”

- “Troubleshooting nsd”

## About Unified Name Service

UNS translates the results of name service requests from a number of different protocols into a single file-based protocol. A protocol is a set of rules, data formats and conventions that determine how data is transferred between network components. A library is the implementation of a protocol. Among several standard protocols that the IRIX operating system provides are the protocols DNS and NIS which deal with name service requests. Given multiple protocols, a single overriding protocol simplifies name service requests.

Unified Name Service has three major components:

- the name service daemon `nsd`

- specific application programming interface (API) routines in the C library

- several protocol libraries

The name service API is left unchanged from previous releases of the IRIX operating system to maintain library-level compatibility. No applications should need to recompile to take advantage of UNS components.

## Overview of UNS Operations

At system start up, the daemon `nsd` takes two actions: it initiates a filesystem namespace rooted at `/ns`. It then reads the UNS configuration file `/etc/nsswitch.conf` which specifies the resolve order of each of the supported tables, and protocols.

Figure 7-1. Action of the nsd Daemon With Name Service Protocols

The daemon `nsd` has no awareness of protocols itself, it simply sets up a front-end interface to the different name services and runs between them. If a request comes from NIS to resolve a password into a system name, `nsd` passes the request to the appropriate library based on the resolution of the request pathname. A request issued from NIS `/etc/passwd,` for example, is passed to `/ns/.local/.nis/passwd`, so that in effect UNS acts as an alias.

When the `nsd` daemon is called, it reads the configuration file `nsswitch.conf,` which contains a list of protocols and tables. A table is made up of searchable rows and columns. The hosts table consisting of `hosts.byname` and`hosts.byaddr,` effectively allows a search either by hostname or by host address.

The file system namespace started by `nsd` is rooted at `/ns` and is used by the underlying interfaces to retrieve name system data. This is a dynamic file system, timed out after 30 seconds, so that if you issue the command `ls` from `/ns` you may not see the files.

The results of any name search are held in the `.local` cache file in the `/ns` namespace. The `.local` file is the local user's view of the namespace. When a file is accessed in the `/ns` directory, an entry is added to a cache file under `/var/ns/cache`, creating what is in effect a shadow file. There is a cache file for each of the tables supported by the name service daemon. For example, if a call comes to NIS, the NIS database files on the local host are searched first. This means network traffic is reduced and searches are swifter.

Figure 7-2. Partial View of Dynamic UNS Files

The format of these files mimics the format of the historic configuration files that they replace. Using`passwd` as an example, each file under the directories `/ns/*/passwd.byname` is made up of lines separated by newline characters, of the format:

    login:password:uid:gid:gecos:directory:shell

Since the file `/etc/nsswitch.conf` specifies the resolve order for each of the supported tables, including the host table, the hostresorder line in `/etc/resolv.conf` is ignored.

The following table shows the name services that have been supported as part of the operating system since IRIX 6.2 with their client and server services, together with the binding that links the client and the server:

Table 7-1. Protocols With Historically Supported Services

Protocol | Client | Binding (Linking) | Server
--- | --- | --- | ---
DNS | Resolver Library | resolv.conf | named
NIS |  | ypbind (now nsd) | ypserv (now nsd)
Files | getx by y() getx by ent() |  |

Protocols and tables provided with the initial UNS release are client-side DNS; client-side NIS; Files; MDBM, the NIS database files; NDBM; Berkeley DB; Nisserv, the replacement for `ypserv;` and LDAP, the lightweight alternative for X500. The operation of these libraries is explained in “UNS Protocol Libraries”.

The following sections explain various aspects of UNS:

- “How UNS Works With NIS”

- “About UNS and the NIS Database ”

- “How UNS Works With BIND”

- “How UNS Works With NFS”

- “How UNS Works With LDAP”.

### How UNS Works With NIS

The NIS network lookup service provides a centralized database of information about the network to systems participating in the service. Of the number of information sources provided to network applications, typically the default lookup order is NIS first, DNS (BIND) second, then the appropriate local files.

Unified Name Service (UNS) does not change the fundamental operation of NIS, although how the server daemon `ypserv,` and the binding daemon `ypbind`, work are changed.

Historically, the NIS daemon`ypserv` is the database server responsible for answering client inquiries and updating the database. `ypserv` runs only on NIS server machines with a complete NIS database. The NIS binder daemon `ypbind`, would run on all NIS clients and was responsible for remembering information necessary for communicating with `ypserv`. A system can function as a server and a client simultaneously, and can therefore be running both `ypbind` and `ypserv`.

Figure 7-3. Historical Operation of NIS Name Lookups

In earlier versions of the IRIX operating system, NIS daemons are started by the master network script `/etc/init.d/network`, when the NIS daemon flags are set “on.” Beginning with the IRIX 6.5 operating system, the UNS file `/etc/nsswitch.conf` controls the resolve order of the NIS client, and so overrides the previous actions of `ypserv`.

Figure 7-4. Operation of the nsd Daemon With NIS

The`nsd` daemon reads the UNS configuration file`/etc/nsswitch.conf`, the default copy of which contains a line of this format:

    hosts:nis dns files

In this instance, the NIS hosts table is referred to before the DNS or local files. The`nsd` daemon then implements the NIS protocol in a shared library stored in the directory `/var/ns/lib`. This is explained further in “UNS Protocol Libraries”.

Further changes to NIS server utilities involve `ypinit`, `ypmake`, and `make.script,` which are now wrappers around a perl script called `mdbm_parse`. This script does the actual parsing, instead of a makefile and binaries. This does not change visible system behavior.

For details of the NIS environment, refer to NIS Administration Guide. For more about the activity of the `nsd` daemon, see “UNS Configuration File”.

### About UNS and the NIS Database

The NIS database is composed of a group of files known as maps. Maps are composed of keys and values. For example, in the map called `hosts.byname`, the keys are the names of the individual systems.

Maps are created from input files, (usually standard ASCII files) and made into files in database record format. Historically these backend database files, called`dbm`, had output files with`.dir` and`.pag` extensions, each pair being a map. Files in DBM format are restricted both in the number of entries, and the relative size of each entry.

Database backend files in the UNS environment are called`mdbm`, and output files often have`.m` extensions. The database itself needs only one file so there are not separate `.dir` and `.pag` files. Files in MDBM format handle millions of entries; each entry can be up to 64 KB long (4 KB by default). This simpler single-key file format leads to faster response.

With UNS, the new location for the NIS backend data storage is `/var/ns/domains`. Each table is still stored in multiple files, one per key. Keys that are looked up are cached into local hash files found in `/var/ns/cache/`.

### How UNS Works With BIND

The Berkeley Internet Name Domain (BIND) implements the Internet Domain Name Service (DNS) for the IRIX operating system. All IRIX network programs can use BIND to replace the original host table to look up information in the `/etc/hosts` file.

BIND server configurations run the `named` server daemon, which is started automatically during station startup if the configuration flag`named` is set “on.” See the `chkconfig(1M)` reference page for more details.

The resolve order on a typical BIND server is determined through the `resolv.conf` file, an example of which follows:

    noodle% cat resolv.conf
    search example1.com example2.com
    #hostresorder nis bind local # now defunct under UNS
    nameserver 192.99.89.54 #bindle
    nameserver 127.0.0.1

The basic BIND client normally accesses data from the name servers specified in its own `resolv.conf` file. It does not run the domain server `named`.

Starting with the IRIX 6.5 operating system, the UNS file `/etc/nsswitch.conf` controls the resolve order of the BIND client and overrides the resolve order of `resolv.conf`. These lines from the default `/etc/nsswitch.conf` show the hosts table reference:

    spanker% cat nsswitch.conf
    .....
    group: files nis
    hosts: nis dns files

UNS provides DNS client capabilities.

In the UNS environment, the`nsd` daemon implements the DNS protocol in a shared library stored in the directory `/var/ns/lib`. This is explained further in “UNS Protocol Libraries”. For further details on DNS, see Chapter 6, “BIND Name Server”.

### How UNS Works With NFS

NFS is an application layer service that can be used on a network running the User Datagram Protocol (UDP) or Transmission Control Protocol (TCP). With NFS a single copy of a file such as `/usr/local` can be accessible by all systems on the network. Remote files appear to be “local” to each user's system. The NFS server daemon `nfsd` runs on the server and accepts RPC calls from clients. NFS caches file attributes on the client side, known as the front-end filesystem, so that certain operations do not have to go all the way to the server.

When a file operation like`ls -l` is requested, the data inside the file is not touched. The information delivered is about the file's attributes (for example, size, time of access, and owner), and those attributes are valid for some 3 seconds. Client changes are made on the locally cached copy, and if the file's attributes remain unchanged for about 60 seconds, they are flushed from the cache and written back to the server. The server is known as the back-end filesystem and contains the definitive archived copy of the data.

Starting with the IRIX 6.5 operating system, the UNS environment provides the local files, which are stored in `/ns/.local`, the local user's view of the namespace. As with the other name services, when a file is accessed in the `/ns/.local` directory, a cache entry is added into a cache file under `/var/ns/cache`, creating what is in effect a shadow file. The `nsd` daemon presents the appearance of a mounted filesystem. There is actually no remote NFS server.

Details of the SGI implementation of the Sun Microsystems Open Network Computing Plus (ONC+) distributed services, previously referred ldap-ns.conf(4) to as Network File System (NFS), are explained in ONC3/NFS Administrators Guide.

### How UNS Works With LDAP

The Lightweight Directory Access Protocol (LDAP) is a simplified version of the X.500 Directory Access Protocol implemented on TCP/IP. One of LDAP's special attractions is that it allows you to define the database schema, specifying how information will be organized and retrieved from the database. Of course, an LDAP client must know of this organization in order to use the database, and this is done with the LDAP client configuration file, `/etc/ldap-ns.conf`.

At system startup, the `nsd` daemon reads the configuration file `/etc/nsswitch.conf` which specifies the resolve order of each of the supported tables and protocols. If one of those listed is LDAP, the LDAP client configuration file `/etc/ldap-ns.conf` is read.

In this file, each domain using the LDAP protocol library has a section specifying which LDAP servers to use, the parameters to search on each server, how to map each name service request to an LDAP search filter, and how to transform the response into a file format. With this flexibility you can use any schema for storing the configuration information. For technical information about LDAP, refer to RFC 1777. For details of the configuration file, see the ldap-ns.conf(4) reference page.

## Namespace Format

The namespace is of the format `/ns/domain/table/protocol/key`. The protocol directory is often left out. This results in all the protocols being searched in the order given in `/etc/nsswitch.conf`. The `.local` domain represents the local system view of the namespace. A special file`.all` gives the full enumeration of the data for a table if supported by a protocol. Files and their purposes are enumerated in Table 7-2:

Table 7-2. UNS Files and Their Purposes

File Name | Purpose
--- | ---
/ns/.local/passwd.byname/root | Root entry in local passwd using whatever protocols are supported.
/ns/.local/passwd.byname/.nis/root | Root entry in local passwd using only the NIS protocol.
/ns/.local/passwd.byname/.nis/.all | All password entries in the NIS passwd table for the local domain.
/ns/engr/passwd.byname/root | Root entry is the engr domain passwd map using any available protocol.
/ns/sgi.com/hosts.byname/sgi | Finds the host address for the machine sgi in the sgi.com domain. (The local host must be a server for sgi.com.)
/ns/.local/hosts.byname/sgi.sgi.com | Finds the host address for the machine sgi.sgi.com in the hosts map. (Data may be anywhere.)

For example, to look up the password entry for the root user in the domain engr.example1.com, you would simply give this command:

    # cat /ns/engr.example1.com/passwd.byname/root

The directory `.local` is created for the local domain so that the root password entry for the local domain can always be found in the file `/ns/.local/passwd.byname/root`.

The file`.all` in each table directory enumerates the entire password table. If you need to list every password entry for the local domain using all the library routines listed in`nsswitch.conf,` give this command:

    # cat /ns/.local/passwd.byname/.all

This gives you a large concatenation of every user in the local domain.

Finally, a special directory .library (for example `.nis`) is created under each table directory for each of the libraries listed for that table in `nsswitch.conf`.

The `ns_lookup()` library routine always opens files under the `.local` domain namespace mounted on `/ns` to satisfy the requests from name service lookups, so this should not be changed.

## UNS Configuration File

The sole UNS configuration file is `/etc/nsswitch.conf`, and is made up of lines of the format:

    map: library library library

For example:

    hosts: nis dns files

This file specifies the libraries and the order in which they are to be used. If any path element does not exist, name service library routines are called by the `nsd` daemon in progressive order until the element is found.

The system administrator need only verify that`nsd` is running—see “Troubleshooting nsd”. Normally the `nsd` daemon is activated at system startup time from `/etc/init.d/network` if the configuration flag is set “on” (see`chkconfig(1M)` ). If the nsd configuration flag is not set “on”, the only name service supported is local files. The`nsd` daemon converts each name service request into a pathname.

When it is started, `nsd` creates the dynamic file system namespace rooted at `/ns` which is used by the underlying interfaces to retrieve name system data.

The format of these files mimics the format of the historic configuration files that they replace. Using`passwd` as an example, each file under the directories `/ns/*/passwd.byname` is made up of lines separated by new-line characters, of this format:

    login:password:uid:gid:gecos:directory:shell

Since the file `/etc/nsswitch.conf` specifies the resolve order for each of the supported tables, including the host table, the hostresorder line in `/etc/resolv.conf` is ignored.

There is one `nsswitch.conf` file for each “domain” supported by this daemon. Every machine has a local domain, `.local` which has the configuration file in `/etc/nsswitch.conf.` Server machines support multiple domains and have a configuration file in `/var/ns/domains/domainname/nsswitch.conf` for each domainname.

## Setting Up a UNS Configuration

The UNS configuration is automatic with the installation of the IRIX operating system. The `nsd` daemon runs and uses the `/etc/nsswitch.conf` file to determine the configuration and protocols of the name services being requested. There is one `nsswitch.conf` file for each “domain” supported by this daemon. Every machine has a local domain`.local` which has the configuration file in `/etc/nsswitch.conf.` Server machines support multiple domains and have a configuration file in `/var/ns/domains/domainname/nsswitch.conf` for each domainname.

However, additional steps are needed to set up a system as a NIS Server:

1. Run`ypinit` to setup a system as a NIS server. It copies a default `nsswitch.conf` file into place and parses the system configuration files into the `mdbm` hash files. Refer to the `ypinit(1M)` reference pages for details.

2. Run `ypmake` to rebuild and distribute the NIS database. Refer to the `ypmake(1M)` reference page for details.

3. Run`mdbm_dump` to view the current contents of an mdbm hash database.

## UNS Protocol Libraries

The protocol libraries provided with the initial UNS release are:

- Files—see “Files Library ”.

- NIS, the Network Information Service—See “NIS Protocol Library”.

- DNS, the Domain Name Service—See “DNS Protocol Library”.

- MDBM, local hash files—See “MDBM Protocol Library”.

- NDBM, an earlier version of MDBM—See “NDBM Protocol Library”.

- Berkeley DB, Berkeley hash files —See “Berkeley DB Protocol Library”.

- Nisserv, the replacement for ypserv —See “Nisserv Protocol Library”.

- LDAP, the lightweight alternative for X500 —See “LDAP Protocol Library”.

As Figure 7-5 indicates, the `nsd` daemon directs requests to specific protocol libraries based on the resolution of a process pathname.

Figure 7-5. Action of ns_lookup in Selection of Protocol Library

### Files Library

The files library parses historic format configuration files such as `passwd` and `hosts`. If looked up in the .local domain, the file in `/etc` is opened and searched. If looked up in some other domain, then a file by the same name is opened under `/var/ns/domains/domainname` for the requested domainname. For more about how these attributes function, see “UNS File Structure Attributes”. See also the reference page `files`(7P).

### NIS Protocol Library

The NIS protocol library makes a request to a remote `ypserv` daemon using version 2 of the NIS protocol. It also takes the place of the `ypbind` daemon on the IRIX operating system. If the NIS protocol is supported on any table, then the library creates a new service socket that answers NIS bind requests from the old style NIS API routines`yp_match()`, `yp_all()`, and so on.

If a key is looked up in the .local domain then the current domainname of the system as specified by the `domainname` command is used. This is typically set in the `/var/yp/ypdomain` file. If the domain is unspecified then the server is dynamically located using the `ypbind` protocol. The maximum number of hops to use in multicast binding can be specified with the`nis_multicast` attribute which defaults to 32. See “Setting Domain Attributes”.

### DNS Protocol Library

The DNS protocol library makes a request to a remote `named` daemon using the DNS protocol. The DNS library parses the file `/etc/resolv.conf` to determine the default search path, nameserver list, and options. If a key is looked up in the .local domain then it will follow the search path; otherwise the specific domain is used. See “Setting Domain Attributes” for a discussion on setting these attributes.

### MDBM Protocol Library

The MDBM protocol library searches for data in `mdbm` hash database files on the local host. Names for these files are the same as the table with a`.m` extension added (for example: `hosts.byname.m`). For the`.local` domain these are found in the `/etc` directory, otherwise, they are found in the `/var/ns/domains/domainname` directory for each domainname. The flat files can be parsed into `mdbm` hash files using the `mdbm_parse` script provided with the nisserv library. See the`mdbm` reference page, and “Setting File Attributes” for an explanation.

### NDBM Protocol Library

The NDBM protocol library searches for data in `ndbm` hash database files on the local host. Names for these files are the same as the table with a `.pag` and`.dir` extension added (for example: `hosts.byname.pag` and `hosts.byname.pag`). For the `.local` domain these are found in the `/etc` directory, otherwise, they are found in the `/var/ns/domains/domainname` directory for each domainname. See the`ndbm(7P)` reference page, and “Setting File Attributes” for an explanation.

### Berkeley DB Protocol Library

The Berkeley DB protocol library searches for data in `db` hash database files on the local host. Names for these files are the same as the table with a `.db` extension added (for example: `hosts.byname.db`). For the `.local` domain these are found in the `/etc` directory, otherwise, they are found in the `/var/ns/domains/domainname` directory for each domainname. See the berkeleydb (7P) reference page, and “Setting File Attributes” for an explanation.

### Nisserv Protocol Library

The nisserv protocol library replaces the `ypserv` daemon in the IRIX operating system. This library will look up data in MDBM hash files on the local disk and provide them to remote machines using version 2 of the NIS protocol. The file naming rules are the same as those for MDBM. If the`nis_secure` attribute is set or the key YP_SECURE exists in the map file, then client systems are required to be using a port number less than 1024. This provides some weak security for maps with confidential information. A number of other special keys exist in the maps to provide the data for NIS protocol procedures. These keys include YP_MASTER_NAME, YP_LAST_MODIFIED, YP_INPUT_FILE, YP_OUTPUT_NAME, and YP_DOMAIN_NAME. These keys are historic from the previous implementation of NIS. For more information, see the `nisserv` (7P) reference page.

### LDAP Protocol Library

The LDAP protocol library converts local name service requests into remote LDAP protocol packets, then formats the result so that it may be used by the standard name service API. All server information and formatting rules are read from a single configuration file`/etc/ldap-ns.conf` .This file is read when the library is initialized or every time the name server daemon receives a SIGHUP signal.

## UNS File Structure Attributes

The `nsd` daemon implements an in-memory filesystem. File structures represent the state for each file, and extended attributes are supported on each name service file. The attributes on the file depend on the library that looked them up, but always include: domain, table, key, timeout, source, version, and server.Attributes are inherited from parent directories. If an attribute such as`timeout` exists on a directory then all the files in that directory will use the same value for`timeout`, unless it is overridden for a particular file. The global attributes, timeout, hostname, and program can be set by command line arguments.

This section explains how various attributes are set or queried:

- “Setting Domain Attributes”

- “Setting Table Attributes”

- “Setting Library Attributes”

- “Querying Attributes”

Attributes to `nsd` are given either on the command line as `nsd -a key=value` or specified in the `nsswitch.conf` file. Following any change, you need to restart `nsd` by giving the command:

    # killall -HUP nsd

### Setting Domain Attributes

In the `nsswitch.conf` file, set the attributes on a domain by lines in this format:

    (key1=value1, key2=value2)

### Setting Table Attributes

Attributes on a table follow the table name in the file:

    passwd(timeout=10): nis files

### Setting Library Attributes

Attributes on a library (for the table) are given following the library name:

    passwd: nis(timeout=10) files

### Setting File Attributes

Attributes on a particular file are specified in the filename:

    /ns/.local/passwd.byname/root(timeout=10)

Attributes can be changed by the library routines at will, and if an attribute is unspecified, then a default value is used.

### Querying Attributes

Attributes can be listed or queried using the `attr` command:

    attr -l /ns/.local/passwd.byname/root
    attr -g timeout /ns/.local/passwd.byname/root

## Cache Tuning

The size of the cache can be controlled with the parameters shown in Table 7-3, which are set in the `nsswitch.conf` file.

Table 7-3. Cache Tuning Parameters

Parameter | Description | Default/Source
--- | --- | ---
size | Total maximum pages, squared | 8
timeout | In seconds, length of time before cache expires | 300
pagesize | In bytes to the power of 2 | 4 Kbytes
mode | Permissions, can be varied | 0755
library | Name of the library that provided the data, as given in nsswitch.conf | Set by xattr command

## Troubleshooting nsd

### General Approach to Troubleshooting

Frequently the system log SYSLOG lists errors and points to solutions. The system log is available from the desktop. Error messages might take this form:

    NFS3 server (local host) nsd not responding
    NFS3 server local host (nsd) not responding
    Stale NFS File Handle

#### Remote Service Errors

If you see consistent or random errors in remote services such as`ping` or `rlogin` errors, `nsd` may have failed. To check the status of `nsd`, enter:

    ps -ef | grep nsd

If`nsd` does not appear in the list of processes running, restart `nsd`. Simply enter `nsd` at the prompt.

#### Mistakes in nsswitch.conf

A less common error message might be this:

    no such protocol

In such a case, check for misspellings in `nsswitch.conf`.

### Deciphering nsd Signals

Some signals `nsd` supports are familiar in other contexts. Send `nsd` the following command, defining `SIG` as`USR1`, `USR2`, `HUP`, or `TERM`.

    kill -SIG nsd

`USR1` |  | Forces nsd to create a state file: `/usr/tmp/nsd.dump` which is a batch file reflecting the state of the file system at the moment.
`USR2` |  | Increases the logging level. As you repeat the command, logging becomes more verbose. Beginning at 0, 6 is the most verbose.
`HUP` |  | Is sent any time one of the `.config` files is changed and you want the system to read the changes.
`TERM` |  | Is sent any time you want to kill`nsd`. You must send a catchable signal. `SIG TERM nsd` forces it to die.

Do not use `kill -kill`, `kill -9`, or `kill -all` as it may prevent you from unmounting the file system.

### Verifying /ns/.local

To check that the client files are installed, give this command:

    # cat /ns/.local/hosts.byname/localhost

You should find output similar to the following:

    127.0.0.1 local host

Prev | Table of Contents | Next
Chapter 6. BIND Name Server |  | Chapter 8. UUCP