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 : Domain : Com. 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

Table 10-1 nisls

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 don't 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, described in "The nisinit Command" on page 194.) The nismkdir command can also be used to add a replica to an existing directory.

There are several prerequisites to creating an NIS+ directory, as well as several related tasks. For a complete description, see NIS+ and DNS Setup and Configuration Guide.

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

---

Caution - 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.

---

This 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. Here are two examples:

• The first example creates the Sales.wiz.com. directory and associates it with its parent directory's master and replica servers.

rootmaster% nismkdir Sales.wiz.com

• The second example creates the Sales.wiz.com. directory and specifies its own master server, smaster.wiz.com.

rootmaster% nismkdir -m smaster.wiz.com. Sales.wiz.com.

Since no replica server is specified, the new directory will have only a master server until you use nismkdir again to assign it a replica. If the Sales.wiz.com. domain already existed, the nismkdir command as shown above would have made salesmaster.wiz.com. its new master server and would have relegated its old master server to a replica.

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 as described in NIS+ and DNS Setup and Configuration Guide.

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 with rep1 being 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.

---

Caution - 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 cron 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

This 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

This 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" on page 179), and you can empty tables with nistbladm -r or nistbladm -R (see "Deleting a Table" on page 211).

To remove a nondirectory object, use:

nisrm [-if] object-name

Table 10-2 nisrm

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...

This 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 don't need any access rights to start the NIS+ daemon, but you should be aware of all its prerequisites and related tasks. They are described in NIS+ and DNS Setup and Configuration Guide.

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

To start the daemon, use:

rpc.nisd

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

rpc.nisd -Y [-B]

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

rpc.nisd -Y -B

Table 10-3 rpc.nisd

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.

Starting the NIS+ Daemon

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

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:

rpc.nisd -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:

rpc.nisd -Y

If the server is rebooted, the daemon will not restart in NIS-compatibility mode unless you also uncomment the line that contains EMULYP=Y in the server's /etc/init.d/rpc file.

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:

rpc.nisd -Y -B

If the server is rebooted, the daemon will not restart in DNS-forwarding NIS-compatibility mode unless you also uncomment the line that contains EMULYP=-"Y" in the server's /etc/init.d/rpc file and change it to:

EMULYP="-Y -B"

Stopping the NIS+ Daemon

To stop the NIS+ daemon, whether it is running in normal or NIS-compatibility mode, kill it as you would any other daemon: first find its process ID, then kill it:

rootmaster# ps -e | grep rpc.nisd root 1081 1 61 16:43:33 ? 0:01 rpc.nisd -S 0 root 1087 1004 11 16:44:09 pts/1 0:00 grep rpc.nisd rootmaster# kill 1081

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 as described in NIS+ and DNS Setup and Configuration Guide.

The nisinit command initializes a workstation to be an NIS+ client. As with the rpc.nisd command, you don't need any access rights to use the nisinit command, but you should be aware of its prerequisites and related tasks. These are described in NIS+ and DNS Setup and Configuration Guide.

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:

• By host name
• By broadcast
• By cold-start file

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 nsswitch.conf file must have files as the first choice on the hosts line. Complete instructions for each method, including prerequisites and associated tasks, are provided in NIS+ and DNS Setup and Configuration Guide. 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% nis_cachemgr client% nis_cachemgr -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 as you would any other process.

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]

Displaying the Time of the Last Update

Use the -u option. It displays the update times for the master and replicas of the local domain, unless you specify a different domain name. It does not perform a ping.

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

Here is an example:

rootmaster# /usr/lib/nisping -u org_dir Last updates for directory wiz.com.: Master server is rootmaster.wiz.com. Last update occurred at Wed Nov 25 10:53:37 1992 Replica server is rootreplica1.wiz.com. Last update seen was Wed Nov 25 10:53:37 1992

Pinging Replicas

You can ping all the replicas in a domain, or one in particular. To ping all the replicas, use the command without options:

/usr/lib/nis/nisping

To ping all the replicas in a domain other than the local domain, append a domain name:

/usr/lib/nis/nisping domainname

Here is an example that pings all the replicas of the local domain, wiz.com.:

rootmaster# /usr/lib/nis/nisping org_dir Pinging replicas serving directory wiz.com.: Master server is rootmaster.wiz.com. Last update occurred at Wed Nov 25 10:53:37 1992 Replica server is rootreplica1.wiz.com. Last update seen was Wed Nov 18 11:24:32 1992 Pinging ... rootreplica1.wiz.com.

Since the update times were different, it proceeds with the ping. If the times had been identical, it would not have sent a ping.

