Novell is now a part of Micro Focus

Upgrading from iChain 1.5 to 2.0

Articles and Tips: article

Neil Cashell
iChain Escalation Engineering
Novell, Inc.

Nicolas Barcet
Solution Architect
Novell, Inc.

01 Apr 2002

This AppNote outlines the recommended process for upgrading from Novell iChain 1.5 to version 2.0. It describes each step in the process, and then tells where to find information about the differences in the eDirectory schema in the new version of iChain.


directory-enabled applications, iChain, upgrades


Novell iChain 2.0


network administrators, consultants, integrators



Prerequisite Skills

familiarity with iChain 1.5

Operating System




Sample Code



Novell iChain 2.0 provides identity-based Web security services that control access to application and network resources across technical and organizational boundaries. iChain separates security from individual applications and Web servers, enabling single-point, policy-based management of authentication and access privileges throughout the Net.

This AppNote outlines the steps in upgrading from iChain 1.5 to 2.0, which are:

  • Prepare the current iChain 1.5 platform

  • Back up the existing iChain 1.5 configuration

  • Upgrade eDirectory with the iChain 2.0 schema

  • Install ConsoleOne 1.3 and the iChain snap-ins

  • Convert and modify existing ACL/ISO object definitions

  • Upgrade the ICS box to iChain 2.0

  • Test the upgrade and implement new features

This AppNote explains each of these steps and provides a list of the eDirectory schema differences between iChain 1.5 and 2.0.

Preparing the Current iChain 1.5 Platform

Before upgrading iChain, you should make sure that the current system is fully operational. To do this, prepare a test scenario. Identify key profiles for all applications. Make a note of what each application requires as input (simple authentication header, parameters passed via the command line, and so on).

Run the test scenario on the existing iChain 1.5 system and confirm that everything is working fine.

Note: iChain 2.0 OLAC parameters can be passed via the URL or HTTP header (query string is still the default). Make sure that the application and OLAC setup are in sync regarding the way in which the data is being passed.

Backing Up the Existing iChain 1.5 Configuration

Follow these steps to back up your existing iChain 1.5 system.

Authentication Server

Start by backing up the Authentication Server.

  1. Perform a backup of eDirectory.

  2. Export to LDIF all of the iChain objects (ACL, ISO, Communities).

  3. Back up any custom tools or modules that you may have been running on the Authentication Server.

  4. If you have ConsoleOne v2.1x installed, rename the ConsoleOne directory. (The iChain 2.0 Authentication Server CD ships with ConsoleOne v1.3). If this is not an option, rename the iChain snap-in and library directories.

iChain ICS Server

Next, back up the iChain ICS Server.

  1. Export the ICS configuration to a NAS file and save it as CURRENT.NAS on a floppy diskette.

  2. Capture screen shots of all the ICS configuration screens.

  3. Export or back up certificates that are being used by the Proxy Server.

    Note: Certificates can only be backed up if they were created with the PKI snap-ins that were used in the iChain 1.5 FP2 patch.

  4. Back up the following files:

    • /etc/hosts - contains host mappings to IP addresses

    • /etc/proxy/data - contains custom login pages (ca*.html)

    • /ichain/oac/ - contains OLAC configuration settings

    • /etc/proxy/r_append.cfg - if any DNS search types have changed

    • /system/appstart.ncf

    • /system/tune.ncf

  5. Copy any tools or modules that you may have used from the server (for example, LSEARCH.NLM for LDAP testing and NETMON.NLM for taking traces).

Other Backup Tips

If at all possible, add an extra disk to the ICS box so that the iChain 1.5 installation can remain untouched while the iChain 2.0 installation is executed. Also, it is a good idea to create a clone image of the iChain 1.5 build on the server before doing the upgrade. Make sure you have everything you need to restore a valid iChain 1.5 ICS image, should something go wrong during the upgrade.

The iChain 2.0 schema is compatible with the previous 1.5 schema. This means that if you leave your 1.5 ISO object untouched, you could have one proxy box running 1.5 while a second one is being upgraded. This could be helpful in doing a seemless migration and allows for an easy rollback should that be necessary.

Note: When upgrading from iChain 1.5 to 2.0, verify that the "SET cache readahead" parameter is set to Off on the ICS box. Having this parameter set to On in iChain 2.0 will cause the server to Abend!

Upgrading eDirectory with the iChain 2.0 Schema

The next step is to upgrade Novell eDirectory with the iChain 2.0 schema. This is done via the iChain 2.0 Install CD.

The install script will generate many BURP errors during this phase. You can simply ignore these errors, as they are due to the fact that many of the modifications to the schema that the install script is trying to perform are already in place.

