Novell is now a part of Micro Focus

How to Configure WebSphere, Oracle, NetWare Enterprise Web Server, and eGuide on a NetWare 5.1 Server

Articles and Tips: article

Kevin Burnett
Software Engineer
WW Partner Information & Training
kburnett@novell.com

01 Nov 2000


This AppNote addresses solutions to the problems encountered in developing a demonstration of NetWare 5.1-based technology for Brainshare 2000.

Introduction

The purpose of this AppNote is to describe the lessons learned in developing a demonstration of NetWare 5.1-based technology for Brainshare 2000. This article's primary value comes not from the description of the accomplishments, but rather from the description of the problems encountered and the solutions and work-arounds developed for those problems. It is intended that the information in this AppNote be used in two ways: 1) As a direct guide to help those attempting to set up WebSphere, Oracle 8I, or Novell Enterprise Web Server on NetWare 5.1 in avoiding the problems we faced; and 2) As a guide for product management and engineering in simplifying this process for our customers, partners, and developers.

Demonstration Platform

The demonstration showed technology to integrate a company's Website with NDS, using NetWare 5.1. In doing so, it showed the power and flexibility of the NetWare platform, together with the other bundled WebSphere and Oracle components.

Figure 1: The demonstration system.

As shown in Figure 1 data can be entered via eGuide and/or Console One to be stored in (NDS). This data is synchronized, depending on DirXML filtering, to the Oracle 8i database via the JDBC DirXML driver. For this example the data being transferred by the JDBC DirXML driver is synchronized to the IBM WebSphere table schemas located in the Oracle 8i database. This data can then be read by the WebSphere sample WEB application, YourCo, via the WebSphere server engine. Since the YourCo sample application is read-only, no data can be entered through it.

In order to interface with the WebSphere Engine, which runs on the NetWare 5.1 server, a Web Server is required. The Novell Enterprise Web Server, which ships with NetWare 5.1, was utilized for this demonstration.

To demonstrate the reverse flow of data, data can be entered directly into the WebSphere table schema via Oracle's SQL Plus utility. When you enter data via Oracle's SQL Plus directly into the WebSphere table schema(s), located in the Oracle database, a trigger is started that notifies the JDBC DirXML Driver to pick up the data. The data is then synchronized with NDS via the DirXML engine. The data can then be viewed via eGuide or Console One.

For this article, all components, NDS, Oracle 8i and WebSphere will be running on NetWare 5.1. In addition the JDBC DirXML driver will be running on NetWare 5.1 along with the DirXML engine. The WebSphere sample program, YourCo, along with eGuide will run on a NetWare 5.1 and be expressed through your favorite browser, via the Novell Enterprise Web Server.

NetWare 5.1, NDS, NetWare Enterprise Web Server, Oracle 8i, WebSphere and eGuide are currently shipping products, whose installation will be mentioned in this paper. The JDBC DirXML driver is currently under development. A prototype was used for BrainShare 2000 demo.

Installing NetWare, NDS, NetWare Enterprise Web Server, and WebSphere

Installing NetWare is a straightforward process that is well documented in the NetWare 5.1 documentation. Just make sure that you that you select WebSphere and NetWare Enterprise Web Server from the available product options. Installation of these products is then automatic. If something goes wrong during this installation process, the most generally accepted recourse is to re-start the installation.

The amount of RAM needed to run all of these applications is, at a minimum, 384MB. This is really pushing the limits of these applications. 512MB is better, with 1GB being best. In real world situations, 1 GB would be recommended. Additionally, the processor speed of the server should be at least 500mhz with a minimum of 10GB available on the hard drive.

Installing Oracle 8i

Installing Oracle 8i for NetWare is also a very straightforward process.

  1. Place the Oracle 8i server for NetWare in your server's CD-ROM drive.

  2. Mount the disc as a NetWare volume.

  3. Once mounted execute the Oracle installation program by typing the following on the server console:

    O8iNW:\ORASETUP

    • This will start an NCF file located on the Oracle disc to complete the Oracle installation. Selecting the defaults will be the most generally accepted method of installation.

  4. When prompted for the DBA password, enter a password.

  5. For the protocol select TCP/IP.

  6. Enter the IP address of the NetWare server.

    Do not install Oracle 8i through NWCONFIG.NLM, as this creates some race conditions, thus causing Oracle to fail installation. Most of the errors that occur, with the use of NWCONFIG, are Java errors produced from the Oracle install program.