You can also ping all the tables in all the directories on a single specified host. To ping all the tables in all the directories of a particular host, us the -a option:

/usr/lib/nis/nisping -a hostname

Checkpointing a Directory

To checkpoint a directory, use the -C option:

/usr/lib/nis/nisping -C directory-name

All the servers that support a domain, including the master, transfer their information from their .log files to disk. This erases the log files and frees disk space. While a server is checkpointing, it will still answer requests for service, but it will be unavailable for updates.

Here is an example of nisping output:

rootmaster# /usr/lib/nis/nisping -C Checkpointing replicas serving directory wiz.com. : Master server is rootmaster.wiz.com. Last update occurred at Wed May 25 10:53:37 1995 Master server is rootmaster.wiz.com. checkpoint has been scheduled with rootmaster.wiz.com. Replica server is rootreplica1.wiz.com. Last update seen was Wed May 25 10:53:37 1995 Replica server is rootreplica1.wiz.com. checkpoint has been scheduled with rootmaster.wiz.com.

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]

Table 10-4 nislog

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

Displaying the Contents of the Transaction Log

Each transaction consists of two parts: the particulars of the transaction and a copy of an object definition.

Here is an example that shows the transaction log entry that was made when the wiz.com. directory was first created. "XID" refers to the transaction ID.

rootmaster# /usr/sbin/nislog -h 1 NIS Log printing facility. NIS Log dump: Log state : STABLE Number of updates : 48 Current XID : 39 Size of log in bytes : 18432 ***UPDATES*** @@@@@@@@@@@@@@TRANSACTION@@@@@@@@@@@@@@ #00000, XID : 1 Time : Wed Nov 25 10:50:59 1992 Directory : wiz.com. Entry type : ADD Name Entry timestamp : Wed Nov 25 10:50:59 1992 Principal : rootmaster.wiz.com. Object name : org_dir.wiz.com. ...................Object...................... Object Name : org_dir Owner : rootmaster.wiz.com. Group : admin.wiz.com. Domain : wiz.com. Access Rights : r---rmcdr---r--- Time to Live : 24:0:0 Object Type : DIRECTORY Name : 'org_dir.wiz.com.' Type: NIS Master Server : rootmaster.wiz.com. . . ................................................ @@@@@@@@@@@@@@TRANSACTION@@@@@@@@@@@@@@ #00000, XID : 2

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, described in Chapter 7, "Administering NIS+ Access Rights."

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:

• Number of seconds. A number with no letter is interpreted as a number of seconds. Thus, 1234 for TTL would be interpreted as 1234 seconds. A number followed by the letter s is also interpreted as a number of seconds.

Thus, 987s for TTL would be interpreted as 987 seconds. When seconds are specified in combination with days, hours, or minutes, you must use the letter s to identify the seconds value.

• Number of minutes. A number followed by the letter m is interpreted as a number of minutes. Thus, 90m for TTL would be interpreted as 90 minutes.
• Number of hours. A number followed by the letter h is interpreted as a number of hours. Thus, 9h for TTL would be interpreted as 9 hours.
• Number of days. A number followed by the letter d is interpreted as a number of days. Thus, 7d for TTL would be interpreted as 7 days.

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.

The following flags may also be used with the nischttl command:

Table 10-5 nischttl

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.

Changing the Time-to-Live of an Object

To change the time-to-live of an object, type the nischttl command with the time-to-live value and the object-name. You can add the -L command to extend the change to linked objects.

nischttl -L time-to-live object-name

You can specify the time-to-live in seconds by typing the number of seconds. Or you can specify a combination of days, hours, minutes, and seconds by using the suffixes s, m, h, and d to indicate the number of seconds, minutes, days, and hours. For example:

client% nischttl 86400 sales.wiz.com. client% nischttl 24h sales.wiz.com. client% nischttl 2d1h1m1s sales.wiz.com.

TTL of 86400 seconds TTL of 24 hours

TTL of 2 days, 1 hour, 1 minute, and 1

second

The first two commands change the time-to-live of the sales.wiz.com. directory to 86,400 seconds, or 24 hours. The third command changes the time-to-live of all the entries in a hosts table to 2 days, 1 hour, 1 minute, and 1 second.

Changing the Time-to-Live of a Table Entry

To change the time-to-live of entries, use the indexed entry format. You can use any of the options, -A, -L, or -P.

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

These examples are similar to those above, but they change the value of table entries instead of objects:

client% nischttl 86400 '[uid=99],passwd.org_dir.wiz.com.' client% nischttl 24h '[uid=99],passwd.org_dir.wiz.com.' client% nischttl 2d1h1m1s '[name=fred],hosts.org_dir.wiz.com'