Note: If the tree you are upgrading also contains BorderManager schema extensions, you will need to manually re-link the "brdsrvsOutgoingAcl" attribute with the object class named "brdsrvsACLRule". This is easily done in ConsoleOne's Schema Manager after you have applied the new schema and reloaded ConsoleOne.

Installing ConsoleOne 1.3 and the iChain Snap-ins

If you don't already have ConsoleOne 1.3 installed, along with the iChain snap-ins from the Authorization Server CD, do so now. This is required for any Radius or token-based authentication setup. Note that you must have Novell International Cryptographic Infrastructure (NICI) version 1.5x-the setup will fail with NICI 2.0.x!

Converting and Modifying ACL/ISO Object Definitions

The ConsoleOne snap-ins that ship with iChain 2.0 can detect objects that were formatted with iChain 1.5. After you have upgraded the Authentication Server from 1.5 to 2.0 and selected the properties of the original 1.5 ISO object with the new 2.0 snap-ins, you will be presented with the screen shown in Figure 1, asking whether you want the 1.5 ISO objects to be upgraded.

Prompt to upgrade iChain 1.5 ISO objects.

If you answer "Yes" here, the ISO attributes will be converted to 2.0 format in which the ISO access mode will default to "Secure". That means users will need to authenticate and be authorized before they can access the protected resource at the origin server.

Once the conversion is completed, you can modify the resources if needed. Figure 2 shows the screen for modifying an existing protected resource.

The Modify Existing Protected Resource window.

If you answer "No" to the prompt in Figure 1, the object will remain as an iChain 1.5 protected resource. The resources on this iChain service object will continue to function as they did in iChain 1.5. For backwards compatibility, you should make all changes to the protected resources with the iChain 1.5 snap-ins.

Here are two items to note if you decide to create completely new objects:

  • The ISO object has many new attributes in iChain 2.0. The most important of these involves the protected resource mode (public, secure, or protected). Also, you need to add "/*" to the end of the protected resource definition in order to access resources in all subdirectories.

  • If you decide to recreate a deleted ISO object, the corresponding Role Objects that reference the old ISO's protected resources must be recreated as well. If this is not done, ACLCHECK will report "rules are of old version" errors.

Upgrading the ICS Box to iChain 2.0

You are now ready to perform the actual iChain 1.5 to 2.0 upgrade on the ICS box. To do this, follow these steps:

  1. Image the ICS box with iChain 2.0.

  2. Unlock the ICS system console by typing "UNLOCK <Enter>" at the console prompt. You don't need to specifiy a password.

  3. Import the NAS file you created earlier by inserting the diskette containing the CURRENT.NAS file into the ICS box's floppy drive and typing "IMPORT FLOPPY <Enter>" at the console prompt. Wait until you see the "Completed execution of autoload" message displayed at the server console before proceeding.

  4. Import the server certificates that you backed up from the iChain 1.5 server.

    If you encounter problems accessing the ICS GUI utility, do the following from the Internet Caching System console:

    • Run the _kill application command to kill the Java ServerApplication thread and all support modules.

    • At the system console, unload CERT.NLM and then reload it.

    • Execute APPSTART.NCF at the system console.

  5. Restore the files you backed up in previous steps. The OAC.PROPERTIES file will not be needed unless some non-default parameters (such as increasing worker threads, synchronization interval, and so on) were required for functionality in iChain 1.5.

  6. Using the ICS GUI utility, run the health check to make sure all services are up and running.

  7. Check to see whether the eDirectory server still has community objects (which do not ship with iChain 2.0) and rules based on community objects. If so, modify the APPSTART.NCF file to load ACLCHECK with the /M option. (iChain 2.0 has experienced a few abends with this /M option. A patch should be released soon to fix this problem. Check the Novell Support Connection Web site at for the latest iChain patches.)

  8. Verify that you can access the iChain protected resources from a browser.

Testing the Upgrade and Implementing New Features

After the upgrade, perform an offline test using the scenario you defined earlier. Perform an onsite production test when the system goes back online.

Only when the old iChain features are confirmed as working should you start enabling the new iChain 2.0 features!

Schema Differences Between iChain 1.5 and 2.0

To obtain an LDIF file containing a list of schema definitions for iChain 2.0, which includes changes made since iChain 1.5, download the file named ICHAIN20.TXT from the AppNotes download link at:


This AppNote has given the procedure for upgrading from iChain 1.5 to 2.0. For additional information about Novell iChain, refer to the following resources:

* Originally published in Novell AppNotes


The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates