Cisco CNS Network Registrar Installation Guide, 6.0
Installing Network Registrar on Linux
Downloads: This chapterpdf (PDF - 249.0 KB) The complete bookPDF (PDF - 794.0 KB) | Feedback

Installing Network Registrar on Linux

Table Of Contents

Installing Network Registrar on Linux

Installation Checklist

System Requirements

Installation and Upgrade

License Key

Uninstalling Network Registrar

Reverting to an Earlier Release

Reverting an Archived Installation

Reverting an Unarchived Installation

Starting and Stopping the Servers

Installing Network Registrar on Linux

This chapter describes how to install Cisco CNS Network Registrar on a Linux system. The topics are:

Installation Checklist

System Requirements

Installation and Upgrade

License Key

Uninstalling Network Registrar

Reverting to an Earlier Release

Starting and Stopping the Servers

Troubleshooting a Failed Installation

Installation Checklist

Before you run the installation program, check these:

System requirements

New software license key

Administrative privileges

Desired installation location

Choice of new installation or upgrade

Choice of client-and-server or client-only installation

Java location

Choice of HTTP or secure HTTPS Web UI login

System Requirements

To run Network Registrar on Red Hat Linux 7.3 requires:

System running Pentium III or better

512 MB of RAM is suggested

Minimum of 310 MB of disk space is required for installation

Red Hat Linux 7.3 (kernel version 2.4), with Red Hat Package Manager (RPM) 4.0.4

Java Runtime Environment (JRE) version 1.3.1 or later, or equivalent Java Development Kit (JDK)

Installation and Upgrade

A new installation and an upgrade from a previous release follow essentially the same process, except that the upgrade includes a few additional steps. If Network Registrar release 5.5, 5.0 or 3.5 is already installed, you can upgrade to release 6.0 while preserving the earlier configuration, or you can replace the configuration. The steps for an installation and upgrade are:

Step 1 To prepare for the installation or upgrade:

a. Obtain the new software license key for this release—You cannot use a previous one.

b. Log on to the target machine with the su username and the root password as superuser.

c. Download and install the Java Runtime Environment (JRE) or Development Kit (JDK), version 1.3.1 or later, available from Sun Microsystems at their website. If you accept the default location during the Java installation, it differs for each of these recent Java versions:

JRE 1.3.1—/javasoft/jre/1.3.1_0x—go to substep (d)

JDK 1.3.1—/jdk1.3.1_0x—go to substep (d)

JRE 1.4.1—/java/j2re1.4.1_0x—go to substep (e)

JDK 1.4.1—/j2sdk1.4.1_0x—go to substep (e)

Each of these installation paths are referred to as JAVA_HOME in each of the subsequent steps. If you are not configuring secure login to the Web UI, go to Step 2.

d. If you installed the JRE or JDK version1.3.1 and want to configure secure login to the Web UI, you must also download and install the Java Secure Socket Extension (JSSE) version 1.0.2 or later, available from Sun Microsystems at their website. The default installation location is /jsse1.0.2.

e. If you are configuring secure login to the Web UI, you must create a keystore file using the Java keytool utility, located in the JAVA_HOME/bin directory. This utility defines a self-signed certificate or points to a file for a certificate that you obtained from an external signing authority:

To create a keystore file containing a self-signed certificate that is valid for one year, run this command and respond to the prompts:

> JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -validity 365 
	-keystore keystore-file 
Enter keystore password: changeit 
What is your first and last name? 
	[Unknown]: john doe 
What is the name of your organizational unit? 
	[Unknown]: engineering 
What is the name of your organization? 
	[Unknown]: example company 
What is the name of your City or Locality? 
	[Unknown]: boston 
What is the name of your State or Province? 
	[Unknown]: ma 
What is the two-letter country code for this unit? 
	[Unknown]: us 
Is CN=john doe, OU=engineering, O=example company, L=boston, ST=ma, C=us correct? 
	[no]: yes 
Enter key password for <tomcat> 
	(RETURN if same as keystore password): 

To create a keystore file and import a certificate file that you obtained from an external signing authority, run this command and respond to the prompts:

> JAVA_HOME/bin/keytool -genkey -alias tomcat -file certificate.cer 
	-keystore keystore-file 

The keystore-file is the fully qualified path to the keystore file you are creating. You need to enter the keystore path and password in Step 9.

Caution The keystore password is included in the server.xml file in the install-path/tomcat/conf directory, which is protected to have root access only. Because the password is visible as plain text in this file, do not change the file permissions to have this file generally accessible.

Step 2 If you are installing from a CD-ROM, insert it in the CD-ROM drive or mount it from a remote server.

If you are installing from a network resource, locate the resource containing the image of the Network Registrar CD-ROM files.

If you are downloading the distribution file from a Cisco website, uncompress and unpack it:

a. You must have the gzip utility (to uncompress) and gtar utility (to unpack) installed and in the search path. See the GNU organization website for details.

b. Download the file.

c. Change to the directory where you want to unpack the file.