Oracle provides two server-based utilities for interaction with the database. The first is SVRMGR31, which is a server-based implementation of the Oracle server manager. This utility allows interaction with the database via SQL commands. (This same type of utility is also available as a part of the Oracle 8i Client.) The second utility is NWDBM81.NLM, which is the Oracle 8i Manager. This utility allows you to manage Instance Information, which includes starting and stopping the database, initialization, sessions and backing up the control file, manage tables spaces, configure the server, and change instances.

You may want to install the Oracle 8i Client on your workstation. The client is compatible with Windows 95, 98 and NT. Like mentioned above, the Oracle 8i client allows you to interact with the database using SQL command. The Client disc also contains Oracle Development Help and the Oracle documentation.

Installing eGuide

Installation of Novell's eGuide is quite straightforward on any of the supported platforms. Since this article deals with the NetWare installation, that is what we will cover here.

Novell eGuide requires 8MB minimum of server memory to run. The installation is a quick and easy process. Since we have installed a Web Server on the NetWare server, and also have a Java Virtual Machine available on the platform eGuide can be installed.

Make sure your NetWare server supports Java JDK 1.1.4 or higher. (NetWare 5.1 does.) Make sure that you have a web server installed on the NetWare server that you install eGuide to. (NetWare 5.1 provides the NetWare Enterprise Web Server.) In addition, the web server must be running and fully functional in order for eGuide to function properly.

You should make sure that you have a fully configured and functional LDAP server installed and running on the NetWare server.

To install eGuide on a NetWare server:

  1. Run the eguide.exe from a client machine that has a drive mapped to the root of the SYS volume of the server you wish to install to.

    • You will be asked for a primary installation directory during the install. This directory is the directory that you want the HTML documents installed to. This directory must be accessible from your web server. This will become the root of the Novell eGuide web page. With a NetWare 5.1 server place your directory in the following location (assuming you are using NetWare Enterprise Web Server): SYS:\Novonyx\Suitespot\docs\eGuide\ where eGuide can be any directory name of your choosing. The Novell eGuide server files will be copied to a directory named server off the primary installation directory, above.

  2. To startup the eGuide server on NetWare, type addbook on the server console. (ADDBOOK.NCF is placed in the SYS:\SYSTEM directory on the NetWare server.)

    • If eGuide is running properly, you will see a message like the following on a server screen: New server is ready. On Port 3421.

  3. To access the eGuide interface via your Internet Browser of choice, double click on intro.html, located in the SYS:\Novonyx\Suitespot\docs\eGuide\docs\en-us\ directory structure.

  4. Select Access Novell eGuide.

    Note: If you have difficulties getting into eGuide by the above method, including getting the "The Novell eGuide Server is currently unavailable" error, you can enter the following URL in your Internet Browser:

http://<sever IP address>/eguide/eguide.html

If the eGuide client still fails to load, it is very important that you are running a compatible version of NLDAP.NLM. The minimum required version ships within the eguide.exe download file. It is located in the following directory upon installation:

SYS:\Novonyx\Suitespot\docs\eGuide\server\nwldapupdate\

NLDAP.NLM v3.14 January 14, 2000 129,855 bytes

Configuring eGuide

After following the above-mentioned instructions for installing eGuide, you can bring eGuide up and, by default, read all the users in your NDS tree. The eGuide offers a lot of configuration parameters that are very easy to work with. Please see eguide.pdf, located in the following directory on the NetWare server:

SYS:\Novonyx\suitespot\docs\eguide\docs\

Note: Your directory name, where you installed eGuide, may differ from the above example.

Configuring WebSphere to Work With Oracle 8i

With Oracle 8i and WebSphere successfully installed on the NetWare 5.1 server, you are ready to configure WebSphere to use Oracle 8i as its database. WebSphere, by default, uses an elementary database called InstantDB. WebSphere uses two table schemas in our example. One is called WAS. This is the internal table schema that WebSphere uses. The second is called WS_DATA. This table schema is used for the WebSphere sample applications; chiefly the YourCo sample application. You can configure Oracle to be used for one or both.

The configuration can be done either at the WebSphere Console, which runs on any platform that WebSphere runs on (Linux, Solaris, Windows NT, Windows 2000, NetWare, AS400, etc.), or by modifying the admin.config file in WebSphere. This approach will modify the admin.config file.

