Setting Up the Root Domain

Network Information Services (NIS and NIS+) Guide

Setting Up the Root Domain

This section provides step-by-step instructions for one task: setting up the root domain with DES authentication using the NIS+ command set.

Note: It is much easier to perform this task with the NIS+ installation scripts as described in NIS+ Setup Scripts than with the NIS+ command set as described here. The methods described in this section should be used only by those administrators who are very familiar with NIS+ and who require some nonstandard features or configurations not provided by the installation scripts.

See Configuration Worksheets, for worksheets that you can use to plan your NIS+ namespace.

This task describes how to set up the root domain with the root master server running at security level 2 (the normal level).

Setting up the root domain involves three major tasks:

Preparing the root master server
Creating the root domain
Creating credentials for the root domain

However, setting up the root domain is not as simple as performing these three tasks in order; they are intertwined with each other. For instance, you must specify some security parameters before you create the root directory; the rest, after. To make the root domain easier to set up, this section separates these tasks into individual steps and arranges them into their most efficient order.

Standard versus NIS-Compatible Setup Procedures

The steps in this section apply to both a standard NIS+ root domain and an NIS-compatible root domain. There are, however, some important differences. The NIS+ daemon for an NIS-compatible domain must be started with the -Y option, which allows the root master server to answer requests from NIS clients.

An NIS-compatible domain also requires read rights to the passwd table for the nobody class, which allows NIS clients to access the information stored in the table's passwd column. This is accomplished with the -Y option to the nissetup command. The standard NIS+ domain version uses the same command but without the -Y option.

Establishing the Root Domain

The procedure describes each step in detail and provides related information. For those who do not need detailed instructions, a summary listing of the necessary commands is provided on Root Domain Setup Summary.

Summary of Steps

Here is a summary of the entire setup process:

Log in as superuser to the root master server.
Check the root master server's domain name.
Check the root master server's /etc/irs.conf file.
Kill and restart keyserv.
Clean out leftover NIS+ material and processes.
Kill server daemons.
Name the root domain's admin group.
Create the root directory and initialize the root master server.
[NIS-compatibility Only] Start the NIS+ daemon with -Y. (See the mk_nisd command description.)
or

[Standard NIS+ Only] Start the NIS+ daemon. (See the mk_nisd command description.)
Verify that the root objects have been properly created.
Create the root domain's subdirectories and tables.
Create DES credentials for the root master server.
Create the root domain's admin group.
Add the root master to the root domain's admin group.
Update the root domain's public keys.
Start the NIS+ cache manager. (See the mk_niscachemgr command description.)
Stop the NIS+ daemon. (See the rm_nisd command description.)
Restart the NIS+ daemon with security level 2. (See the mk_nisd command description.)
Add your LOCAL credentials to the root domain.
Add your DES credentials to the root domain.
Add credentials for other administrators.
Add yourself and other administrators to the root domain's admin group.

Security Considerations

NIS+ provides preset security defaults for the root domain. The default security level is level 2.

Attention:
Operational networks with actual users should always be run at security level 2. Security levels 0 and 1 are for setup and testing purposes only. Do not run an operational network at level 0 or 1.

The NIS+ security system is complex. If you are not familiar with NIS+ security, review the security-related chapters of this book before starting to set up your NIS+ environment.

Prerequisites

Before proceeding, make sure that

The /etc/passwd file on the root master server must contain an entry for you and every other administrator whose credentials will be added to the root domain in this setup process.
If the server will operate in NIS-compatibility mode and support DNS forwarding for clients, it must have a properly configured /etc/resolv.conf file.
The server must have a unique machine name that does not duplicate any user ID.
The server must have a machine name that does not contain any dots. For example, a machine named sales.alpha is not allowed. A machine named sales-alpha is allowed.

In order to complete this task you need to know

The superuser password of the workstation that will become the root master server
The name of the root domain
The name of the root domain's admin group
Your user ID and password
The user ID of any administrator whose credentials you are adding to the root domain

Procedure

You can set up a root domain using Web-based System Manager, the System Management Interface Tool (SMIT), or the following procedure:

