Chapter 9

NIS+ Programming Guide

This chapter presents the fundamental principles of the NIS+ (pronounced "niss-plus") applications programming interface and a detailed sample program. The NIS+ API is for programmers who need to build applications for Solaris networks. It provides the essential features for supporting enterprise-wide applications.

This chapter covers the following topics:

The NIS+ network name service addresses the requirements of client/server networks ranging in size from 10 clients supported by a few servers on a local area network to 10,000 multi-vendor clients supported by 20 to 100 specialized servers located in sites throughout the world and connected by several public networks.

NIS+ Overview

This section describes various aspects of the NIS+ network name service.

NIS+ Domains

NIS+ supports hierarchical domains, as illustrated in the following figure.

Figure 9-1 NIS+ Domain

A NIS+ domain is a set of data describing the workstations, users, and network services in a portion of an organization. NIS+ domains can be administered independently of each other. This independence enables NIS+ to be used in a range of networks, from small to very large.

NIS+ and Servers

Each domain is supported by a set of servers. The principal server is called the master server, and the backup servers are called replicas. Both master and replica servers run NIS+ server software. The master server stores the original tables, and the backup servers store copies.

NIS+ accepts incremental updates to the replicas. Changes are first made on the master server. Then they are automatically propagated to the replica servers and are soon available to the entire namespace.

NIS+ Tables

NIS+ stores information in tables instead of maps or zone files. NIS+ provides 16 types of predefined, or system, tables, which are shown in the following figure.

Figure 9-2 NIS+ Tables

Each table stores a different type of information. For instance, the Hosts table stores host name/Internet address pairs, and the Password table stores information about users of the network.

NIS+ tables have two major improvements over NIS maps. First, a NIS+ table can be accessed by any column, not just the first column, which is sometimes referred to as the "key." This access eliminates the need for duplicate maps, such as the hosts.byname and hosts.byaddr maps of NIS. Second, access to the information in NIS+ tables can be controlled at three levels of granularity: the table level, the entry level, and the column level.

NIS+ Security

The NIS+ security model provides both authorization and authentication mechanisms. For authorization, every object in the namespace specifies the type of operation it accepts and from whom. NIS+ attempts to authenticate every requestor accessing the namespace. After it identifies the originator of the request, it determines whether the object has authorized that particular operation for that particular principal. Based on its authentication and the object's authorization, NIS+ carries out or denies the access request.

Name Service Switch

NIS+ works in conjunction with a separate facility called the Name Service Switch. The Name Service Switch, sometimes referred to as "the Switch," enables Solaris-based workstations to obtain their information from more than one network information service. They can get the information from local, or /etc files, from NIS maps, from DNS zone files, or from NIS+ tables. The Switch not only offers a choice of sources, but allows a workstation to specify different sources for different types of information. The name service is configured through the file /etc/nsswitch.conf.

NIS+ Administration Commands

NIS+ provides a full set of commands for administering a namespace, as listed in the following table.

Table 9-1 NIS+ Namespace Administration Commands

Command	Description
`nischgrp`	Changes the group owner of a NIS+ object.
`nischmod`	Changes an object's access rights.
`nischown`	Changes the owner of a NIS+ object.
`nisgrpadm`	Creates or destroys a NIS+ group, or displays a list of its members. Also adds members to a group, removes them, or tests them for membership in the group.
`niscat`	Displays the contents of NIS+ tables.
`nisgrep`	Searches for entries in a NIS+ table.
`nisls`	Lists the contents of a NIS+ directory.
`nismatch`	Searches for entries in a NIS+ table.
`nisaddent`	Adds information from `/etc` files or NIS maps into NIS+ tables.
`nistbladm`	Creates or deletes NIS+ tables, and adds, modifies, or deletes entries in a NIS+ table.
`nisaddcred`	Creates credentials for NIS+ principals and stores them in the Cred table.
`nispasswd`	Changes password information stored in the NIS+ Passwd table.
`nisupdkeys`	Updates the public keys stored in a NIS+ object.
`nisinit`	Initializes a NIS+ client or server.
`nismkdir`	Creates a NIS+ directory and specifies its master and replica servers.
`nisrmdir`	Removes NIS+ directories and replicas from the namespace.
`nissetup`	Creates `org_dir` and `groups_dir` directories and a complete set of (unpopulated) NIS+ tables for a NIS+ domain.
`rpc.nisd`	The NIS+ server process.
`nis_cachemgr`	Starts the NIS+ Cache Manager on a NIS+ client.
`nischttl`	Changes a NIS+ object's time to live value.
`nisdefaults`	Lists a NIS+ object's default values: domain name, group name, workstation name, NIS+ principal name, access rights, directory search path, and time-to-live.
`nisln`	Creates a symbolic link between two NIS+ objects.
`nisrm`	Removes NIS+ objects (except directories) from the namespace.
`nisshowcache`	Lists the contents of the NIS+ shared cache maintained by the NIS+ Cache Manager.

NIS+ API

The NIS+ application programming interface (API) is a group of functions that can be called by an application to access and modify NIS+ objects. The NIS+ API has 54 functions that fall into nine categories:

Object manipulation functions (nis_names)
Table access functions (nis_tables)
Local name functions (nis_local_names)
Group manipulation functions (nis_groups)
Server related functions (nis_server)
Database access functions (nis_db)
Error message display functions (nis_error)
Transaction log functions (nis_admin)
Miscellaneous functions (nis_subr)

The functions in each category are summarized in the following table. The category names match the names by which they are grouped in the NIS+ man pages.