Prepare Oracle Database for WebSphere

To prepare the Oracle database for WebSphere do the following:

  1. On the server console type svrmgr31. This will bring up the command-line utility to allow configuration of the database.

    • Step 2 assumes that your Oracle DBA password is novell.

  2. svrmgr31>connect internal/novell

    • On the remaining steps don't forget to put a semi-colon (;) at the end of each statement. Failure to do so will cause the Oracle server manager to prompt for additional input. The connect command does not require a semi-colon.

  3. svrmgr31>create tablespace was datafile 'sys:\orahome1\was' size 50k reuse autoextend on next 5k;

  4. svrmgr31>create user EJSADMIN identified by EJSADMIN default tablespace was;

  5. svrmgr31>grant connect to EJSADMIN;

  6. svrmgr31>grant resource to EJSADMIN;

  7. svrmgr31>grant dba to EJSADMIN;

    • The exit command does not need a semi-colon (;) following it.

  8. svrmgr31>exit

    • The preceding command will create a database called was in Oracle 8i. It will also create a user that will be used to administer the database. This is the database that will be used internally by WebSphere.

Modify WebSphere

Next we need to modify the WebSphere admin.config file to allow WebSphere to see the oracle database. The admin.config file is located in the SYS:\WebSphere\AppServer\bin subdirectory.

Make the following modifications:

  1. com.ibm.ejs.sm.adminServer.dbDriver=oracle.jdbc.driver.OracleDriver

  2. com.ibm.ejs.sm.adminServer.dbUser=EJSADMIN

    • (Add the following zip file to the end of the classpath)

  3. com.ibm.ejs.sm.adminserver.classpath=...;SYS:/OraHome1/jdbc/lib/classes111.zip

  4. com.ibm.ejs.sm.adminServer.dbPassword=EJSADMIN

  5. com.ibm.ejs.sm.adminServer.dbUrl=jdbc:oracle:thin:@<Server IP Address>:1521:ORCL

  6. install.initial.config=true

  7. initial.defaultServer.start=true

Start Up WebSphere Server

Start up the WebSphere server by typing the following at the NetWare server console:

>startupserver

The rest is automatic. WebSphere should come up using the Oracle database instead of the default InstantDB.

Remove WebSphere

Removal of WebSphere databases from Oracle 8i.

To remove the two WebSphere databases from Oracle, do the following:

  1. On the server console type svrmgr31. This will bring up the command-line utility to allow configuration of the database.

    • Step 2 assumes that your Oracle DBA password is novell.

  2. svrmgr31>connect internal/novell

  3. svrmgr31>drop tablespace was including contents cascade constraints;

  4. svrmgr31>drop user EJSADMIN cascade;

  5. svrmgr31>exit

The Websphere databases, and all their contents will now be removed.

