Updated June 13, 2001
Before deploying sample applications to iPlanet Application Server, ensure that your application server environment is functioning properly and that you are familiar with the administrative tools, packaging of the samples and basic server operations.
Check the iPlanet Developer's site http://developer.iplanet.com/appserver/samples/index.html for updates to the sample applications. Between releases of the application server, updates to the samples may be published to this site. Updates may includes sample bug fixes, enhancements and new samples.
Use the Fortune sample application to verify basic interoperability between the web server and application server. Since this application is automatically deployed during installation of iPlanet, you can invoke the application as soon as you've installed the application server by accessing the following URL or by clicking here:
http://<webserver host>:<port>/NASApp/fortune/fortune
The Fortune application employs a servlet and JSP to display a different fortune message each time the application is invoked. If you encounter problems running this application, refer to the General Troubleshooting section for more information.
In order to use the Jakarta Ant tool to compile and reassemble the sample applications, you will need to ensure that the application server's bin/ directory is in your environment's path. On Windows, during installation of the application server, the System PATH variable is automatically set to include install_dir\ias\bin. On UNIX, you will need to add the install_dir/ias/bin directory to your PATH environment variable. See the Sample Application Build Facility section for more details.
Familiarize yourself with the application server's runtime environment prior to working with the samples. Key components of the runtime include:
| Runtime Component | Description |
| Web Connector Plugin | A dynamically loaded library that plugs into an web server instance. This library redirects incoming HTTP requests to the Executive Server (kxs) processes in an application server instance. |
| Application Server Processes | |
Executive Server (kxs) |
Plays two roles: a) redirects incoming HTTP traffic received from Web Connector Plugin to a Java Server and b) manages replication of highly available session and state data between application server instances. |
Java Server (kjs) |
Contains web and EJB containers. |
RMI/IIOP Bridge (cxs) |
The cxs redirects incoming requests from RMI/IIOP clients to the EJB container housed in a Java Engine (kjs). |
Administrative Server (kas) |
Monitors health of other application server processes and acts as a server for the administrative and deployment tools. |
| Directory Server | |
Directory Server Process (slapd) |
Plays two roles: a) contains user and group information for authentication and authorization purposes and b) acts as a distributed store for the application server's Registry information. |
| Netscape Administrative Server | Acts as a contact point for the Netscape Console tool. This server is not required to be active by the application server. |
Familiarize yourself with the Netscape Console and its ability to launch the administrative tools for both the iPlanet Directory Server and iPlanet Application Server. Start the console, navigate through it and launch the iPlanet Application Server administrative tool to register your application server instance.
Overall Administrative Tools
Application Server Administrative Tools
UNIX:
install_dir/startconsole
For example,
/usr/iplanet/ias6/startconsole
Enter your username and password for the Netscape Administrative Server. Default usermane is "admin" and was set during installation of the application server.
If you encounter problems while connecting to the Netscape administrative server, you might need to supply a URL with port number to successfully connect to the administrative server. This can be done in the following fashion:
/usr/iplanet/ias6/startconsole -a http://<hostname>:8889
Where 8889 is the Netscape Administrative Server's port number. If you encounter problems connecting to the Netscape Administrative Server, ensure that the port number on the connection URL matches the port number assigned to the Netscape Administrative Server during installation. If you do not remember the port number, you can view the ias6/admin-serv/config/adm.conf file to determine the port number. Look for the "port: xxxx" entry in this file.
Windows:
Start->Programs->iPlanet Server Products->Netscape Console 6.0
Enter your username and password for the Netscape Administrative Server. Default usermane is "admin" and was set during installation of the application server.
Although you can browse user and group information through the Netscape Console, the Directory Server Administrative Tool enables you to perform maintenance on the directory server. For example, in some of the samples, you are directed to load the directory server with user and group information. One means of doing this is by loading a predefined LDIF file into the directory server through the Directory Server Administrative Tool.
Directory Server Administrative GUI
To start the Directory Server Administrative Tool via the Netscape Console:
1. Expand the host name entry associated with your server.
2. Then expand the <system name>->Server Group entry.
3. Double click on Directory Server to launch the Directory Server administration
tool.
Now browse through some of the entries that were populated during installation:
1. Select the Directory tab and expand the folder containing your network
domain name.
2. Select the Groups and and People icons to view the groups and
people added during installation of the iPlanet application server.
You can leave the Directory Server Administrative tool open as you will be able to use this tool during setup of the application.
ldapmodify Command Line Utility
To make changes to the directory server content, you can use the ldapmodify
command line utility. Some of the samples that rely on directory server content
describe how to use this facility to populate entries in the directory server.
The Application Server Administrative Tool provides a means to modify the runtime characteristics of the application server. This tool acts as a client to the application server's administrative server process (also known as as the "kas"). You can launch this tool via either the Netscape Console or directly via Start->Programs (Windows) and the command line (UNIX).
Starting Outside of Netscape Console
UNIX:
install_dir/ias/bin/ksvradmin
Windows:
Start->Programs->iPlanet Application Server 6.0->iAS Administration Tool
Starting Via Netscape Console
In the Netscape Console window, double click the iPlanet Application Server icon under the Server Group area.
Registering a Server Instance
To manage an application server instance via the application server administrative tool GUI and via the iascontrol and iasdpeloy CLIs, you must first register the application server instance with the administrative environment:
The Application Server Deployment Tool enables you to perform assembly and deployment operations on J2EE applications. The sample application setup instructions provide information on how to use the Deployment Tool to assemble and deploy the sample applications. To start the Deployment Tool, follow the instructions for your operating system platform:
UNIX:
install_dir/ias/bin/deploytool&
Windows:
Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool
Certain low-level configuration changes to the application server runtime are accomplished via the Application Server Registry Editor. The editor is a GUI application that provides a composite view of the configuration information stored in the directory server and in the local file system. To start the editor, execute the following command:
kregedit
Two sets of command line utilities will be of interest to you. The iascontrol command line interface (CLI) enables you to start and stop the server from the command line. The iasdeploy CLI enables you to perform deployment-related tasks from the command line. For further information on these utilities, execute the utility with the -help option. Both of these utilities are capable of operating against either local or remote application server instances.
In order for these utilities to operate against remote application server instances, you must first register each instance through the Application Server Administrative Tool. Once you've assigned a logical name to the remote instance, you can use this name in the command line execution of the iascontrol and iasdeploy tools.
iascontrol Usage Information
Usage:
iascontrol <subcommand> [-instance <instance> |
[-user <user> -password <password>] [-host <host> -port <port>] ]Where <subcommand> is one of the following:
start - to start an application server instance. on local host, also starts admin server if not already started.
stop - to stop the engines of an application server. admin server is not stopped.
kill - to force the immediate, non-graceful termination of all application server processes (local host only)-instance - name of server instance as registered in admin tool.
-user - name of user that has admin authorization for the specified server.
-password - password associated with user.
-host - hostname or IP address of the target server instance.
-port - port number of the application server's administrative server. Port 10817 is the default.
-help - display usage information.Before using the start and stop commands you must register
the server instance via the application server admin tool.
iasdeploy Usage Information
Usage:
iasdeploy <subcommand> [options] [-verbose] [-instance <instance>...|
-user <username> -password <password>] [-host <host> -port <port>]]]
[operand...]Where:<subcommand> is one of the following:
deployapp - to deploy a J2EE application.
redeployapp - to redeploy a J2EE application faster.
deploymodule - to deploy a J2EE WAR or EJB JAR module.
removeapp - to remove a J2EE application.
removemodule - to remove a J2EE WAR or EJB JAR module.
removeweb - to remove a J2EE WAR module with module name.
removeejb - to remove a J2EE EJB JAR module with module name.
regdatasource - to register JDBC datasource.
verify - to verify J2EE application/WAR or EJB JAR module.
deploystartup - to deploy a startup class.
Following are the valid options:
-instance - name of server instance as registered in admin tool.
-verbose - display all command output.
-user - userid of the user who has deployment authorization for the specified application server.
-password - password associated with user.
-host - hostname or IP address of target
application server instance.
-port - port number of application server's administrative server. Port 10817 is default.
-help - display usage information.To display usage information for particular subcommand:
iasdeploy <subcommand> -help or iasdeploy -help <subcommand>
You can easily restart and application server instance through either the Administration Tool or via the command line. Prior to using the application server's Administration Tool GUI or iascontrol to restart an application server instance, you must first register an application server instance with the application server's Administration Tool. See the Application Server Admin Tool section for more information on registering a server instance with the administrative tool.
Application Server Administration Tool
1. Select the server instance.
2. Select the General button.
3. Click on Stop Server
4. Click on Start Server
Command Line
Execute the following commands to restart the application server:
After performing "stop", only the directory server (ns-slapd), the Netscape admin server (ns-admin) and the application server's administrative server (kas) should be running. On UNIX, for example, you should see the following processes after performing a "stop":
$ ps -ef | grep ias
ckamps 19170 13813 0 14:10:21 pts/16 0:00 grep ias
nobody 18391 1 0 11:19:20 ? 0:16 ./ns-slapd -f /usr/iplanet/ias6/slapd-canteloupe/config/slapd.conf -i /usr/ipla
root 18717 18712 0 11:20:23 pts/14 0:03 /usr/iplanet/ias6/ias/bin/.kas
root 18712 1 0 11:20:22 pts/14 0:00 /bin/sh /usr/iplanet/ias6/ias/bin/kas
root 15474 1 0 11:14:37 ? 0:00 ./ns-admin -d /usr/iplanet/ias6/admin-serv/config
Here is an example of processes after a "start" command:
On UNIX, the ".k*" processes, for example ".kjs", are the actual engine processes while processes without the leading dot are merely shell processes responsible for starting the actual engine processes.root@canteloupe-{/}: ps -ef | grep ias
nobody 18391 1 1 11:19:20 ? 0:17 ./ns-slapd -f /usr/iplanet/ias6/slapd-canteloupe/config/slapd.conf -i /usr/ipla
root 19217 1 0 14:16:07 ? 0:00 /bin/sh /usr/iplanet/ias6/ias/bin/kjs -cset CCS0 -eng 1
root 18717 18712 1 11:20:23 pts/14 0:03 /usr/iplanet/ias6/ias/bin/.kas
root 19215 19214 2 14:16:05 ? 0:01 /usr/iplanet/ias6/ias/bin/.kxs -cset CCS0 -eng 0
root 19219 19217 1 14:16:07 ? 0:03 /usr/iplanet/ias6/ias/bin/.kjs -cset CCS0 -eng 1
root 19214 1 0 14:16:05 ? 0:00 /bin/sh /usr/iplanet/ias6/ias/bin/kxs -cset CCS0 -eng 0
root 18712 1 0 11:20:22 pts/14 0:00 /bin/sh /usr/iplanet/ias6/ias/bin/kas
root 18969 18960 0 12:19:29 pts/14 0:22
root 15474 1 0 11:14:37 ? 0:00 ./ns-admin -d /usr/iplanet/ias6/admin-serv/config
Hard Termination
To perform a complete termination of the application server (i.e. to stop both
the engines and the application server's administrative server), you can use
the following command on both Windows and UNIX:
iascontrol kill
On UNIX, this command will perform a "kill -9" on the application server processes. On Windows, the application server's Windows service will be stopped. Only the directory server and Netscape administrative servers will remain active after a "kill":
nobody 18391 1 0 11:19:20 ? 0:17 ./ns-slapd -f /usr/iplanet/ias6/slapd-
root 15474 1 0 11:14:37 ? 0:00 ./ns-admin -d /usr/iplanet/ias6/admin-serv/config
Occasionally, you will need to added JAR files and/or directories to the CLASSPATH of the application server. You typically modify the application server's classpath when you need to share a set of classes across all applications deployed to a server.
In iPlanet Application Server 6.0 SP3 the classpath setting used by the kjs shell script is housed in a common environment setting shell script. Make changes to the kjs CLASSPATH variable in the
install_dir/ias/env/iasenv.ksh:
...
# Union of all CLASSPATHS
export CLASSPATH=${TOMCAT_DIR}/jasper.jar:...
Restart the application server to pick up the classpath changes.
On Windows the application server uses the CLASSPATH setting defined in the application server's registry. (Setting the Windows system environment variable CLASSPATH will not affect the setting used by the application server). To modify the registry:
On SP2, modify the installdir/ias/bin/kjs script to include the supporting JAR files and/or directory paths. The kjs script starts the JVM that houses the application server's web and EJB containers.
install_dir/ias/bin/kjs:
...
CLASSPATH=$THIRD_PARTY_JDBC_CLASSPATH:$GX_ROOTDIR/classes/java/jdbc20.jar:
$GX_ROOTDIR/classes/java/javax.jar:...
Restart the application server to pick up the classpath changes.
For development purposes, the manner in which you can easily monitor the application server logs depends on the operating system in use. Developers typically monitor the logs generated by the Java Engine (kjs) processes as these logs contain output from the web and EJB containers.
Note that although the RMI/IIOP Bridge process is named "cxs", it is actually just another Java Engine (kjs) process. Consequently, to review the Bridge log messages, you must monitor one of the kjs processes.
Monitoring Application Server Logs on Windows
To enable display of application server logs on Windows, modify the iPlanet
Application Server 6.0 Windows service entry:
1. Start->Settings->Control Panel
2. Double click on Services
3. Find the "iPlanet Application Server 6.0" entry and select
it.
4. Click on Startup.
5. Click on "Allow Service to Interact with Desktop" and click
on OK.
6. Click on Stop to stop the application server.
7. Click on Start to start the application server.
As the application server starts, you will see a number of MS DOS output windows appear on the desktop. A single output window will be present for each physical process in the application server. See the section Familiarize Yourself with the Runtime Environment for more information on the application server processes.
To enable vertical scroll bars in these output windows, follow these instructions:
1. Select the MS DOS icon at the upper left of the output window.
2. Select Properties.
3. Select Layout.
4. Set the Screen Buffer Size Height to 200 or as desired.
5. Answer Yes when asked to apply these changes to all invocations of
this window.
Monitoring Application Server Logs on UNIX
On UNIX, most developers use the tail
-f command to monitor the application server log files of the process
of interest. To monitor the Java Engine logs in this manner follow these instructions:
1. Navigate to the logs directory:
cd install_dir/ias/logs
2. Execute tail command on one of the Java Engine (kjs) and the Executive Service (kxs) processes:
tail -f kjs_1*
tail -f kxs*
3. Use Control-C to kill tail.
If you are using the iPlanet Web Server, you can easily view log entries through a web browser.
1. Launch a browser and connect to the administrative port of the web server. For example,
http://canteloupe.red.iplanet.com:8888/https-admserv/bin/index
2. Select the server of interest and click on Manage.
3. Click on the Status tab.
4. View the application server's web connector log entries by clicking on the
View Error Log link.
By default, for performance reasons, dynamic servlet and EJB reloading is disabled in the application server. To enable it for use in your development environment follow these instructions:
1. Start the iPlanet Application Server's Registry Editor, kregedit, and modify the Versioning\ area under:
SOFTWARE\iPlanet\Application Server\6.0\CCS0\SYSTEM_JAVA\Versioning
2. Set the Disable key to "0".
3. Restart the application server to pickup the Versioning\ change.
This change will enable dynamic reloading of servlet classes and registered JSPs - i.e. those JSPs that have been assigned GUIDs and are listed as servlets in web.xml files. By default, unregistered JSPs are dynamically reloaded by the application server.
Modification of EJBs is affected immediately when the EJB container refreshes the pool for that Bean, while maintaining the session information for other active beans. To get the changes reflected, the user has to call the create method for stateful and entity beans again, whereas stateless session beans would be affected immediately. By default dynamic servlet, EJB and registered JSP reloading is disabled in the iPlanet Application Server. To enable dynamic reloading of servlets, EJBs and registered JSPs:
Although the Test Drive installation of iPlanet Application Server automatically activates RMI/IIOP support, the Express, Typical and Custom installations do not. For these installations, you must manually configure RMI/IIOP support in the application server to enable RMI/IIOP access to EJBs.
To activate RMI/IIOP support, you start the iPlanet Application Server Administrative tool and add an RMI/IIOP Bridge process to the application server environment. The Bridge process acts as a gateway between front end IIOP access and the internal protocols used to access the EJB container.
UNIX:
install_dir/ias/bin/ksvradminWindows:
Start->Programs->iPlanet Application Server->iAS Administration Tool
ps -ef | grep iiop
root 1153 1 0 17:00:15 ? 0:00 /bin/sh /usr/iPlanet/iAS6/ias/bin/kjs -cset CCS0 -eng 3 -iiop -DORBinsPort=9010
iPlanet Application Server 6.0 sp3 ships with Pointbase Network Server version 3.5. The data needed for all supported samples is preloaded into the database. More information on working with Pointbase can be found here.
Copyright
(c) 2001 Sun Microsystems, Inc.