Table 9-2 NIS+ API Functions

Function	Description
`nis_names()`	Locates and manipulates objects.
`nis_lookup()`	Returns a copy of a NIS+ object. Can follow links. Though it cannot search for an entry object, if a link points to one, it can return an entry object.
`nis_add()`	Adds a NIS+ object to the namespace.
`nis_remove()`	Removes a NIS+ object in the namespace.
`nis_modify()`	Modifies a NIS+ object in the namespace.
`nis_tables`	Searches and updates tables.
`nis_list()`	Searches a table in the NIS+ namespace and returns entry objects that match the search criteria. Can follow links and search paths from one table to another.
`nis_add_entry()`	Adds an entry object to a NIS+ table. Can be instructed to either fail or overwrite if the entry object already exists. Can return a copy of the resulting object if the operation was successful.
`nis_freeresult()`	Frees all memory associated with a `nis_result` structure.
`nis_remove_entry()`	Removes one or more entry objects from a NIS+ table. Can identify the object to be removed by using search criteria or by pointing to a cached copy of the object. If using search criteria, can remove all objects that match the search criteria; therefore, with the proper search criteria, can remove all entries in a table. Can return a copy of the resulting object if the operation was successful.
`nis_modify_entry()`	Modifies one or more entry objects in a NIS+ table. Can identify the object to be modified by using search criteria or by pointing to a cached copy of the object.
`nis_first_entry()`	Returns a copy of the first entry object in a NIS+ table.
`nis_next_entry()`	Returns a copy of the "next" entry object in a NIS+ table. Because a table can be updated and entries removed or modified between calls to this function, the order of entries returned might not match the actual order of entries in the table.
`nis_local_names()`	Gets default names for the current process.
`nis_local_directory()`	Returns the name of the workstation's NIS+ domain.
`nis_local_host()`	Returns the fully qualified name of the workstation. A fully qualified name has the form host-name.domain-name.
`nis_local_group()`	Returns the name of the current NIS+ group, which is specified by the environment variable NIS_GROUP.
`nis_local_principal()`	Returns the name of the NIS+ principal that has a UID associated with the calling process.
`nis_getnames()`	Returns a list of possible expansions to a particular name.
`nis_freenames()`	Frees the memory containing the list generated by `nis_getnames()`.
`nis_groups()`	Group manipulation and authorization.
`nis_ismember()`	Tests whether a principal is a member of a group.
`nis_addmember()`	Adds a member to a group. The member can be a principal, a group, or a domain.
`nis_removemember()`	Deletes a member from a group.
`nis_creategroup()`	Creates a group object.
`nis_destroygroup()`	Deletes a group object.
`nis_verifygroup()`	Tests whether a group object exists.
`nis_print_group_entry()`	Lists the principals that are members of a group object.
`nis_server`	Various services for NIS+ applications.
`nis_mkdir()`	Creates the databases to support service for a named directory on a specified host.
`nis_rmdir()`	Removes the directory from a host.
`nis_servstate()`	Sets and reads state variables of NIS+ servers and flushes internal caches.
`nis_stats()`	Retrieves statistics about a server's performance.
`nis_getservlist()`	Returns a list of servers that support a particular domain.
`nis_freeservlist()`	Frees the list of servers returned by `nis_getservlist()`.
`nis_freetags()`	Frees the memory associated with the results of `nis_servstate()` and `nis_stats()`.
`nis_db`	Interface between the NIS+ server and the database. Not to be used by a NIS+ client.
`db_first_entry()`	Returns a copy of the first entry of the specified table.
`db_next_entry()`	Returns a copy of the entry succeeding the specified entry.
`db_reset_next_entry()`	Terminates a first/next entry sequence.
`db_list_entries()`	Returns copies of entries that meet specified attributes.
`db_remove_entry()`	Removes all entries that meet specified attributes.
`db_add_entry()`	Replaces an entry in a table identified by specified attributes with a copy of the specified object, or adds the object to the table.
`db_checkpoint()`	Reorganizes the contents of a table to make access to the table more efficient.
`db_standby()`	Advises the database manager to release resources.
`nis_error()`	Functions that supply descriptive strings equivalent to NIS+ status values.
`nis_sperrno()`	Returns a pointer to the appropriate string constant.
`nis_perror()`	Displays the appropriate string constant on standard output.
`nis_lerror()`	Sends the appropriate string constant to `syslog`.
`nis_sperror()`	Returns a pointer to a statically allocated string to be used or to be copied with `strdup()`.
`nis_admin`	Transaction logging functions used by servers.
`nis_ping`	Used by the master server of a directory to timestamp it. This forces replicas of the directory to be updated.
`nis_checkpoint()`	Forces logged data to be stored in the table on disk.
`nis_subr`	Functions to help operate on NIS+ names and objects.
`nis_leaf_of()`	Returns the first label in a NIS+ name. The returned name does not have a trailing dot.
`nis_name_of()`	Removes all domain-related labels and returns only the unique object portion of the name. The name passed to the function must be either in the local domain or in one of its child domains, or the function returns NULL.
`nis_domain_of()`	Returns the name of the domain in which an object resides. The returned name ends in a dot.
`nis_dir_cmp()`	Compares any two NIS+ names. The comparison ignores case and states whether the names are the same, descendants of each other, or not related.
`nis_clone_object()`	Creates an exact duplicate of a NIS+ object.
`nis_destroy_object()`	Destroys an object created by `nis_clone_object()`.
`nis_print_object()`	Prints the contents of a NIS+ object structure to `stdout`.