Configuring WebSphere to Work with the WebSphere Samples

  1. In order to use the sample WebSphere applications, including the YourCo application, you need to configure the Oracle 8i database. This is done by bringing up the WebSphere home screen on your favorite browser.

    • http://<server IP address>/WebSphereSamples/

  2. Next select the option database configuration in the Note.

  3. On the Configuring the Samples page, select Run the database servlet.

  4. Provide the following information:

    • User: EJSADMIN

    • Password: EJSADMIN

    • Path to WebSphere Install: (Leave as is)

    • Database URL: (Provide your server's IP address where it says <ip-ofyour-server>)

    • Database Driver: (Leave as is)

    • Please enter a yes or no question to use for the Poll sample: (Place any question here, such as Does it snow in Utah?

  5. Press Submit.

  6. Go back to the IBM WebSphere Samples Gallery page and select YourCo from the blue, left-hand column. You can then experiment with all the YourCo functionality.

Possible Problems with the WebSphere Engine

The WebSphere engine runs on the NetWare server using the host Java Virtual Machine. When the WebSphere engine comes up, it will load three Java processes. These processes, which are loaded in this order, are:

  • Nanny

  • Admin Server

  • Managed Server

You can see these processes by typing Java -show on the NetWare console screen.

Another, more reliable way to check the status of WebSphere loading is to type out the contents of the WebSphere log file. The log file is located in:

SYS:\WebSphere\AppServer\logs\tracefile

You can do the following on the NetWare server console to check the status:

>Type SYS:\WebSphere\AppServer\logs\tracefile

A trace file with no errors will look like this:

006.591 1b999a16 AdminServer A Initializing WebSphere Administration server

006.646 1b99f5cc DrAdminServer A DrAdmin available on port 1,044

037.405 1b999a16 InitialSetupI A Creating Sample Server Configuration

054.651 1b999a16 DefaultServer A initializing Default Server

059.869 1b999a16 DefaultServer A started Default Server

091.177 1b999a16 AdminServer A WebSphere Administration server open for e-business

The key to the WebSphere server being up and running is the last line, with the "WebSphere Administration server open for e-business."

Quite frequently after installing WebSphere, when you bring it up, one or more of the three Java processes will exit with a generic error. These errors will typically occur at the Admin Server process of the boot cycle. The error will be displayed on the server console, showing the complete Java dot path, ending in the process name. For example, the error could look like the following:

com.ibm.ejs.sm.server.AdminServer exited with status -1

Sometimes the error code will be positive:

com.ibm.ejs.sm.server.AdminServer exited with status 1

When this occurs, Managed Server will not load. Eventually Nanny will exit also. Occasionally, Admin Server will load and Managed Server will not. This is rare. When this happens, typically you will need to re-install WebSphere to correct the problem.

The following lists some of the reasons that Admin Server will not load:

Note: These problems assume that you are using and have configured Oracle as your WebSphere database.

  • DNS name is not setup correctly on the NetWare server. Edit the SYS:\ETC\Hosts file. Make sure that you have a correct DNS entry in the file for your server in the format of:

<Server IP Address> <Server URL><Name you want to reference the server with.>

  • An example would be:

151.155.138.3  day.provo.novell.com  DAY

  • Make sure that the following entries in ADMIN.CONFIG are set to true:

install.initial.config=true
initial.defaultServer.start=true

  • When the WebSphere server loads Admin Server, if the load procedure gets to a certain point, these settings will be set to false. These need to be set to true for Websphere to load properly.

  • If you are not using Oracle 8i as your database, but rather want to use IBM's instantDB, and are having problems getting WebSphere server up and running. Perform these steps. This will fix most of the problems:

    1. Delete the directory SYS:\WebSphere\AppServer\bin\idbstore\. Idbstore is where all the IBM database files are stored.

    2. Edit ADMIN.CONFIG and change the following values from false to true:

      install.initial.config=true
      initial.defaultServer.start=true

    3. Re-start WebSphere by typing Startupserver on the NetWare server console.

  • You can run into some licensing issues with using the 5 - user license provided with the Oracle 8i that ships with NetWare. Oracle states that the license that ships with the NetWare Oracle version is 5 users, when in actuality, it is 7 users. WebSphere's Admin Server uses 2 of these licenses with WebSphere's Managed Server using 3. So just getting the WebSphere server running consumes 5 of the 7 licenses. When you run the YourCo WebSphere demo application, YourCo will use two connections. This is due to the Oracle user, in our case EJSADMIN, having database administrator (dba) rights. Each logged in dba user consumes one Oracle license. Once you reached the 7 Oracle licenses, HTML errors will be returned to your browser indicating that there are no more Oracle licenses.

  • The only way to fix this problem is to buy a greater number of user licenses from Oracle.

Upgrading NDS to Tao Release (Beta 4)

Upgrading the NDS that ships with NetWare 5.1, version 8.3, is quite a simple procedure. Follow these steps:

  1. Load NWCONFIG on your NetWare server:

    • >NWCONFIG

  2. Select Product Options.

  3. Select Install a product not listed.

  4. Press F3 to select a different source drive/directory. Enter the path to the nds8.ips file.

  5. Press Enter to start the installation.

  6. Follow all the on-screen instructions to install the NDS Tao Beta 4 release.

    Note: These instructions are all listed in the readme file, which is a part of the Tao Beta 4 release.

Testing the Complete System Configuration

The following are a couple of suggestions for putting this system configuration through its paces in preparation for a demonstration.

Referencing Figure 1, at the beginning of this document, data can be entered via Console One into NDS. For example, creating a user. This information will be stored in NDS on the NetWare server. This information can be viewed by eGuide, sorted, etc. Additionally the data will be transferred to the WebSphere YourCo Oracle 8i table via the JDBC DirXML driver. Once the data has been transferred to the Oracle database, it can be viewed in the WebSphere YourCo application. (Browser via NetWare Enterprise Web Server).

To reverse this process, (user) information can be entered directly into the WebSphere Oracle table by using Oracle's SQL Plus, or compatible utility. Entering this information will cause a trigger to occur in Oracle that will cause the JDBC DirXML driver to synchronize the data to NDS. Once the data is in the NDS datastore, it can be displayed via eGuide or Console One.

Variations on this theme could include using browsers to read and write the data, or other input/output applications/devices. However, this would discount the point of this project; the point being to show the power and flexibility of the NetWare 5.1 platform.

Implications of Changing the NetWare Server's IP Address

When a NetWare 5.1 server is installed, the installation requires that you choose between two network protocols: IPX/SPX or IP. IP is the preferred protocol for this project. If you ever have the need to change the original IP address on your server, the process and implications of this to your other applications can be quite overwhelming. The following outlines all the places the IP address will need to be changed for this project to work.

NetWare 5.1 Server

NetWare 5.1 Server's LAN driver binding can be changed either directly in the server's AUTOEXEC.NCF file or by loading INETCFG. If modifying AUTOEXEC.NCF, locate your LAN Driver and look for the Bind statement right underneath it. There should be the following information:

Bind IP <LAN DRIVER NAME> ADDR=<IP ADDR> MASK=<MASK ADDR> GATE=<GATE ADDR>

Modify as needed and reboot the server. When the server comes back up, it will be using the new IP address.

  1. To use INETCFG, select Bindings,TCP/IP, enter changes.

  2. Reboot the server. When the server comes back up, it will be using the new IP address.

  3. DNS information. Edit the SYS:\ETC\Hosts file to update your new IP address and DNS name.

NetWare Enterprise Web Server

The NetWare Enterprise Web Server will not work correctly after changing the NetWare server's IP address. This is due to the reliance of the NetWare Enterprise Web Server on two security certificates located, by default, in the server container of your NDS tree. These certificates use the server's IP address as part of their composition. You will need to delete these two certificates and re-create them as follows:

  1. Delete the following certificates from the root of your NDS tree:

    SSL CertificateDNS
SSL CertificateIP

When re-creating these two certificates, you do not need to append the server name to the certificate name. The NetWare Server Certificate Creation utility will do it automatically.

  1. Create two new certificates by doing the following:

  2. In Console One, right click on the container of your server.

  3. Select New, then Object.

  4. Select NDSPKI:Key Material

  5. Select the defaults. For certificate name, enter SSL CertificateDNS. Click Next.

  6. Click Finish.

  7. Repeat steps a through e for the SSL CertificateIP.

  8. Restart the NetWare Enterprise Web Server.

In addition to re-creating the certificates, you need to change the IP address in the following locations:

SYS:\Novonyx\suitespot\admin-serv\config\ns-admin.conf

SYS:\Novonyx\suitespot\https-<SERVER NAME>\CONF_BK\MAGNUS.CONF

SYS:\Novonyx\suitespot\https-<SERVER NAME>\CONF_BK\OBJ.CONF

SYS:\Novonyx\suitespot\https-<SERVER NAME>\config\magnus.conf

SYS:\Novonyx\suitespot\https-<SERVER NAME>\config\obj.conf

Alternately, you can re-install NetWare Enterprise Web Server, enter the new IP address during install, and all the above changes will be made for you - EXCEPT re-creating the security certificates.

WebSphere

WebSphere needs a few changes to get it working with the new server IP address. Complete the following steps to update WebSphere:

  1. In the file ADMIN.CONFIG change the IP address in the following line to the new server IP address:

    com.ibm.ejs.sm.adminServer.dbUrl=jdbc:oracle:thin:@<Server IP Address>:1521:ORCL

  2. You will need to reconfigure the WebSphere sample application again.

Oracle 8i

Use the Oracle 8i EASYCFG utility to change the Oracle Listener's IP address. Perform the following steps to do this:

  1. Type EASYCFG on the NetWare 5.1 server's console. This will bring up the NetWare GUI with EASYCFG.

  2. Select Config from the menu bar (only option).

  3. Select Listener from the menu.

  4. Select Address from the sub-menu.

  5. Modify and save the new IP address.

  6. Select Config and choose Exit to exit EASYCFG.

  7. Exit NetWare GUI, if desired.

  8. Stop and then re-start Oracle 8i. Oracle will come back up using the new IP address.

* Originally published in Novell AppNotes

Disclaimer

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