[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Network Information Services (NIS and NIS+) Guide

Administering NIS+ Directories

This section describes how to use the NIS+ directory administration commands to perform the following tasks:

Using the niscat Command With Directories

The niscat -o command can be used to list the object properties of an NIS+ directory. To use it, you must have read access to the directory object itself.

Listing the Object Properties of a Directory

To list the object properties of a directory, use niscat -o and the directory's name:

niscat -o directory-name

For example:

rootmaster# niscat -o wiz.com.
Object Name   : wiz
Owner         : rootmaster.wiz.com.
Group         : 
Access Rights : r---rmcdr---r---
Time to Live  : 24:0:0
Object Type   : DIRECTORY
.
.
.

The nisls Command

The nisls command lists the contents of an NIS+ directory. To use it, you must have read rights to the directory object.

To display in terse format, use:

nisls [-dgLmMR] directory-name

To display in verbose format, use:

nisls -l [-gm] [-dLMR] directory-name
Options for the nisls Command
Option Purpose
-d Directory object. Instead of listing a directory's contents, treat it like another object.
-L Links. If the directory name is actually a link, the command follows the link and displays information about the linked directory.
-M Master. Get the information from the master server only. Although this provides the most up-to-date information, it may take longer if the master server is busy.
-R Recursive. List directories recursively. That is, if a directory contains other directories, their contents are displayed as well.
-l Long. Display information in long format. Long format displays an object's type, creation time, owner, and access rights.
-g Group. When displaying information in long format, display the directory's group owner instead of its owner.
-m Modification time. When displaying information in long format, display the directory's modification time instead of its creation time.

Listing the Contents of a Directory--Terse

To list the contents of a directory in the default short format, use one or more of the options listed below and a directory name. If you do not supply a directory name, NIS+ will use the default directory.

nisls [-dLMR]
nisls [-dLMR] directory-name

For example, this instance of nisls is entered from the root master server of the root domain wiz.com.:

rootmaster% nisls 
wiz.com.:
org_dir 
groups_dir

Here is another example entered from the root master server:

rootmaster% nisls -R Sales.wiz.com. 
Sales.wiz.com.: 
org_dir	  
groups_dir 

groups_dir.Sales.wiz.com.:
admin 

org_dir.Sales.wiz.com.:
auto_master
auto_home
bootparams
cred
.
.
.

Listing the Contents of a Directory--Verbose

To list the contents of a directory in the verbose format, use the -l option and one or more of the options listed below. The -g and -m options modify the attributes that are displayed. If you don't supply a directory name, NIS+ will use the default directory.

nisls -l [-gm] [-dLMR]
nisls -l [-gm] [-dLMR] directory-name

Here is an example, entered from the master server of the root domain wiz.com.:

rootmaster% nisls -l

wiz.com.:
D r---rmcdr---r--- rootmaster.wiz.com. date org_dir
D r---rmcdr---r--- rootmaster.wiz.com. date groups_dir

The nismkdir Command

The nismkdir command creates a nonroot NIS+ directory and associates it with a master server. (To create a root directory, use the nisinit -r command. The nismkdir command can also be used to add a replica to an existing directory.

This section desribes how to add a nonroot directory and its master server to an existing system using the nismkdir command. An easier way to do this is with the nisserver script, described in NIS+ Setup Scripts.

To create a directory, use:

nismkdir [-m master-server] directory-name

To add a replica to an existing directory, use:

nismkdir -s replica-server directory-name
nismkdir -s replica-server org_dir. directory-name
nismkdir -s replica-server groups_dir. directory-name

Creating a Directory

To create a directory, you must have create rights to its parent directory on the domain master server. First use the -m option to identify the master server and then the -s option to identify the replica, use:

nismkdir -m master directory
nismkdir -s replica directory
Attention: Always run nismkdir on the master server. Never run nismkdir on the replica machine. Running nismkdir on a replica creates communications problems between the master and the replica.

The following example creates the Sales.wiz.com. directory and specifies its master server, smaster.wiz.com. and its replica, rep1.wiz.com. It is entered from the root master server.

rootmaster% nismkdir -m smaster.wiz.com. Sales.wiz.com.
rootmaster% nismkdir -m smaster.wiz.com. org_dir.Sales.wiz.com.
rootmaster% nismkdir -m smaster.wiz.com. groups_dir.Sales.wiz.com.
rootmaster% nismkdir -s rep1.wiz.com. Sales.wiz.com.
rootmaster% nismkdir -s rep1.wiz.com. org_dir.Sales.wiz.com.
rootmaster% nismkdir -s rep1.wiz.com. groups_dir.Sales.wiz.com. 

The nismkdir command allows you to use the parent directory's servers for the new directory instead of specifying its own. However, this should not be done except in the case of small networks. See the following examples:

Adding a Replica to an Existing Directory

This section describes how to add a replica server to an existing system using the nismkdir command. An easier way to do this is with the nisserver script, described in NIS+ Setup Scripts.

To assign a new replica server to an existing directory, use nismkdir on the master server with the -s option and the name of the existing directory, org_dir, and groups_dir:

nismkdir -s replica-server existing-directory-name
nismkdir -s replica-server org_dir. existing-directory-name
nismkdir -s replica-server groups_dir. existing-directory-name

The nismkdir command realizes that the directory already exists, so it does not recreate it. It only assigns it the additional replica. Here is an example in which rep1 is the name of the new replica machine:

rootmaster% nismkdir -s rep1.wiz.com. wiz.com.
rootmaster% nismkdir -s rep1.wiz.com. org_dir.wiz.com.
rootmaster% nismkdir -s rep1.wiz.com. groups_dir.wiz.com.

Note that you cannot assign a server to support its parent domain--unless, of course, it belongs to the root domain.

Attention: Always run nismkdir on the master server. Never run nismkdir on the replica machine. Running nismkdir on a replica creates communications problems between the master and the replica.

After running the three iterations of nismkdir as shown above, you need to run nisping from the master server on the three directories:

rootmaster# nisping wiz.com. 
rootmaster# nisping org_dir.wiz.com. 
rootmaster# nisping group_dir.wiz.com. 

You should see results similar to these:

rootmaster# nisping wiz.com. 

Pinging replicas serving directory wiz.com. :
Master server is rootmaster.wiz.com.
        Last update occurred at Wed Nov 18 19:54:38 1995 
Replica server is rep1.wiz.com.
        Last update seen was Wed Nov 18 11:24:32 1995
 
        Pinging ... rep1.wiz.com.

It is good practice to include nisping commands for each of these three directories in the master server's /etc/crontab file so that each directory is pinged at least once every 24 hours after being updated.

The nisrmdir Command

The nisrmdir command can remove a directory or simply dissociate a replica server from a directory. When it removes a directory, NIS+ first disassociates the master and replica servers from the directory, and then removes the directory. To remove the directory, you must have destroy rights to its parent directory. To dissociate a replica server from a directory, you must have modify rights to the directory.

Removing a Directory

To remove an entire directory and dissociate its master and replica servers, use the nisrmdir command without any options:

nisrmdir directory-name

The following example removes the manf.wiz.com. directory from beneath the wiz.com. directory:

rootmaster% nisrmdir manf.wiz.com.

Disassociating a Replica From a Directory

To dissociate a replica server from a directory, use the nisrmdir command with the -s option:

nisrmdir -s servername directory

The following example disassociates the manfreplica1 server from the manf.wiz.com. directory:

rootmaster% nisrmdir -s manfreplica1 manf.wiz.com.

The nisrm Command

The nisrm command is similar to the standard rm system command. It removes any NIS+ object from the namespace, except directories and nonempty tables. To use the nisrm command, you must have destroy rights to the object. However, if you don't, you can use the -f option, which tries to force the operation in spite of permissions.

You can remove group objects with the nisgrpadm -d command (see Deleting an NIS+ Group), and you can empty tables with nistbladm -r or nistbladm -R.

To remove a nondirectory object, use:

nisrm [-if] object-name
nisrm Syntax Options
Option Purpose
-i Inquire. Asks for confirmation prior to removing an object. If the object-name you provide is not fully qualified, this option is used automatically.
-f Force. Attempts to force a removal even if you don't have the proper permissions. It attempts to change the permission by using the nischmod command, and then tries to remove the object again.

Removing Nondirectory Objects

To remove nondirectory objects, use the nisrm command and provide the object names:

nisrm object-name...

The following example removes a group and a table from the namespace:

rootmaster% nisrm -i admins.wiz.com. groups.org_dir.wiz.com.
Remove admins.wiz.com.? y
Remove groups.org_dir.wiz.com.? y

The rpc.nisd Command

The rpc.nisd command starts the NIS+ daemon. The daemon can run in NIS-compatibility mode, which enables it to answer requests from NIS clients as well. You do not need any access rights to start the NIS+ daemon, but you should be aware of all its prerequisites and related tasks.

By default, the NIS+ daemon starts with security level 2.

To start the daemon, use:

startsrc -s rpc.nisd

To start the daemon in NIS-compatibility mode, use:

startsrc -s rpc.nisd -a "-Y"

To start an NIS-compatible daemon with DNS forwarding capabilities, use:

startsrc -s rpc.nisd -a "-Y -B"
Other rpc.nisd Syntax Options
Option Purpose
-S security-level Specifies a security level, where 0 means no NIS+ security and 2 provides full NIS+ security. (Level 1 is not supported.)
-F Forces a checkpoint of the directory served by the daemon. This has the side effect of emptying the directory's transaction log and freeing disk space.

To start the NIS+ daemon on any server, use the command without options:

startsrc -s rpc.nisd

The daemon starts with security level 2, which is the default.

To start the daemon with security level 0, use the -S flag:

startsrc -s rpc.nisd -a "-S 0"

Starting a NIS-Compatible Daemon

You can start the NIS+ daemon in NIS-compatibility mode in any server, including the root master. Use the -Y (uppercase) option:

startsrc -s rpc.nisd -a "-Y"

If the server is rebooted, the daemon will not restart in NIS-compatibility mode unless you also edit the server's /etc/rpc.nfs file with mk_nisd -I -y -b.

Starting a DNS-Forwarding NIS-Compatible Daemon

You can add DNS forwarding capabilities to an NIS+ daemon running in NIS-compatibility mode by adding the -B option to rpc.nisd:

startsrc -s rpc.nisd -a "-Y -B"

If the server is rebooted, the daemon will not restart in DNS-forwarding NIS-compatibility mode unless you also edit the server's /etc/rpc.nfs file with mk_nisd -I -y -b.

Stopping the NIS+ Daemon

To stop the NIS+ daemon, whether it is running in normal or NIS-compatibility mode, use:

rootmaster# stopsrc -s rpc.nisd

The nisinit Command

This section describes how to initialize a workstation client using the nisinit command. An easier way to do this is with the nisclient script, described in NIS+ Setup Scripts.

The nisinit command initializes a workstation to be an NIS+ client. As with the rpc.nisd command, you do not need any access rights to use the nisinit command, but you should be aware of its prerequisites and related tasks.

To initialize a client, use:

nisinit -c -B
nisinit -c -H hostname
nisinit -c -C filename

To initialize a root master server, use:

nisinit -r

Initializing a Client

You can initialize a client in three different ways:

Each way has different prerequisites and associated tasks. For instance, before you can initialize a client by host name, the client's /etc/hosts file must list the host name you will use and the irs.conf file must have files as the first choice on the hosts line. Following is a summary of the steps that use the nisinit command.

To initialize a client by host name, use the -c and -H options, and include the name of the server from which the client will obtain its cold-start file:

nisinit -c -H hostname

To initialize a client by cold-start file, use the -c and -C options, and provide the name of the cold-start file:

nisinit -c -C filename 

To initialize a client by broadcast, use the -c and -B options:

nisinit -c -B

Initializing the Root Master Server

To initialize the root master server, use the nisinit -r command:

nisinit -r

The nis_cachemgr Command

The nis_cachemgr command starts the NIS+ cache manager program, which should run on all NIS+ clients. The cache manager maintains a cache of location information about the NIS+ servers that support the most frequently used directories in the namespace, including transport addresses, authentication information, and a time-to-live value.

At start-up the cache manager obtains its initial information from the client's cold-start file, and downloads it into the /var/nis/NIS_SHARED_DIRCACHE file.

The cache manager makes requests as a client workstation. Make sure the client workstation has the proper credentials, or instead of improving performance, the cache manager will degrade it.

Starting the Cache Manager

To start the cache manager, enter the nis_cachemgr command (with or without the -i option):

client% startsrc -s nis_cachemgr
client% startsrc -s nis_cachemgr -a "-i"

Without the -i option, the cache manager is restarted but it retains the information in the /var/nis/NIS_SHARED_DIRCACHE file. The information in the cold-start file is simply appended to the existing information in the file. The -i option clears the cache file and re-initializes it from the contents of the client's cold-start file.

To stop the cache manager, kill it using stopsrc -s nis_cachemgr.

The nisshowcache Command

The nisshowcache command displays the contents of a client's directory cache.

Displaying the Contents of the NIS+ Cache

The nisshowcache command is located in /usr/lib/nis. It displays only the cache header and the directory names. Here is an example entered from the root master server:

rootmaster# /usr/lib/nis/nisshowcache -v 
 Cold Start directory:
 Name : wiz.com.
 Type : NIS
 Master Server :
   Name       : rootmaster.wiz.com.
   Public Key : Diffie-Hellman (192 bits)
   Universal addresses (3)
   .
   .
   .
 Replicate:
   Name       : rootreplica1.wiz.com.
   Public Key : Diffie-Hellman (192 bits)
   Universal addresses (3)
   .
   .
   .
Time to live : 12:0:0
Default Access Rights :

The nisping Command

The nisping command pings replica servers, telling them to ask the master server for updates immediately. (The replicas normally wait a couple of minutes before executing this request.) Before pinging, the command checks the time of the last update received by each replica. If it is the same as the last update sent by the master, it does not ping the replica.

The nisping command can also checkpoint a directory. This consists of telling each server in the directory, including the master, to update its information on disk from the domain's transaction log.

To display the time of the last update, use:

/usr/lib/nis/nisping -u [domain]

To ping replicas, use:

/usr/lib/nis/nisping [domain]
/usr/lib/nis/nisping -H hostname [domain]

To checkpoint a directory, use:

/usr/lib/nis/nisping -C hostname [domain]

For more information, read the nisping command description.

The nislog Command

The nislog command displays the contents of the transaction log.

/usr/sbin/nislog
/usr/sbin/nislog -h [number]
/usr/sbin/nislog -t [number]
Options for the nislog Command
Option Purpose
-h [ num] Display transactions starting with the head (beginning) of the log. If the number is omitted, the display begins with the first transaction. If the number 0 is entered, only the log header is displayed.
-t [ num] Display transactions starting backward from the end (tail) of the log. If the number is omitted, the display begins with the last transaction. If the number 0 is entered, only the log header is displayed.
-v Verbose mode

For more information, see the nislog command description.

The nischttl Command

The nischttl command changes the time-to-live value of objects or entries in the namespace. This time-to-live value is used by the cache manager to determine when to expire a cache entry. You can specify the time-to-live in total number of seconds or in a combination of days, hours, minutes, and seconds.

The time-to-live values you assign objects or entries should depend on the stability of the object. If an object is prone to frequent change, give it a low time-to-live value. If it is steady, give it a high one. A high time-to-live is a week; a low one is less than a minute. Password entries should have time-to-live values of about 12 hours to accommodate one password change per day. Entries in tables that don't change much, such as those in the RPC table, can have values of several weeks.

To change the time-to-live of an object, you must have modify rights to that object. To change the time-to-live of a table entry, you must have modify rights to the table, entry, or columns you wish to modify.

To display the current time-to-live value of an object or table entry, use the nisdefaults -t command

To change the time-to-live value of objects, use:

nischttl time-to-live object-name
nischttl [-L] time-to-live object-name

To change the time-to-live value of entries, use:

nischttl time-to-live [column=value,...], table-name
nischttl [-ALP] time-to-live [column=value,...],table-name

Where time-to-live is expressed as:

These values may be used in combination. For example, a TTL value of 4d3h2m1s would specify a time to live of four days, three hours, two minutes, and one second.

nischttl Syntax Options
Option Purpose
-A All. Apply the change to all the entries that match the column= value specifications that you supply.
-L Links. Follow links and apply the change to the linked object or entry rather than the link itself.
-P Path. Follow the path until there is one entry that satisfies the condition.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]