d. To uncompress and unpack a .gtar.gz file, use gtar with the -z option:

gtar -zxpf cnr_6_0-linux.gtar.gz 

To unpack a .gtar file that was already uncompressed using gunzip, omit the -z option:

gtar -xpf cnr_6_0-linux.gtar 

Step 3 Run the install_cnr program from the installation directory:

install-dir # ./install_cnr 

The install-dir is the directory on which the CD-ROM is mounted, in which you unpack the distribution file, or network resource from which you are installing.

Step 4 Respond to questions about where you want to install the executable, data, log, and temporary files. By default, the executables go to /opt/nwreg2, the data files to /var/nwreg2/data, the log files to /var/nwreg2/logs, and the temporary files to /var/nwreg2/temp. If the selected base directory does not already exist (/opt/nwreg2 by default), respond to whether you want it created.

For an upgrade, the process autodetects the locations from the previous release. Accept these values.

Step 5 These prompts appear only if you are upgrading from a previous release:

a. Respond to whether you want to upgrade the existing configuration database or create a new, empty one. Enter y to upgrade using the existing database (the default), or n to replace it with a new one. (If the upgrade process cannot determine the database version, a menu selection appears where you can enter the appropriate selection number.)

b. Respond to whether you want to archive the existing databases. Enter y to archive (the default), or n not to archive.

c. If you chose to archive the databases, enter an archive location outside the current installation directories. It should have enough disk space to accommodate all the files in the Network Registrar installation directory. The default is the /opt/nwreg2.sav directory.

Step 6 Respond to whether you want to install the server and client, or just the client. Enter 1 (the default) for a server-and-client installation; enter 2 for a server-only installation.

Step 7 Enter the number of the CCM management SCP port for internal communication between server and clients. Check the target system this port number; the default is 1234.

Step 8 Enter where the Java 1.3.1 (or later) JRE or JDK installation is located. The installation or upgrade process tries to detect this location.

If you install a new Java version or change its location, re-install Network Registrar, then enter the new location at this step.

Step 9 Select whether you want to enable the Web UI for nonsecure or secure login:

Enable the Web UI on an HTTP port

Enable the Web UI on a secure HTTPS port

Enable the Web UI on both HTTP and secure HTTPS ports

Do not enable the Web UI

Enabling the secure HTTPS port configures security for connecting to the Apache Tomcat version 4.0 webserver using a preconfigured Java Secure Socket Extension (JSSE) installation (see Step 1 for the configuration steps):

If you select the HTTP connection (the default setting), go to Step 10.

If you select the HTTPS connection (or both HTTP and HTTPS), these prompts also appear:

Enter the fully qualified path to where Java or the JSSE is installed. If you installed JRE or JDK version 1.3.1, you must enter the JSSE path. Use the location from Step 1(c) or (d).

Enter the fully qualified path to the keystore file that contains the certificate(s) to be used for the secure connection to the Apache Tomcat Web server. This is the keystore-file you specified in Step 1(e).

Enter the password given when creating the JSSE keystore file to provide the secure interface to clients. The default password is changeit.

If you select not to enable the Web UI, click Next, then go to Step 11.

Note To change from one type of login to another, re-install Network Registrar and change the selection at this step.

Step 10 Enter an available port number for the Web UI connection. The default for HTTP is 8080; the default for secure HTTPS is 8443. If you selected both connections, you must enter two port numbers.

Step 11 A number of processing messages appear, ending with notification that Network Registrar was successfully installed.

Step 12 To check the status of the Network Registrar servers, use the install-path/usrbin/aicstatus command. See the "Starting and Stopping the Servers" section.

License Key

To administer the cluster of Network Registrar servers that you installed, you must enter the license key that enables the user interfaces.

Caution Network Registrar 6.0 requires a totally new license key. You cannot use one from a previous release.

You can run the user interfaces and the servers on different machines. You must tell the user interface which cluster (group of servers that share a database) that you want to access and whether the cluster is on the local or a remote host.

The license that you have determines what to do and what can happen:

If you have a permanent license, you must enter it once for each cluster that you want to access through the user interface. Once entered, you are not prompted for a license key again until you install the cluster on another machine.

If you have an evaluation copy of Network Registrar, you have a license that expires.

If you have an invalid or expired license key, you cannot configure or manage the Network Registrar servers until you obtain a valid license key, although the servers will continue to function normally.

Step 1 Start the Network Registrar Web UI or CLI:

To access the Web UI, open the Web browser and use the HTTP (nonsecure login) or HTTPS (secure login) website:


The hostname is the target host's actual name. The port-at-install is the port specified during the installation (see Step 10). The HTTP and secure HTTPS connections have two different port numbers.

To start the CLI, enter:

# install-path/usrbin/nrcmd -C clustername -N admin -P changeme 

Step 2 Enter the su username and the root password to become the superuser.

Step 3 Enter the license key:

In the Web UI, enter the license key on the Add License page. Click Add.

In the CLI, enter this command:

nrcmd> license set key=keystring 