Log in as superuser on the machine to be the root master server.
The examples in these steps use rootmaster as the root master server and wiz.com. as the root domain.
Check the root master server's domain name.
Use the domainname command to make sure the root master server is using the correct domain name. The domainname command returns a workstation's current domain name.

Attention: Domains and hosts should not have the same name. For example, if you have a sales domain you should not have a machine named sales. Similarly, if you have a machine named home, you do not want to create a domain named home. This caution applies to subdomains; for example, if you have a machine named west, you do not want to create a sales.west.myco.com subdirectory.

If the name is not correct, change it.
```
rootmaster# domainname 
   strange.domain
rootmaster# domainname wiz.com
rootmaster# chypdom -I wiz.com.
```
The above example changes the domain name of the root master server from strange.domain to wiz.com. When changing or establishing a domain name, make sure that the it has at least two labels; for example, wiz.com instead of wiz.

Note: Do not include a trailing dot for the domain name in this instance. The domainname command is not an NIS+ command and does not follow the NIS+ convention of appending a dot to domain names.

(More complete instructions are provided in Specifying a Domain Name After Installation.)
Check the root master server's /etc/irs.conf file.

Now kill and restart keyserv as shown below.

rootmaster# stopsrc -s keyserv
rootmaster# startsrc -s keyserv

Clean out leftover NIS+ material and processes.
If the workstation you are working on was previously used as an NIS+ server or client, remove any files that might exist in /var/nis and kill the cache manager, if it is still running. In this example, a cold-start file and a directory cache file still exist in /var/nis:
```
rootmaster# stopsrc -g nisplus
rootmaster# rm -rf /var/nis/*
```
If running in NIS-compatibility mode, also enter the following command:
```
rootmaster# rm -rf /var/yp/ypdomain
```
This step makes sure files left in /var/nis or directory objects stored by the cache manager are completely erased so they do not conflict with the new information generated during this setup process. If you have stored any admin scripts in /var/nis, you may want to consider temporarily storing them elsewhere, until you finish setting up the root domain.
Kill server daemons.
If the workstation you are working on was previously used as an NIS+ server, check to see if rpc.nisd or rpc.nispasswdd is running. If either of these daemons is running, kill them.
Name the root domain's admin group.
Although you wo not actually create the admin group until later, you must identify it now. Identifying it now ensures that the root domain's org_dir directory object, groups_dir directory object, and all its table objects are assigned the proper default group when they are created.

