5.3 Upgrading NICI

5.3.1 Version Upgrades and Compatibility

You upgrade NICI by installing a newer version of NICI on top of an existing NICI installation. Always upgrade NICI by using its install program. Freely copying NICI modules often results in a chaotic system, and consequences of such an action often cause irreparable damage to the system and other products such as PKI, Novell SecretStore/Single Sign-On, NMAS, eDirectory, and others.

Applications developed for NICI 1.x are not compatible with newer NICI versions (2.x or later). To provide backward compatibility, NICI 1.x on Windows platforms can coexist with newer NICI versions. If you want to keep this coexistence, always install the newer version after the old version of NICI. For example, install NICI 2.4 after NICI 1.5.7.

Reinstalling NICI does not destroy existing keys. Except on NetWare, the NICI 2.0 or later install does not require rebooting the server in most instances. However, if the NICI module (DLL or .so) is in use and can’t be overwritten by the install program, a reboot might be necessary.

5.3.2 Upgrading NICI on NetWare

As part of the NetWare upgrade wizard utility, the NICI team provides an NLM (nuwnici.nlm) to encrypt and transfer NICI configuration files from one physical server to another. The encrypted files are written to a floppy diskette, and the floppy is physically transported to the target server. nuwnici.nlm can also be used as a standalone NICI transfer utility. It has multiple phases. The first phase (Phase 1) is executed on the target (new) server. Phase 2 is executed on the source (old) server. Phase 3 is executed on the target (new) server. After phase 3 is completed, the target (new) server must be rebooted for the transfer to take effect.

There is also a phase 4 executed on the target (new) server. Phase 4 is basically a tool to check if NICI is working properly on the new server after the reboot.

A help screen is displayed by using the -h command line option.

On platforms other than NetWare, copying the NICI configuration files to the new box transfers NICI keys and keying materials to the new server.

If you do this, we highly recommend that you delete the NICI configuration on the old server.

5.3.3 Upgrading NICI to Version 2.7.0 on Linux, Solaris, or AIX Systems

When upgrading a version of NICI prior to v2.7.0 to NICI v2.7.0 or later on Linux and UNIX platforms, you must first remove the existing NICI installation. For example, if you are upgrading NICI from version 2.6.0 to version 2.7.0, you must first uninstall 2.6.0 before installing 2.7.0. However, if you are upgrading NICI from NICI v2.7.0 or later, you can install the new version on top of the existing version. For example, if you are upgrading NICI from version 2.7.4 to version 2.7.5, you can install 2.7.5 on top of 2.7.4.

A hybrid version of NICI (mixing features of NICI 1.2 and NICI 1.5) was shipped with eDirectory 8.5. In order to migrate the NICI configuration files from the hybrid version to 2.x, an upgrade utility (runf2dc) is provided.

If a Linux, Solaris, or AIX server is hosting more than one eDirectory, each eDirectory instance typically has its own NICI directory setup. Both instances of NICI configuration files must be migrated with the provided tool. For instance, assume two eDirectory instances run on a single Solaris host in the /var/nds1 and /var/nds2 directories, respectively. The runf2dc tool must be run on both the /var/nds1/nici and /var/nds2/nici directories to migrate each instance separately.

Materials in the NICI configuration files don’t depend on the contents of eDirectory files. Instead, encrypted data in eDirectory depends on keys stored in NICI configuration files. This encrypted data (such as user private keys, certificates, secret store data, and NMAS store data) is not available if NICI files are not migrated properly.

We strongly recommend running each instance of eDirectory on the same host with different user IDs to separate their cryptographic materials using the host system’s security mechanisms. NICI does not require a special user to run, except for installation, when a privileged user who can install setuid programs must install NICI (a one-time operation).