Uninstalling Network Registrar

To uninstall Network Registrar, use the uninstall_cnr program, then use the mcdshadow backup program to save the databases. See the Network Registrar User's Guide on how to back up the databases. You cannot convert the 6.0 databases back to the 5.5 databases.

Run the uninstall_cnr program:

install-directory# ./uninstall_cnr 
Stopping Server Agent...
Deleting startup files...
Removing Network Registrar...
cannot remove /opt/nwreg2/usrbin - directory not empty
cannot remove /opt/nwreg2/conf - directory not empty
package optnwreg2 not found in file index
Note that any files that have been changed (including your database) have _not_ been 
uninstalled. You should delete these files by hand when you are done with them, before you 
reinstall the package.

The "cannot remove" warnings means that, although the uninstall program removes the server and user interface components, it cannot delete the database and log files. You must delete these separately before you re-install Network Registrar. You might want to delete what is left in the binary, data, and log directories.

Note The uninstall process usually stops the Network Registrar AIC Server Agent first. If you find that the server processes are not shutting down, see the "Starting and Stopping the Servers" section.

Reverting to an Earlier Release

You can revert to Network Registrar version 5.5 from 6.0 based on whether you archived or did not archive the previous database during the upgrade process.

Reverting an Archived Installation

If you archived the installation before the upgrade, use these steps to revert to an earlier version:

Step 1 Locate your backup directory (/opt/nwreg2.sav by default).

Step 2 Stop Network Registrar, if it is running:

# /etc/rc.d/init.d/aicservagt stop 

Step 3 Back up any data, logs, or configurations from the Network Registrar 6.0 installation.

Step 4 Remove the Network Registrar 6.0 installation files. For example:

# rm -rf /opt/nwreg2 
# rm -rf /var/nwreg2 

Step 5 Change to the root directory of your installation drive as your working directory:

Step 6 Extract the previous installation from the saved archive, from the root directory. For example:

# tar xvf /opt/nwreg2.sav/cnr_archive.tar 

Step 7 Restart Network Registrar (see the "Starting and Stopping the Servers" section).

Note The Network Registrar version that is registered with the packaging system does not roll back. Although the previous release runs correctly, the system still indicates that the new release is installed.

Reverting an Unarchived Installation

If you did not save an archive, but have a backup copy of the previous installation, use these steps to revert to an earlier release:

Step 1 Archive the Network Registrar 6.0 database if you anticipate using it at a future date.

Step 2 Uninstall Network Registrar 6.0, as described in the "Uninstalling Network Registrar" section. The uninstall program does not remove the Network Registrar log and data files. However, it displays a list of the directories and files not being removed. Delete these files manually before installing the earlier version of Network Registrar.

Step 3 Re-install Network Registrar 5.5 as directed in the Network Registrar 5.5 Installation Guide.

Step 4 Stop Network Registrar (see the "Starting and Stopping the Servers" section).

Step 5 Recover the previous database, using the steps in Chapter 4 of the Network Registrar User's Guide.

Step 6 Change directories to the database directory.

Step 7 Run the keybuild tool to rebuild the key files (this can take several minutes):

# install-path/bin/keybuild mcddb 

Step 8 Run the dbcheck tool to verify the integrity of the database:

# install-path/bin/dbcheck mcddb 

Starting and Stopping the Servers

You can start and stop the Network Registrar servers (DNS, DHCP, and TFTP) from the Linux command line. If the installation completed successfully and you enabled the servers, the DNS and DHCP servers run automatically and start each time you reboot the machine.

For the TFTP server, you must use this CLI command to enable it to restart on bootup:

nrcmd> tftp enable start-on-reboot 

The AIC Server Agent is the first Network Registrar program to run each time the host boots, and is the last Network Registrar program to exit when you shut down the service. It controls loading and unloading each executable server program and initiates the service by starting each server.

To start the AIC Server Agent:

Step 1 Log in as superuser.

Step 2 Enter the aicservagt command with the start argument:

# /etc/rc.d/init.d/aicservagt start 

Step 3 Enter the aicstatus command to check that the servers are running:

# install-path/usrbin/aicstatus 

To stop the AIC Server Agent, perform the steps as in starting the agent, except enter the aicservagt command with the stop argument.

# /etc/rc.d/init.d/aicservagt stop 

The Network Registrar installation process creates a log file, cnr_install_log, in the Network Registrar log file directory. For upgrades, a second log file, mcdupgrade_log, is also created. By default, the log directory is set to /var/nwreg2/logs.

If the installation or upgrade does not complete successfully, first check the contents of these log files to help determine what might have failed. Examples of possible causes for failure are:

An incorrect version of Java installed

Insufficient available disk space available

Inconsistent data for an upgrade

If log messages do not clearly indicate the failure, you can gather additional debug information using the debug_install utility script. This script is located in the Network Registrar executables directory, by default, /opt/nwreg2.

If the cause of the failure still does not seem readily apparent or correctable, forward the output of this script to Cisco Systems for further analysis.