To name the admin group, set the value of the environment variable NIS_GROUP to the name of the root domain's admin group.
```
rootmaster# NIS_GROUP=admin.wiz.com.
rootmaster# export NIS_GROUP
```
Create the root directory and initialize the root master server.
This step creates the first object in the namespace--the root directory--and converts the workstation into the root master server. Use the nisinit -r command, as shown below. (This is the only instance in which you will create a domain's directory object and initialize its master server in one step. In fact, nisinit -r performs an automatic nismkdir for the root directory. In any case except the root master, these two processes are performed as separate tasks.)
```
rootmaster# nisinit -r 
 
This machine is in the wiz.com. NIS+ domain
Setting up root server ...
All done.
```
A UNIX directory with the name /var/nis/data is created.

Within the /var/nis directory is a file named root.object.
```
rootmaster# ls -l /var/nis/data 
-rw-rw-rw- 1 root other 384 date  root.object
```
This is not the root directory object; it is a file that NIS+ uses to describe the root of the namespace for internal purposes. The NIS+ root directory object will be created later in this procedure, then other files will be added beneath the directory. Although you can verify the existence of these files by looking directly into the directory, NIS+ provides more appropriate commands. They are called out where applicable in the following steps.

Attention: Do not rename the /var/nis or /var/nis/data directories or any of the files in these directories that were created by nisinit or any of the other NIS+ setup procedures.
[NIS-Compatibility only] Start the NIS+ daemon with -Y.
Perform this step only if you are setting up the root domain in NIS-compatibility mode. This step includes instructions for supporting the DNS forwarding capabilities of NIS clients.
Use mk_nisd with the -I, -B, or -N option.
Note: Read the command description for mk_nisd and decide which option you should use before continuing with this procedure.

For NIS compatibility with DNS forwarding, use:
```
rootmaster# mk_nisd -y -b [-I|-B|-N]
```
For NIS compatibility without DNS forwarding, use:
```
rootmaster# mk_nisd -y [-I|-B|-N]
```
To start the NIS+ daemon without NIS compatibility or DNS forwarding, use:
```
rootmaster# mk_nisd [-I|-B|-N]
```
Verify that the root objects have been properly created.
At this point in the procedure, your namespace should have:
- A root directory object (root.dir)
- A root master server (rootmaster) running the NIS+ daemon (rpc.nisd)
- A cold start file for the master server (NIS_COLD_START)
- A transaction log file (trans.log)
- A table dictionary file (data.dict).
The root directory object is stored in the /var/nis/data directory. Use the ls command to verify that it is there.
```
rootmaster# ls -l /var/nis/data
-rw-rw-rw-  1 root  other  384  date  root.object
-rw-rw-rw-  1 root  other  124  date  root.dir
```
At this point, the root directory is empty; in other words, it has no subdirectories. You can verify this by using the nisls command.
```
rootmaster# nisls -l wiz.com.
wiz.com.:
```
However, it has several object properties, which you can examine using niscat -o:
```
rootmaster# niscat -o wiz.com. 
Object Name  : wiz
Owner     : rootmaster.wiz.com.
Group     : admin.wiz.com.
Domain    : com.
Access Rights : r---rmcdrmcdr---
.
.
.
```
Note that the root directory object provides full (read, modify, create, and destroy) rights to both the owner and the group, while providing only read access to the world and nobody classes. (If your directory object does not provide these rights, you can change them using the nischmod command.)

To verify that the NIS+ daemon is running, use the ps command.
```
rootmaster# ps -ef | 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
```
The root domain's NIS_COLD_START file, which contains the IP address (and, eventually, public keys) of the root master server, is placed in /var/nis. Although there is no NIS+ command that you can use to examine its contents, its contents are loaded into the server's directory cache (NIS_SHARED_DIRCACHE). You can examine those contents with the /usr/lib/nis/nisshowcache command.

Also created are a transaction log file (trans.log) and a dictionary file (data.dict). The transaction log of a master server stores all the transactions performed by the master server and all its replicas since the last update. You can examine its contents by using the nislog command. The dictionary file is used by NIS+ for internal purposes; it is of no interest to an administrator.
Create the root domain's subdirectories and tables.
This step adds the org_dir and groups_dir directories, and the NIS+ tables, beneath the root directory object. Use the nissetup utility. For an NIS-compatible domain, be sure to include the -Y flag.

NIS-compatible only:
```
rootmaster# /usr/lib/nis/nissetup -Y
```
Standard NIS+ only:
```
rootmaster# /usr/lib/nis/nissetup
```
Each object added by the utility is listed in the output:
```
rootmaster# /usr/lib/nis/nissetup
org_dir.wiz.com. created
groups_dir.wiz.com. created
auto_master.org_dir.wiz.com. created
auto_home.org_dir.wiz.com. created
bootparams.org_dir.wiz.com. created
cred.org_dir.wiz.com. created
ethers.org_dir.wiz.com. created
group.org_dir.wiz.com. created
hosts.org_dir.wiz.com. created
mail_aliases.org_dir.wiz.com. created
sendmailvars.org_dir.wiz.com. created
client_info.org_dir.wiz.com. created
netmasks.org_dir.wiz.com. created
netgroup.org_dir.wiz.com. created
networks.org_dir.wiz.com. created
passwd.org_dir.wiz.com. created
protocols.org_dir.wiz.com. created
rpc.org_dir.wiz.com. created
services.org_dir.wiz.com. created
timezone.org_dir.wiz.com. created
```
The -Y option creates the same tables and subdirectories as for a standard NIS+ domain, but assigns read rights to the passwd table to the nobody class so that requests from NIS clients, which are unauthenticated, can access the encrypted password in that column.

Recall that when you examined the contents of the root directory with nisls, it was empty. Now, however, it has two subdirectories.
```
rootmaster# nisls wiz.com.
wiz.com.:
org_dir
groups_dir
```
You can examine the object properties of the subdirectories and tables by using the niscat -o command. You can also use the niscat option without a flag to examine the information in the tables, although at this point they are empty.
Create DES credentials for the root master server.
The root master server requires DES credentials so that its own requests can be authenticated. To create those credentials, use the nisaddcred command as shown below. When prompted, enter the server's root password.
```
rootmaster# nisaddcred des 
DES principal name: unix.rootmaster@wiz.com
Adding key pair for unix.rootmaster@wiz.com 
           (rootmaster.wiz.com.).
Enter login password:
Wrote secret key into /etc/.rootkey 
```
If you enter a password that is different from the server's root password, you will get a warning message and a prompt to repeat the password:
```
Enter login password: 
nisaddcred: WARNING: password differs from login password.
Retype password:
```
You can persist and retype the same password, and NIS+ will still create the credential. The new password will be stored in /etc/.rootkey and used by the keyserver when it starts up. To give the keyserver the new password right away, run keylogin -r, as described in Administering NIS+ Credentials.

If you decide to use your login password after all, press Control-c and start the sequence over. If you were to simply retype your login password as encouraged by the server, you would get an error message designed for another purpose, but which in this instance could be confusing.
```
nisaddcred: WARNING: password differs from login password.
Retype password: 
nisaddcred: password incorrect.
nisaddcred: unable to create credential.
```
As a result of this step, the root server's private and public keys are stored in the root domain's cred table (cred.org_dir.wiz.com.) and its secret key is stored in /etc/.rootkey. You can verify the existence of its credentials in the cred table by using the niscat command. Since the default domain name is wiz.com., you do not have to enter the cred table's fully qualified name; the org_dir suffix is enough. You can locate the root master's credential by looking for its secure RPC netname.
Create the root domain's admin group.
This step creates the admin group that was named earlier in this procedure. Use the nisgrpadm command with the -c option. The example below creates the admin.wiz.com. group.
```
rootmaster# nisgrpadm -c admin.wiz.com. 
Group admin.wiz.com. created.
```
This step only creates the group--it does not identify its members. To observe the object properties of the group, use niscat -o, but be sure to append groups_dir in the group's name.
```
rootmaster# niscat -o admin.groups_dir.wiz.com. 
Object Name  : admin
Owner     : rootmaster.wiz.com.
Group     : admin.wiz.com.
Domain    : groups_dir.wiz.com.
Access Rights : ----rmcdr---r---
Time to Live : 1:0:0
Object Type  : GROUP
Group Flags  :
Group Members :
```
Add the root master to the root domain's admin group.
Since at this point the root master server is the only NIS+ principal that has DES credentials, it is the only member you should add to the admin group. Use the nisgrpadm command again, but with the -a option. The first argument is the group name, the second is the name of the root master server. This example adds rootmaster.wiz.com. to the admin.wiz.com. group.
```
rootmaster# nisgrpadm -a admin.wiz.com. rootmaster.wiz.com.
Added rootmaster.wiz.com. to group admin.wiz.com.
```
To verify that the root master is indeed a member of the group, use the nisgrpadm command with the -l option (see Administering NIS+ Groups).

Note: With group-related commands such as nisgrpadm, you do not have to include the groups_dir subdirectory in the name. You need to include that directory with commands like niscat because they are designed to work on NIS+ objects in general. The group-related commands are "targeted" at the groups_dir subdirectory.
```
rootmaster# nisgrpadm -l admin.wiz.com. 
Group entry for admin.wiz.com. group:
  Explicit members:
    rootmaster.wiz.com.
  No implicit members
  No recursive members
  No explicit nonmembers
  No implicit nonmembers
  No recursive nonmembers
```
Update the root domain's public keys.
Normally, directory objects are created by an NIS+ principal that already has DES credentials. In this case, however, the root master server could not acquire DES credentials until after it created the cred table (since there was no parent domain in which to store its credentials). As a result, three directory objects--root, org_dir, and groups_dir--do not have a copy of the root master server's public key. (You can verify this by using the niscat -o command with any of the directory objects. Look for the public key field. Instructions are provided in Administering NIS+ Directories.

To propagate the root master server's public key from the root domain's cred table to those three directory objects, use the /usr/lib/nis/nisupdkeys utility for each directory object.
```
rootmaster# /usr/lib/nis/nisupdkeys wiz.com. 
rootmaster# /usr/lib/nis/nisupdkeys org_dir.wiz.com.
rootmaster# /usr/lib/nis/nisupdkeys groups_dir.wiz.com.
```
After each instance, you will see a confirmation message such as this one:
```
Fetch Public key for server rootmaster.wiz.com.
 netname = 'unix.rootmaster@wiz.com.'
Updating rootmaster.wiz.com.'s public key.
  Public key:
```
Now, if you look in any of those directories (use niscat -o), you will see this entry in the public key field:
```
Public key: Diffie-Hellman (192 bits)
```
Start the NIS+ cache manager.
The cache manager maintains a local cache of location information for an NIS+ client (in this case, the root master server). It obtains its initial set of information from the client's cold-start file and downloads it into a file named NIS_SHARED_DIRCACHE in /var/nis.

To start the cache manager, simply enter the nis_cachemgr command as shown below.
```
rootmaster# startsrc -s nis_cachemgr
```
Once the cache manager has been started, you have to restart it only if you have explicitly killed it. You do not have to restart it if you reboot, since the NIS_COLD_START file in /var/nis starts it automatically when the client is rebooted. For more information about the NIS+ cache manager, see Administering NIS+ Directories.
Stop the NIS+ daemon. (See the rm_nisd command description for more information.
```
rootmaster# stopsrc -s rpc.nisd
```
Restart the NIS+ daemon with security level 2.
Now that the root master server has DES credentials and the root directory object has a copy of the root master's public key, you can restart the root master with security level 2 (the default).

Standard NIS+ domain only
```
rootmaster# startsrc -s rpc.nisd
```
For an NIS-compatible root domain, be sure to use the -Y flag:
```
rootmaster# startsrc -s rpc.nisd -a "-Y"
```
For NIS-compatible NIS+ domain and DNS forwarding, use the -Y and -B flags:
```
rootmaster# startsrc -s rpc.nisd -a "-Y -B"
```
Attention: Operational networks with actual users should always be run at security level 2. Security levels 0 and 1 are for setup and testing purposes only. Do not run an operational network at level 0 or 1 or you will be running in an unsecured NIS+ environment.
Add your LOCAL credentials to the root domain.
Since you do not have access rights to the root domain's cred table, you must perform this operation as superuser. In addition, the root master's /etc/passwd file must contain an entry for you. Use the nisaddcred command with the -p and -P flags as shown below.
```
nisaddcred -p uid -P principal-name local 
```
The principal-name consists of the administrator's login name and domain name. This example adds a LOCAL credential for an administrator with a UID of 11177 and an NIS+ principal name of topadmin.wiz.com.
```
rootmaster# nisaddcred -p 11177 -P topadmin.wiz.com. local
```
For more information about the nisaddcred command, see Administering NIS+ Credentials.
Add your DES credentials to the root domain.
Use the nisaddcred command again, but with the following syntax:
```
nisaddcred -p SecureRPC-netname -P principal-name des
```
The SecureRPC-netname consists of the prefix UNIX followed by your UID, the symbol @, and your domain name, but without a trailing dot. The principal-name is the same as for LOCAL credentials: your login name followed by your domain name, with a trailing dot.
```
rootmaster# nisaddcred -p unix.11177@wiz.com -P topadmin.wiz.com. des 
Adding key pair for unix.11177@wiz.com (topadmin.wiz.com.).
Enter login password: 
```
If after entering your login password you get a password differs from login password warning and yet the password you entered is your correct login password, ignore the error message. The message appears because NIS+ cannot read the protected /etc/passwd file that stores the password, as expected. The message would not have appeared if you had no user password information stored in the /etc/passwd file.
Add credentials for other administrators.
Add the credentials, both LOCAL and DES, of the other administrators who will work in the root domain.
- One way is to ask the other administrators to add their own credentials. However, they will have to do this as superuser. Here is an example that adds credentials for an administrator with a user ID of 33355 and a principal name of miyoko.wiz.com.
```
rootmaster# nisaddcred -p 33355 -P miyoko.wiz.com. local 
rootmaster# nisaddcred -p unix.33355@wiz.com -P miyoko.wiz.com. des
Adding key pair for unix.33355@wiz.com (miyoko.wiz.com.).
Enter login password: 
```
- Another way is for you to create temporary credentials for the other administrators, using dummy passwords. (Note that the other administrator, in this example miyoko, must have an entry in the NIS+ passwd table. If no such entry exists you must first create one with nistbladm. The example below includes that step.)
```
rootmaster# nistbladm -D owner=miyoko.wiz.com. name=miyoko uid=33355 \
  gcos=miyoko home=/home/miyoko shell=/bin/tcsh passwd.org_dir
rootmaster# nisaddent -a -f /etc/passwd.xfr passwd 
rootmaster# nisaddent -a -f /etc/shadow.xfr shadow
rootmaster# nisaddcred -p 33355 -P miyoko.wiz.com. local
rootmaster# nisaddcred -p unix.33355@wiz.com -P miyoko.wiz.com. des
Adding key pair for unix.33355@wiz.com (miyoko.wiz.com.).
Enter miyoko's login password:
nisaddcred: WARNING: password differs from login passwd.
Retype password: 
rootmaster# nischown miyoko.wiz.com. '[name=miyoko],passwd.org_dir'
```
  In this case, the first instance of nisaddent populates the passwd table--except for the password column. The second instance populates the shadow column. Each administrator can later change his or her network password using the chkey command. Administering NIS+ Credentials describes how to do this.
Add yourself and other administrators to the root domain's admin group.
You do not have to wait for the other administrators to change their dummy passwords to perform this step. Use the nisgrpadm command with the -a option. The first argument is the group name, the remaining arguments are the names of the administrators. This example adds two administrators, topadmin and miyoko, to the admin.wiz.com. group:
```
rootmaster# nisgrpadm -a admin.wiz.com. topadmin.wiz.com. miyoko.wiz.com. 
Added topadmin.wiz.com. to group admin.wiz.com.
Added miyoko.wiz.com. to group admin.wiz.com.
```

Root Domain Setup Summary

The following table summarizes the steps requires to set up a root domain. The summary assumes a simple case. Be sure you are familiar with the complete task descriptions before you use this summary as a reference. This summary does not show the server's responses to each command.

Setting Up a Root Domain: Command Summary
Tasks	Commands
Log in as superuser to rootmaster.	rootmaster% su Password:
Check domain name	# domainname
Remove leftover NIS+ material.	# rm -rf /var/nis* If running in NIS-compatible mode, also remove NIS domain: # rm -rf /var/yp/ypdomain
Name the admin group.	# NIS_GROUP=admin.wiz.com.;export NIS_GROUP
Initialize the root master. [NIS-compatibility with DNS forwarding only] Start daemon with -Y -B, S 0. [NIS+ Only] Start daemon with -S 0.	# nisinit -r # startsrc -s rpc.nisd -a "-Y -B -S 0" or # startsrc -s rpc.nisd -a "-S 0"
Create org_dir, groups_dir, tables.	# /usr/lib/nis/nissetup [-Y]
Create DES credentials for root master.	# nisaddcred des Enter login password:
Create admin group.	# nisgrpadm -c admin.wiz.com.
Assign full group rights to root directory	# nischmod g+rmcd wiz.com.
Add root master to admin group.	# nisgrpadm -a admin.wiz.com. rootmaster.wiz.com.
Update root directory's keys.	# /usr/lib/nis/nisupdkeys wiz.com.
Update org_dir's keys.	# /usr/lib/nis/nisupdkeys org_dir.wiz.com.
Update groups_dir's keys.	# /usr/lib/nis/nisupdkeys groups_dir.wiz.com.
Start NIS+ cache manager	# startsrc -s nis_cachemgr
Kill existing NIS+ daemon.	# stopsrc -s rpc.nisd
Restart the NIS+ daemon. Use -y for NIS compatibility and -b for DNS forwarding.	# mk_nisd [-y] [-b][-I\|-B\|-N]
Add your LOCAL credentials.	# nisaddcred -p 11177 -P topadmin.wiz.com. local
Add your DES credentials.	# nisaddcred -p unix.11177@wiz.com \ -P topadmin.wiz.com. des Enter login password:
Add credentials for other admins. Add other admins to admin group.	# nisaddcred ... # nisgrpadm -a admin.wiz.com. member ...