support readiness document for java web server 2

Sun Microsystems, Inc.Java Software

Support Readiness DocumentforJava Web Server 2.0

Sun Microsystems, Inc.Java Software901 San Antonio RoadPalo Alto, CA 94303U.S.A.

Support Readiness DocumentforJava Web Server 2.0

Version: 2.0Release Date: August 31, 1999

1999 by Sun Microsystems, Inc.—Printed in USA.901 San Antonio Road, Palo Alto, California 94303

All rights reserved. No part of this work covered by copyright may be duplicated by any

means—graphic, electronic or mechanical, including photocopying, or storage in an information

retrieval system—without prior written permission of the copyright owner.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to

restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer

Software clause at DFARS 252.227-7013 (October 1988) and FAR 52.227-19 (June 1987). The

product described in this manual may be protected by one or more U.S. patents, foreign patents,

and/or pending applications.

TRADEMARKS: Java, Java 2, 100% Pure Java, Java Web Server, Java Development Kit, Java

Workshop, JavaBeans, JavaServer, JavaServer Pages, JDBC, JDK, HotJava, Netscape, Netscape

Navigator, OpenWindows, and Solaris are trademarks of Sun Microsystems, Inc. Solaris SPARC

(Platform Edition) is a trademark of Sun Microsystems, Inc. All SPARC trademarks are used

under license and are trademarks or registered trademarks of SPARC International, Inc. in the

United States and other countries. Products bearing SPARC trademarks are based upon an

architecture developed by Sun Microsystems, Inc. UNIX is a registered trademark in the United

States and other countries, exclusively licensed through X/Open Company, Ltd.

Production Note: This book was written in FrameMaker 5.5 for Solaris and Windows by Mary

Artibee and Lorraine Maggi.

ent

Table of Contents

Preface v

1.0 Java Web Server Overview 11.1 Features, Advantages and Benefits 21.2 Java Web Server Architecture Details 51.3 Java Web Server Security Details 6

1.3.1 Servlets and Security 61.3.2 Resource Protection 71.3.3 Secure Web Service – Secure Sockets Layer (SSL) 71.3.4 Java 2 Security 8

1.4 New in Version 2.0 81.4.1 Bug Fixes 10

1.5 Localization and Internationalization 11

2.0 Product Distribution 122.1 Java Web Server 30-Day Trial 122.2 Java Web Server Purchase 122.3 Product Transition 12

3.0 Requirements and Dependencies 133.1 System Requirements and Dependencies 13

3.1.1 Disk Space Needed to Install Java Web Server 133.1.2 Recommended System Configurations 133.1.3 Supported Hardware Platforms / Required Boards or Peripherals 15

3.2 Software Requirements and Dependencies 153.2.1 Operating Systems and Versions Supported 153.2.2 Recommended Amount of Swap Space (Solaris Operating Environm

Only) 153.2.3 Recommended Heap Size 153.2.4 Other Software Requirements 16

3.3 Product Compatibility 163.3.1 Interoperability with Existing Third-Party Software 163.3.2 Backward/Forward Compatibility with Other Releases 173.3.3 Versions 17

3.4 Product Upgrades 17

SUN MICROSYSTEMS, INC. i

Table of Contents

ort

3

ful

3.4.1 Java Web Server Migration 17

4.0 Installing Java Web Server 174.1 Pre-Installation Considerations 17

4.1.1 Solaris Only: Packages Necessary for Running with Java 2 174.1.2 Solaris Only: Applying Necessary Solaris OS Patches 184.1.3 Solaris Only: Install as Root in Order to Run on Port 80 (Or Any P

Number Below 1024) 194.1.4 Solaris Only: Installation Occurs Upon Untarring the Download 194.1.5 Versions 204.1.6 Java Runtime Environment (JRE) 204.1.7 Estimated Time Needed to Install 21

4.2 Installation Details 214.2.1 Default Installation Path 214.2.2 Changes to System Files 214.2.3 Directories Created at Installation 214.2.4 Directories Created After Running Java Web Server the First Time 24.2.5 Daemons Started for the Application 23

4.3 Tutorial: Download and Install Java Web Server 234.3.1 Solaris 234.3.2 Microsoft Windows 95 and Microsoft Windows NT 24

4.4 Post-Installation Considerations: Verifying a SuccessInstallation 254.4.1 Tutorial: Start the Server (Solaris) 25

4.4.1.1 Using the Default Java Runtime Environment 254.4.1.2 Using your Existing Java Environment 25

4.4.2 Tutorial: Start the Server (Microsoft Windows NT) 254.4.3 Tutorial: Start the Server (Microsoft Windows 95) 264.4.4 Checking that the Server is Running 26

4.5 Common Problems with Installation 274.5.1 Solaris 27

4.5.1.1 Download Corruption 274.5.1.2 Avoiding Permission Problems When Restarting 27

4.5.2 Microsoft Windows 27

5.0 Uninstalling the Java Web Server 285.1 Stopping the Java Web Server 28

5.1.1 Using the Graphical User Interface 285.1.2 Using a Command Line 285.1.3 Microsoft Windows NT 28

5.2 How to Uninstall the Java Web Server 295.2.1 Solaris 295.2.2 Microsoft Windows NT 295.2.3 Microsoft Windows 95 29

5.3 Common Problems with Uninstalling 305.3.1 Microsoft Windows NT Registry Entries Are Not All Deleted 30

6.0 Java Web Server Configuration 30

SUN MICROSYSTEMS, INC. ii

Table of Contents

ing

ting

laris

6.1 Using Environment Variables 306.2 Starting the Java Web Server Automatically 31

6.2.1 Solaris 316.2.2 Microsoft Windows NT 316.2.3 Microsoft Windows 95 31

6.3 Changing the Default Ports 32

7.0 Using the Java Web Server 327.1 Tutorial: Configure Your Admin Tool 327.2 Java Web Server’s Administration Tool 33

7.2.1 Additional Controls 347.2.2 Links to Administration Tool Documentation 34

7.3 Using the Java Web Server to Invoke a Servlet 347.3.1 Tutorial: Configure the Java Web Server to Use Your Servlet 357.3.2 Tutorial: Invoke Your Servlet Using the Java Web Server 35

7.4 Mapping Servlets to URLs Using the Java Web Server 357.4.1 Tutorial: Map Your Servlet to a Unique URL 35

7.5 Server Side Includes (SSIs): Another Way to Invoke a Servlet Usthe Java Web Server 367.5.1 Tutorial: Create a.shtml File Using an SSI Tag 37

8.0 Tuning and Troubleshooting 388.1 Installation and Configuration “Gotchas” 38

8.1.1 Running Servlet Compatibility Mode 388.1.2 Running Native Code 398.1.3 Running Java Web Server as Root in the Solaris Opera

Environment 398.1.4 Running Java Web Server as Someone Other than Root in the So

Operating Environment 408.2 Known Bugs and Their Workarounds 41

8.2.1 Using the Java 2 SDK (formerly code-named “JDK 1.2”) 418.2.1.1 Solaris 418.2.1.2 Windows 41

8.2.2 Environment Variables with Quoted Strings Won’t Work 418.2.3 Limitations on JavaServer Pages 1.0 Support 428.2.4 Incorrect Version of JRE Redistribution Information 428.2.5 Trailing Backslash in the PATH Environment Variable 42

8.3 Common User/System Administrator Errors 428.3.1 Locking Yourself Out of the Java Web Server 428.3.2 Administration Password Forgotten 438.3.3 Running Multiple Servers 43

8.4 Troubleshooting Utilities 438.4.1 netstat 438.4.2 ping 448.4.3 telnet 448.4.4 Alternate Browsers 448.4.5 BugTraq 448.4.6 Log Files 44

SUN MICROSYSTEMS, INC. iii

Table of Contents

8.4.7 Thread Dump 458.4.8 Stack Trace Line Numbers 468.4.9 What to Try When JWS is Not Responding 468.4.10 Debugging Security Manager Problems with Java 2 468.4.11 JWS Version Info 488.4.12 Verbose Flag 488.4.13 Snoop Servlet 48

9.0 Reference Information 489.1 Technical Documentation 48

9.1.1 Primary Documentation 489.1.2 Release Notes 519.1.3 Additional Documentation 51

9.2 Additional Reference 529.2.1 External Email Aliases 529.2.2 ListServs 529.2.3 FAQ Reference Section 529.2.4 Books 53

10.0 Product Support 5310.1 Warranty/Installation Support 5310.2 Using the Serial Number Validation URL 54

Appendix A: Java Web Server, Migrating 1.1.3 to 2.0 1

1.0 Requirements 1

2.0 Approach 2

3.0 Migrating Customizations 23.1 Executables 2

3.1.1 Servlets and Servlet Beans 23.1.2 CGI Scripts 33.1.3 Startup Scripts 3

3.2 Log Information 43.3 Security 4

3.3.1 Certificates 43.3.2 Realms 5

3.4 Environment Settings 53.5 Properties 5

3.5.1 Available Through the Administration Tool 53.5.2 Available Only Through theProperties File 6

3.6 Documents 63.7 Additional Possibilities for Migration 6

SUN MICROSYSTEMS, INC. iv

There toprod-

eyand

on liveL in

eing

re

alic

d

rrm.

ular

n in

hen

PrefaceThis document provides Support Readiness information for Java Web Server 2.0. goal of Support Readiness Documents (SRDs) is to help support engineers prepasupport Java Software products. SRDs are not designed to provide comprehensiveuct training (see the product documentation or Sun Education for this). Instead, thfocus on issues immediately relevant to support, such as installation, configuration,common user problems.

Document Format Options: PDF and PostScript

TheJavaWebServer SRD can be viewed in PostScript or PDF format. The PDF versiof the document allows navigation via a table of contents frame, and the benefit ofcross references and web links. Text that is underlined and in blue, such as the URthis paragraph, are clickable links in the PDF version of the document. (Note: pagenumbers in the PDF document refer to printed pages, and will not coincide with thpage numbers in the PDF reader status bar.) Although the blue color and underlinappear in the PostScript version, there are no live links when viewing that version.

Typographic Conventions

This document uses the following type conventions:

• The names of commands, files, Java™ objects, Java classes, and directories ashown inregular monospace font .

• Text that is a placeholder to be replaced with a real name or value appears in ittype; for example:% unzip jsdt-1.4.zip -d destination directory.

• Text that you type, when shown alongside computer output such as a commanprompt, is shown inbold monospace font . The marker "prompt> ," in regularmonospace font, represents the actual command prompt you would see on youscreen, which may vary depending on your specific environment, shell, or platfoFor example:Solaris prompt> ls -l .

• The names of menu items, buttons, windows, and keyboard keys appear in regfont with initial capitals, such as the Enter key.

• URLs that are clickable web links in the PDF version of the document are showblue, underlined monospace font, as inhttp://java.sun.com . Although the bluecolor and underlining appears in the PostScript version, there are no live links wviewing that version.

SUN MICROSYSTEMS, INC. v

http://java.sun.com

Preface

h as

t are

luehen

• URLs that are not clickable web links are shown in regular monospace font, sucjsdt://stard:5555/socket/Session/chatSession.

• Cross-references to other sections of the document are shown in regular font bublue and underlined, as in,SeeSection1.0,“JSDTOverview.” In the PDF version ofthe document, these are clickable links to the indicated section. Although the bcolor and underlining appears in the PostScript version, there are no live links wviewing that version.

• New terms and book titles appear initalic type.

SUN MICROSYSTEMS, INC.

e-roughator

.

erver.

ows

ure

ts arerk.tedlop-t toe theirt Kit

Serv-

Java Web Server 2.0

1.0 Java Web Server Overview

JavaTM Web ServerTM (JWS) 2.0 is an easy-to-use, easy-to-administer, platform-indpendent web server. Once the server is running it can be used and administered thJava Development Kit (JDK) 1.1-compliant web browsers such as Netscape Navig

4.06, Netscape Communicator 4.5, HotJavaTM Browser 1.1.5, and Internet Explorer 4.0The Java Web Server, by default, supplies each of the following services:

• HTTP Service (Hypertext Transfer Protocol)

• HTTPS Service (Hypertext Transfer Protocol, Secure)

These services can be enabled or disabled, modified, or added to the Java Web S

A key feature of the Java Web Server is its focus on security. Java Web Server foll

the JavaTM Security model, provides access control utilities, and implements the SecSockets Layer (SSLv3) protocol.

Java Web Server’s functionality can be extended by the use of Java servlets. ServleJava server-side modules which fit seamlessly into the Java Web Server’s framewoSun Microsystems, Inc. is committed to making the Servlet API as public and accepas applets and CGI (Common Gateway Interface), therefore the Java Servlet Devement Kit (JSDK) has been developed and released to aid in adding Servlet supporany web server. The latest release, JSDK 2.1, can be used by developers to creatown servlets and servlet engines. Also available is the JavaServer Web Developmen(JSWDK) 1.0 which is the reference implementation for JavaServer Pages 1.0 andlet 2.1.1.

SUN MICROSYSTEMS, INC. 1 of 55

Java Web Server Overview

1.1 Features, Advantages and Benefits

TABLE 1. Detailed Overview of Product Features, Advantages & Benefits

Key Feature Benefits How to Use

Java Web Server HTTP 1.1 compliant (HTTP service). After installing Java Web Server, run thejserv executable to start the web server.

Cross-Platform Java Web Server can be used on any plat-form that supports the Java programminglanguage.

Java Web Server's ability to be cross-plat-form is due to the fact that it is written inJava. Since Java is a widely supported andaccepted language, most platforms supportany application written in Java.

SSL is only provided for Solaris SPARCand Windows NT environments. Custom-ers must port scripts to any new platform.

Java Web ServerAdministrationTool

Administration of a Java Web Server isperformed dynamically, which meansthat administration can be performedwithout bringing down the server, therebyeliminating server downtime.

The Administration Tool is an applet witha comprehensive user interface whichallows for simple and quick administra-tion.

All administration of the server is per-formed via the Administration Tool, anapplet that provides a clean, modular inter-face.

Through this tool’s graphical user interface(GUI), services such as the web service, andsecure web service can be managed.Changes can be made to setup, security, andJava servlets. The services and resourceusage can be monitored through logs andcharts.

SeeSection7.2 for details.

Java Servlets Java servlets are the server-side counter-part to applets; they do not need a graphi-cal user interface. Servlets are Javaserver-side objects that are loaded ondemand. Basically, servlets support thefamiliar programming model of acceptingrequests and generating responses.

Java servlets can be loaded dynamically,so a servlet can be loaded on-the-fly with-out bringing down the server.

Java servlets can be used to replace CGIscripts.

Servlets are added to the server and config-ured by using the Administration Tool.Select Web Service, then the Servlets but-ton.

Several sample Java servlets are includedwith the Java Web Server. They are listedunderhttp:// host:port/examples/ .

Custom servlets can be written using theServlet API found in the JSDK along withthe JDK.

Java ServletBeans/JavaBeans

A servlet bean is a servlet that adheres to

the JavaBeansTM design pattern for get-ting and setting properties. A servlet beanhas all the benefits of a regular Java Bean.

Beans may or may not have a user inter-face, depending how they are used.

For more details on JavaBeans go tohttp://java.sun.com/beans/

Servlet beans can be used like any otherservlet. For example, the template or ses-sion tracker servlets could be Beans as wellas servlets.

Java Beans can also be integrated into exist-ing servlets or.jsp files. These would beBeans with no user interface.


http://java.sun.com/beans/


-
Java Server Pages(JSP)
JSP technology integrates HTML andJava for a powerful and portable solutionto problems of dynamic content genera-tion and maintenance.

JSP technology is based on the “openstandards” process.

The.jsp file includes embedded scriptinglanguage. The JSP syntax is parsed and processed into a servlet on the server side, thussending dynamic content back to the client.

Secure Area Sand-boxes

Secure area sandboxes allow remote serv-lets, like applets, to be isolated into pre-defined spaces so that they do not damageor infect each other. As a result, the com-pany's exposure to security risk is greatlydecreased. Java Web Server supportstrusted and untrusted servlets as part ofthe Java Security Model.

SeeSection1.3 for more information.

The Java Web Server does this for you.Untrusted servlets are run in a separatethread (a “secure sandbox”), where theycannot perform potentially dangerous oper-ations such as opening files.

Access ControlLists (ACLs)

Java Web Server provides dynamically-configurable access control lists (ACLs)to control which authenticated user getsaccess to specific web site files or serv-lets.

Access control lists are set in the Adminis-tration Tool under Security.

Note: ACLs are a standard part of the JDK1.1 interfaces.

Digital Signatures Digital signatures are used to let trustedorganizations “vouch for” code.

Digital signatures might be used to let serv-lets run “outside of the sandbox” eventhough they have been loaded remotely.

Secure SocketLayer (SSL)

Java Web Server with Secure SocketsLayer version 3.0 is available for US andCanada, and internationally if certainencryption regulations are met (HTTPSservice).

SSL provides authentication of your webserver to its clients, encryption of clientdata to your web server, integrity protec-tion, and when appropriate, authentica-tion of clients to your server.

Instructions for how to use the SSL featurecan be found in the documentation underSecurity.

Included is how to useauthstore , a utilityto generate a certificate for authentication.Note thatauthstore must be used exactlyas the instructions say, or it will not work.

TABLE 1. Detailed Overview of Product Features, Advantages & Benefits (Continued)




HTML Generation Java servlets can generate HTML dynam-ically, so HTML will only be created andsent to the client (browser) when the webpage is accessed.

A servlet can be written to output HTMLtext by explicitly sending HTML output tothe client using code in the following form:

out.println(“<H1> Test</H1>”);

Additionally, the output of the servlet canbe included by means of the<servlet>tag of Server-Side Include (.shtml ) filesusing code in the following form:

<SERVLET code= fooServlet InitParam1=InitValue1 InitParam2=InitValue2> <PARAM NAME=requestParam1 VALUE=requestValue1 <PARAM NAME=requestParam2 VALUE=requestValue2 </SERVLET>

When a .shtml file is requested by a client(browser) and it contains a<servlet> tag,the content of the .shtml file up to the<servlet> tag is sent verbatim to the cli-ent. Then the servlet named in the<serv-let> tag is loaded and executed, and it’souput is sent to the client. This is followedby the remainder of the contents of the.shtml file after the</servlet> tag.

Page Compilation(now deprecated)

Java servlets can generate dynamicHTML pages from hybrid HTML/Javasource files. ThePageCompileServletis loaded and initialized like any otherservlet.

Now deprecated in favor of Java ServerPages.

ThePageCompileServlet enables youto embed Java code in static HTML pagesand compile these hybrid HTML/Java pages(.jhtml ) into Java servlets. The resultingservlets blend the static HTML content withdynamic content derived from the embed-ded Java code.





Java

Javaices

e

1.2 Java Web Server Architecture Details

Details of the Java Web Server architecture are shown in section 1, Diagram of theWeb Server Architecture”.

The Java Web Server handles HTTP requests with its Web Service. In addition theWeb Server can handle HTTPS requests with its Secure Web Service. These servuse internal servlets which are part of the Java Web Server.

Servlets are dynamically loaded, although servers will usually provide an option toforce loading when the server starts up. For example, the servlet which controls thAdministration Tool is loaded when the server starts.

Session Tracking Session Tracking is a mechanism forbuilding a sophisticated, stateful modelon top of the web's stateless protocol. Itcan maintain state and user identityacross multiple page requests. It can alsoconstruct a complex overview of userbehavior that goes beyond reporting ofuser hits.

Session tracking interfaces are in thejavax.servlet.http package.

Presentation Tem-plates

The Presentation Templates allow you tocustomize the appearance of HTML doc-uments.

If you have a large set of documents, youcan establish the way they all appear, justby writing one template. This is espe-cially helpful if many authors are writingor changing the documents.

Specify a particular set of files, and a gen-eral appearance to be applied to each ofthose files whenever they are viewed by abrowser. If one of the specified files isopened by a browser being served by theJava Web Server, then thetemplate serv-let processes the file before it is passed tothe browser. The result is that the file is dis-played with the specified appearance.

Virtual Host Sup-port

Host document collections from a singlemachine as if they were located on differ-ent machines. Use DNS to map real andvirtual host names to different domainnames.

Specify additional host names and docu-ment roots. Requests are fulfilled based ontheHost: header.





theroverlocalinto

igna-uches

l per-

FIGURE 1. Diagram of the Java Web Server Architecture

1.3 Java Web Server Security Details

1.3.1 Servlets and SecurityThe Java platform provides a Security Manager which can be used to control wheactions such as network or file access are permitted. By default, all servlets loadedthe network are untrusted and are not allowed to perform the above actions. Only servlets are fully trusted and are granted all privileges. Local servlets are those builtthe Java Web Server and those in the localservlets directory which is controlled bythe server administrator.

Servlets which have been digitally signed as they were put into Java archive (JAR) filescan be trusted and granted more permissions by the Security Manager. A digital sture on executable code indicates that the organization which signed the code “vofor it.”

When executed using Java 2, servlets executed on JWS can be granted additionamissions through adding the required policy to theserver_root/secu-rity/jserv.policy file usingpolicytool .

(HTTP)

WEB SSI SERVLET

INVOKER SERVLET

CGI SERVLET

HTTP REQUEST

SERVLETS USED INTERNALLY BY THE SERVER

SERVLET 1

(THIS REQUESTCOULD INVOKE

A SERVLET)

APPLET

SERVLET 2

TRUSTED DIRECTORYREMOTE SERVER

JAVA WEB SERVER

SERVLET 5

SERVLET 6

TRUSTED CLIENT

SERVLET 7

LOCAL FILE

(SAME MACHINE ASJAVA WEB SERVER)

SERVLET 4

SERVLET 3

(HTTPS)

SECURE WEB

OTHER SERVLETS

SERVICE

SERVICE



r Javaserverme,re

b-g on

5d

thetored

. The

ver.

d

ddsuTTPStures

lly”

t cardwell.

1.3.2 Resource ProtectionResources include files, directories, and servlets that can be accessed through youWeb Server. Resources are not protected by default, but for each resource on the that you want to protect, you may specify a security realm, an authentication scheand an access control list. This will limit who can access resources and how they aused.

• Security Realms – Realms are a way of logically breaking down security into susets. The Java Web Server comes with some of the following realms, dependinwhat environment you are using:

UNIX ® – Applies only to users of the UNIX environment. It is the same data-base of users as the one listed by the UNIXgetpwent() routines. This realmlets the server use HTTP Basic authentication with users' UNIX passwords.

NTRealm – Applies only to users of the Microsoft Windows NT environmentand therefore is only available in the Win32 version of this product. It displaysthe users on the NT system.

defaultRealm– The realm for controlling the example servlets. This realm canalso be used for general management of users and groups.

certificateRealm – Used to protect resources for users using Secure SocketsLayer (SSL) for authentication. This realm is only packaged in the versions ofthe product which include SSL.

servletMgrRealm – Used exclusively for signed servlet support, which is usedprimarily by software publishers. Holds the X.509 certificates used to authenti-cate those publishers.

• Authentication Scheme – The authentication scheme choices are Basic and MDDigest Authentication. Basic sends plain text passwords across the network anDigest sends “functions of passwords,” so with Digest, eavesdroppers can’t readpasswords. Note that with both authentication schemes the passwords must be sas text on the server, so if the server is broken into, the passwords may be foundJava Web Server administration pages are by default controlled through Digestauthentication.

Note: Most browsers only support Basic authentication at this point.

• Access Control Lists– Access Control Lists (ACLs) are used to protect controlaccess to files (which can be HTML pages), directories and servlets on the serACLs assign permissions to users and groups, such as the permission toGET a webpage. ACLs may also deny permissions. Users, groups, and ACLs are all scopewithin a realm.

1.3.3 Secure Web Service – Secure Sockets Layer (SSL)The Secure Sockets Layer is a general-purpose network security protocol which aanother layer of security on top of the already available security features. When yoenable the secure web service on your Java Web Server, you are able to run an Hserver with these added capabilities. In normal usage, SSL provides up to four feato your TCP connections:

• Your web server is authenticated to its clients, so that they can tell who you “reaare. Public Key Certificates are used to do this authentication.

• All requests to your web server are encrypted so that client data (such as credidata) is kept confidential. The responses from your web server are encrypted as



d

own

man-then

fmbi-

theresritycep-ces-arya 2".

am-

to

• The data is protected against being tampered with by a third party. This is calleintegrity protection.

• When appropriate, clients can authenticate themselves to your server using theirPublic Key Certificates.

Authstore is the tool that is used with the Java Web Server package to create and age server certificates. Only certificates generated with this tool can be used with Java Web Server. Instructions are included with the utility. Additional information oSecure Web Service is available at:http://www.sun.com/software/jwebserver/techinfo/docs.html .

1.3.4 Java 2 SecurityOn the Java 2 platform, the Security Manager uses policy files which define a list oavailable permissions. The total permissions for an item are set by the following conation:

Total permissions = Base permissions + ACL permissions + policy file permissions

In JWS 2.0, the policy file permissions are controlled through theserver_root/secu-rity/jserv.policy file which uses the default policy file syntax.

Because the JWS security manager has been changed to accommodate JDK1.2, may be times when a servlet attempts a specific operation for which its permissionunder the old security manager do not match the permissions under the new secumanager. This difference in permissions may result in Security or AccessControl extions where there no problem existed before. To fix this problem, determine the nesary privileges and add them to the policy file. For information on locating the necesspermissions, see Section 8.4.10, "Debugging Security Manager Problems with Jav

In addition to the base permissions, the defaultjserv.policy file has three JWS-spe-cific permissions that are needed to access certain JWS functionality. These are:

RuntimePermissions checkRealmAccess

RuntimePermissions checkServletAccess

RuntimePermissions checkSetSessionDirectory

For servlet operation to work correctly, these permissions must be granted for thelibcode base (file:${server.root}/lib/- ).

1.4 New in Version 2.0

The following features and their documentation are new in this release.

• Sample servlets moved. Samples servlets are no longer stored under thesystem/directory or listed by default on the servlets screen of the Administration Tool. Sple servlets are now in the JWS top-levelexamples/ directory (along with informa-tion on what the sample does and how to run it), and their classes are in theservlets/sunexamples/ directory.

• The product documentation directory is at the top-level JWS installation (eg,server_root/doc ). In addition, a default file-alias has been set up to allow access


http://www.sun.com/software/jwebserver/techinfo/docs.html


ess-

om-

nica-

JREta-oween

asrted.

elop-rt).

heseevel-dedasedemsbut

fol-

isr leg-

be

the documentation through the URL:http:// host:port/doc/ . It is recommendedthat this file alias be removed when JWS is deployed to avoid inadvertently accing the JWS product documentation.

• The Administration Tool is based on JDK 1.1 and therefore requires a JDK 1.1-cpatible browser. This should pose little difficulty as recent versions of the majorbrowsers are acceptable, including: Netscape Navigator 4.06, Netscape Commutor 4.5, Microsoft Internet Explorer 4.0, and HotJava Browser 1.1.5.

• Java Runtime Environment (JRE) 1.1.7 installed and used by default. The new is expected to further enhance JWS’s performance. Using the Solaris implemention of the JRE, rather than the reference implementation, means threads are nnative and not green as earlier. Consequently, command options referencing grthreads are no longer valid. For instance, the-threads green option of thehttpd(or jserv ) command is no longer valid. Other releases of the JDK or JRE (such1.1.6) may also work with JWS 2.0, but they are untested and therefore unsuppo

• Java 2 SDK (formerly code-named “JDK 1.2”) supported but not bundled. Whenusing-javahome option, you must point to a full JDK image (which includesjavac ). For Java 2 support on Solaris, this means that you must install the devment tools package (SUNWjsdev) in addition to the runtime package (SUNWj2For the latest Solaris Java 2 SDK and associated OS patches, please see:http://www.sun.com/solaris/java .

• JavaServer Pages 1.0 supported. Earlier JWS 2.0 Betas supported JSP 0.92. Ttwo specifications differ significantly and developers should not expect pages doped with 0.92 to be compatible with 1.0. JSP-specific information has been adto the JWS 2.0 on-line documentation. JavaServer Pages technology, which is bon the “open standards” process, is a powerful and portable solution to the problof dynamic content generation. JSP 0.92 examples are shipped for compatibilityare not supported.

• Java Servlet API 2.1 supported. Due to changes made for security reasons, thelowing Servlet API methods now return NULL (or an empty enumeration):

javax.servlet.http.HttpSessionContext.getIds()

javax.servlet.http.HttpSessionContext.getSession(String id)

javax.servlet.ServletContext.getServlet(String name)

javax.servlet.ServletContext.getServletNames()

javax.servlet.ServletContext.getServlets()

There is on-line documentation regarding the changes from version 2.0 to 2.1(servlets/servlet_20-21changes.html ).

Refer to section 8.1.1, Running Servlet Compatibility Mode, if needed.

• Page Compilation is deprecated in favor of JSP. Page Compilation files (.jhtml )will run under JWS 2.0 but such support is not guaranteed in future releases. Itrecommended that you use JSP for new development and consider porting youacy applications to this new standard.

• Session tracking has changed. There is a Session Service to allow sessions totracked server-wide across services. Its properties are in theserver_root/proper-ties/server/javawebserver/sessionservice/ andserver_root/proper-ties/service_defaults/sessionservice/ directories.


http://www.sun.com/solaris/java


ta-

-u-

Se you

ica-

• Simple proxy service was removed.

• The jserv startup script has been revised to improve functionality, increase porbility between different VM implementations, and aid in troubleshooting startupproblems. These changes were made to the design:

For javawebserver VM, located inserver_root/properties/server/jav-awebserver/vmargs.txt.

These changes were made to thejserv command-line arguments:

• Theauthstore utility improved. The list of imported root certificates is now viewable. Authstore-specific information has been added to the JWS 2.0 on-line docmention.

• Thesecure_html / directory contains the default secure service homepage for JW2.0, whilepublic_html / is the default webpage directory. [In JWS 1.1.3, the samdefault directory was used for both the webpage and secure services (althoughcould choose to use different ones.]

• NetDynamics plug-in servlet provided. Thendservlet servlet forwards URLrequests to an intermediary plug-in server (provided with the NetDynamics Appltion server) which then passes them to the application server.

1.4.1 Bug Fixes

Important bugs fixed in this release:

• 4079442 Encoded URL sessionIDs are not parsed correctly

• 4098713 Cannot load remote servlets as.class files

• 4143172-D command line parameters passed tojserv script are sometimes lost

• 4147152 Incomplete servlet tag in.shtml file freezes Java Web Server

• 4184074 Servlet alias names are case-sensitive

• 4184114java.lang.Throwable being caught but not logged by servlets

• 4184118 Modified servlets not always reloaded

• 4184122HttpServletRequest.getRequestUri() should not return querystring

• 4185256 Authstore sometimes does not start in Solaris environments

• 4185805 MIME-based servlet chaining may loop on itself

• 4186784 Directory separators are not written correctly

vmargs.txt File for providing arguments to VM. One file per VM.

-D Still supported but system properties that contain spaces must now bequoted. Defines system properties to be passed to theadminserver andjavawebserver VMs.

-threads No longer supported as-green or -native (default) can be specified invmargs.txt file instead. Used to set threads asnative or green for theserver.

-javacmd NEW. Allows the user to specify the java runtime executable to invoke,such as,java_g or jrew .

-classpath Deprecated in favor of-cp . Prepends specified path to that of theCLASS-PATH environment variable.



d-

ing

p

it is

• 4191867getRealPath() incorrectly calculated for virtual hosts

• 4192745getResource(String) andgetSystemResource(String) fails forservlets

• 4192980 MIME type for MIDI files not recognized

• 4193033 JWS becomes unresponsive after exceptions or errors

• 4194224 Directory path names are sometimes not fully parsed

• 4194239 Using invoker servlet andssinclude displays page source

• 4195147 Invoker servlet does not checkrules.properties file

• 4198423CAstore file should be stored in JWS install directory, not home

• 4198978 JWS displays “500 Server Error”; Log shows “Unrecognized SSL hanshake”

• 4198981 JWS displays “500 Server Error”; Log shows “Socket Closed”

• 4202853 Can’t invoke *.shtml file as a welcome file

• 4200500 Class loader errors not trapped and logged

• 4208402 Exception writing a byte array >64k elements to a socket

• 4209670 Templates don’t work when virtual hosts are used

• 4209727 Log filesreferer_log andagent_log do not contain timestamps

• 4210600getRealPath() method doesn’t return the absolute path

• 4210616 Requesting.jhtml files do not maintainkeepalive

• 4211277 while calling servlet chain: can’t mix text and binary input

• 4212948 Windows: colon delimiters in system properties causes path conflicts

• 4216095 File names are case-sensitive in Windows (95/NT) environments

• 4217281 JWS does not handle If-modified-since header correctly

• 4218341 JWS does not limit the size ofHTTP headers

• 4218524 File aliases not functional in Windows (95/NT) environments

• 4218837 Incorrect Java runtime is used to start the javawebserver

• 4211983 SSI: When use #include with virtual, file attribute is ignored

• 4220526 CGI programs do not propagate stderr information to error log

• 4225356 Unable to chain more than one servlet with MIME-based servlet chain

• 4236096 NT: servlets don’t reload and can cause JWS to go into an infinite loo

1.5 Localization and Internationalization

This release supports internationalization. JWS 2.0 is mostly internationalized but not localized. It has not been tested under any locale other than US English.


Product Distribution

with

unc-

p-d”

isSSL is

icato a

.er soft-ernce.and

ng

and

isss,nths

2.0 Product Distribution

Java Web Server is packaged and sold for the SolarisTM and Microsoft Windows envi-ronments, either electronically or in packaged form. Go tohttp://www.java.sun.com/software/jwebserver/buy/index.html to either buy or try the product.

2.1 Java Web Server 30-Day Trial

You can evaluate the Java Web Server free of charge for 30 days. Only the versioninternational SSL is available for this trial period. Downloads are available for bothSolaris and Microsoft Windows. After 30 days, the Java Web Server will cease to ftion, at which time you can choose to purchase the Java Web Server if desired.

The trial installation cannot be converted to a full licensed version, i.e., any develoment of servlets and other content will have to be migrated over to a full “purchaseinstallation of the JWS.

2.2 Java Web Server Purchase

The cost of Java Web Server 2.0 is $295 for the version with domestic SSL, whichavailable in the US and Canada. An international version of Java Web Server with is available for $295 if certain encryption exportation regulations are met. The cost$150 if trading up from a previous release of JWS.

Information about educational licenses can be found athttp://www.sun.com/edu/index.html .

2.3 Product Transition

JWS 2.0 will be the last release of this product in its current form. In late 1998, AmerOnline (owner of Netscape Communications) and Sun Microsystems, Inc. entered in3-year agreement for joint development and marketing of certain key technologiesReferred to as iPlanet, one of the first areas to be addressed was that of web servware. The decision was made to consolidate existing Sun and Netscape web servproducts to create a stronger, more focused line of server offerings under the AlliaOf the two companies’ existing four web servers, Netscape Enterprise Server (NES)FastTrack (Developer Version of NES 4.0) were chosen as the vehicles for providiweb server functionality going forward. Critical features of the other 2 web servers(namely, JWS and Sun Web Server) will be integrated into future releases of NES FastTrack.

Refer tohttp://www.sun.com/software/jwebserver/transi-tion/faq.html for more discussion on this.

Refer tohttp://home.netscape.com/netscape/alliance/index.html formore information on the Sun/Netscape Alliance.

With the release of JWS 2.0, JWS 1.1.3 enters the End-of-Life (EOL) process; thisstandard procedure when a new release is introduced. As a part of the EOL proceJWS 1.1.3 customers with support contracts continue to receive support for 12 mo


http://www.java.sun.com/software/jwebserver/buy/index.html

http://www.java.sun.com/software/jwebserver/buy/index.html

http://www.sun.com/edu/index.html

http://www.sun.com/edu/index.html

http://www.sun.com/software/jwebserver/transition/faq.html

http://www.sun.com/software/jwebserver/transition/faq.html

http://home.netscape.com/netscape/alliance/index.html

Requirements and Dependencies

er.on-

ent,ludesSique

webelop-

erv-men-

after JWS 2.0 ships, or as otherwise specified in the support contract, whichever islonger. This support is provided by Sun through existing channels.

As JWS 2.0 will be the final release of the JWS product line, its EOL period is longTypically, it is three years from the final release date for all customers with support ctracts.

While NES and FastTrack are full-featured web servers and include a Java environmthey are not at the same specification level as JWS 2.0. For example, NES 4.0 incJSP 0.92, while JWS 2.0 includes JSP 1.0; both support Servlet API 2.1. Also, JWincludes support for JHTML, servlet chaining, presentation templates, and other unfeatures. A technical migration white paper is forthcoming that will describe what isrequired to move an application.

FYI: The Jakarta Project (announced at JavaOne 1999) is an Apache open-sourceserver working group that is taking the source code for Sun’s JavaServer Web Devment Kit (JSWDK is Sun’s reference implementation for Servlet and JSP; it is NOTJWS which is Sun’s production implementation) and merging it with Apache Jserv slet engine. The goal is to provide a superior 100% Pure Java Servlet and JSP impletation for Apache. Refer tohttp://jakarta.apache.org/ .

3.0 Requirements and Dependencies

3.1 System Requirements and Dependencies

3.1.1 Disk Space Needed to Install Java Web ServerPlease note that these downloads are large.

Solaris

• The compressed download file size is approximately 12 Mbyte

• To install, approximately 20 Mbyte of free hard drive space is needed

Microsoft Windows NT/95

• The compressed download file is approximately 9 Mbyte

• To install, approximately 15 Mbyte of free hard drive space is needed

3.1.2 Recommended System Configurations

Solaris

Minimums:

• Sun SPARCstationTM 5 workstation

• 32 Mbyte RAM

• Solaris 2.5.1 - plus the following patches:

103566-25 (X11/OpenWindows)


http://jakarta.apache.org/


.0 on

.0 on

timeay

103640-17 (Kernel)

Recommended:

• Sun UltraTM 1 (or later version) workstation

• 64 Mbyte RAM

• Solaris 2.6

There are 3 recommended patches that should be installed before using JWS 2Solaris 2.6 with JRE 1.1.7:

105181-10 (or newer) - Kernel patch

105284-15 (or newer) - Motif Runtime Library Patch

105490-04 (or newer) - dynamic linker patch

There are 6 recommended patches that should be installed before using JWS 2Solaris 2.6 with Java 2 (formerly code named JDK 1.2):

105181-11 (or newer) - Kernel patch

105210-17 (or newer) - LibC patch

105490-05 (or newer) - Linker patch

105568-13 (or newer) - Libthread patch

105633-12 (or newer) - OpenWindows 3.6:Xsun Patch (fonts)

105669-04 (or newer) - CDE 1.2:libDTSvc Patch (dtmail)

Note: At this time there are no required patches to run the JWS 2.0 bundled run(1.1.7_05 ) on Solaris 7. But, if you are going to use a different runtime, you mneed patches. For example, if you are going to run JWS 2.0 against Java 2(JDK1.2.1_03 ) on Solaris 7, then you should download and apply the patchesrequired forJDK1.2.1_03 available athttp://www.sun.com/solaris/java /.

Microsoft Windows

Minimums:

• Intel 486-based PC

• 32 MB RAM

• Microsoft Windows 95 (with Winsock 2) or Microsoft Windows NT 4.0 (or laterversion)

Windows Sockets 2 (WinSock 2) may be downloaded from Microsoft athttp://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/default.asp .

Special Note for Windows 95 Users: Windows 95 is supported as a development anddemonstration platform only. It is not supported as a server deployment platform.Microsoft does not recommend the use of Windows 95 as a server platform.

Recommended:

• Intel Pentium 166 (or higher)-based PC

• 64 MB RAM


http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/default.asp


http://www.sun.com/solaris/java/


net-orks therdur

)

laterve.,e this

ener-ga-

theut

cantternion is

• Microsoft Windows NT 4.0 with Service Pack 4 (or higher)

Note: Service Pack 4 can be downloaded from Microsoft athttp://www.microsoft.com/ntworkstation/downloads/Recom-mended/ServicePacks/NT4SvcPk4.asp .

3.1.3 Supported Hardware Platforms / Required Boards or PeripheralsThe Java Web Server is not hardware specific. You may, however, need to have a work card installed on your machine in order to use the Java Web Server. The netwcard does not have to be connected to a live network. Just installing the card makeoperating system load the appropriate Internet Protocol (IP) drivers. Without the cainstalled the drivers don't get loaded and therefore sockets cannot be opened to yoserver.

3.2 Software Requirements and Dependencies

3.2.1 Operating Systems and Versions Supported

• Solaris Operating System 2.5.1 (or later version) with patches (seeRecommendedSystem Configurations). (X86 is not officially supported)

• Microsoft Windows NT 4.0

• Microsoft Windows 95 – Supported for development, but not for deployment(because Microsoft does not support Microsoft Windows 95 as a server platform

While Java Web Server currently works in environments that have JDK 1.1.7 (and versions) support, support is only offered for the operating systems mentioned aboFor up-to-date information on whether your target environment supports JDK 1.1.7please contact the environment's vendor. The Java Web Server team does not havinformation.

3.2.2 Recommended Amount of Swap Space (Solaris Operating Environment Only)The recommended amount of swap space is whatever is normal for your system, gally twice the amount of memory you have. For example, if your system has 32 mebytes of memory then your swap space should be 64 megabytes.

3.2.3 Recommended Heap SizeThe Java Virtual Machine (VM) limits the size of the heap that a program, such as Java Web Server, can use. By default the Java VM limits the heap size to 16 MB, byou can set the upper bound of the heap size with the-mx option. This option is passedto the Java VM at startup.

For example, to set the maximum heap size to 32 MB, pass-mx32m to the Java VMstartup: “jserv -vmargs -mx32m ”. Alternatively, edit thevmargs.txt propertiesfile to set this value.

The heap limit helps determine when a garbage collection (GC) will take place. Youset the limit high to avoid a GC, but then you could end up paging. Generally, it is beto take the hit from a GC fairly often and to avoid paging. The other thing to keep imind about garbage collection is that the entire server stops while garbage collect


http://www.microsoft.com/ntworkstation/downloads/Recommended/ServicePacks/NT4SvcPk4.asp

http://www.microsoft.com/ntworkstation/downloads/Recommended/ServicePacks/NT4SvcPk4.asp


his.

esizest betionice

ormsver-

ey

as4.0,

yousuch

de.

serK

apeuers.

going. If you have an occasional, very long GC, the clients will hang for that time. Tleads to more variability in service quality than with more frequent but smaller GCs

The server caches files in memory to avoid going to disk. You can set the size of thcache that the server will use for this purpose. However, you need to coordinate theof the cache with the size of the heap that the Java VM uses: the size of the heap muat least the size of the cache, and it should allow some breathing room for the allocaof other objects. Typically the server should run with the heap size set to be about twthe cache size.

If you seeOutOfMemory errors written to your console or the error log, you need toincrease the heap size or decrease the cache size.

3.2.4 Other Software RequirementsTo run the Java Web Server, you need a Java Runtime Environment (JRE) that confwith the JDK 1.1.7 (or later versions). For many environments, you can download asion fromhttp://java.sun.com/products/OV_jdkProduct.html . TheMicrosoft Windows and Solaris distributions of JWS 2.0 take care of this for you; thare bundled with the JRE 1.1.7.

To run the JWS administrative tools you need a JDK 1.1-compatible browser, suchNetscape Navigator 4.06, Netscape Communicator 4.5, Microsoft Internet Exploreror HotJava Browser 1.1.5.

You also need to have the appropriate IP drivers installed on your machine so thatmay use the IP protocol. These are automatically installed with some components,as network cards or internet access software.

Microsoft Windows 95 Only

In Microsoft Windows 95 you need Microsoft Windows Sockets 2 (WinSock 2).WinSock2 may be downloaded from Microsoft's site at:

http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/default.asp.

You cannot run the Java Web Server on Microsoft Windows 95 in disconnected moThis is because Microsoft Windows 95 will not recognize local host with WinSock2installed. This problem does not affect Microsoft Windows NT 4.0, which ships withWinSock2.

3.3 Product Compatibility

3.3.1 Interoperability with Existing Third-Party SoftwareThe Administration Tool may not work on all web browsers. It depends on the browbeing JDK 1.1-compatible (which most browsers are), or compatible with a later JDversion. The following browsers are known to work: Netscape Navigator 4.06, NetscCommunicator 4.5, Microsoft Internet Explorer 4.0, and HotJava Browser 1.1.5. Yomay not be able to administer Java Web Server if you use older or beta web brows


http://java.sun.com/products/OV_jdkProduct.html



Installing Java Web Server

erv-ajorerves

full

ent

3.3.2 Backward/Forward Compatibility with Other ReleasesBetween minor releases (1.0 to 1.1) the product will be forward compatible (i.e., a slet which runs on Java Web Server 1.0 will run on Java Web Server 1.1). Between mreleases (1.x to 2.x), there will be no guarantees. In other words, Java Software resthe right to break 1.x compatible components in 2.x.

3.3.3 Versions

• Java Web Server 1.0 – Made available, but never sold

• Java Web Server 1.0.1 – Made available, but never sold

• Java Web Server 1.0.2 – Made available and sold as bugfix release for 1.0.1

• Java Web Server 1.0.3 – Made available and sold as bugfix release for 1.0.2

• Java Web Server 1.1 – Made available and sold

• Java Web Server 1.1.1 – Available as free bugfix release for 1.1

• Java Web Server 1.1.2 – Available as free bugfix release for 1.1.1

• Java Web Server 1.1.3 – Available as free bugfix release for 1.1.2, also sold as

release

• Java Web Server 1.1.3 patch 1 – Available as free bug fix release for 1.1.3

• 107511-01 Solaris Global 1.1.3 patch

• 107512-01 Solaris Domestic 1.1.3 patch

• 107513-01 Windows Global 1.1.3 patch

• 107514-01 Windows Domestic 1.1.3 patch

• Java Web Server 2.0 – Available now for purchase

3.4 Product Upgrades

3.4.1 Java Web Server MigrationPlease seeAppendixA: JavaWebServer, Migrating1.1.3to 2.0for information on howto migrate your JWS 1.1.3 customizations to JWS 2.0.

4.0 Installing Java Web Server

4.1 Pre-Installation Considerations

4.1.1 Solaris Only: Packages Necessary for Running with Java 2To run JWS 2.0 with the Java 2 SDK, you must use this startup command:

jserv -javahome path to Java 2

When using-javahome option, you must point to a full JDK image (which includesjavac ). For Java 2 support on Solaris, this means that you must install the developmtools package (SUNWjsdev) in addition to the runtime package (SUNWj2rt ).



ntuire

,

llingf

che-

k.

ith

laris

laris

4.1.2 Solaris Only: Applying Necessary Solaris OS PatchesJava Web Server 2.0 bundles and uses the Solaris 1.1.7 Java Runtime Environme(JRE). JWS 2.0 can also be used with the Java 2 SDK, Standard Edition. Both reqpatches on the Solaris platform.

On the JWS 2.0 CD, the necessary patches can be found in thesolaris/patches/directory, eg,JDK1.1.7/1.1.7_08_sparc_jdk_patches.tar.Z.

If you downloaded JWS 2.0, you can get the necessary patches athttp://www.sun.com/solaris/jdk/download.1.1.7_08/ (for JDK 1.1.7) orhttp://www.sun.com/solaris/jdk/download.1.2.1_02/ (for Java 2).

Install the patches appropriate for your version of Solaris, and for the desired JDKbefore installing JWS 2.0. For the latest patches, seehttp://www.sun.com/solaris/java/ .

It is highly recommended that you keep your Operating System up to date by instathe full set of patches available for your platform, rather than just the minimal set opatches noted for running the JRE/JDK.

This recommendation is made because other bugs may exist on your platform whimay interact unfavorably with your applications and result in minor to major inconvniences for you. For the latest set of patches for your operating system level, seehttp://sunsolve.sun.com/ . Under Free Services, choose the Public Patches lin

The following 2 patches must be installed before using JWS 2.0 on Solaris 2.5.1 wJRE 1.1.7:

• 103566-25 (or newer) - X11/OpenWindows patch

• 103640-17 (or newer) - Kernel patch

Installation of the following 3 patches is recommended before using JWS 2.0 on So2.6 with JRE 1.1.7:


• 105284-15 (or newer) - Motif Runtime Library Patch

• 105490-04 (or newer) - dynamic linker patch

Installation of the following 6 patches is recommended before using JWS 2.0 on So2.6 with Java 2 (formerly code named JDK 1.2):


• 105210-17 (or newer) - LibC patch

• 105490-05 (or newer) - Linker patch

• 105568-13 (or newer) - Libthread patch

• 105633-12 (or newer) - OpenWindows 3.6:Xsun Patch (fonts)

• 105669-04 (or newer) - CDE 1.2:libDTSvc Patch (dtmail)


http://www.sun.com/solaris/jdk/download.1.1.7_08/

http://www.sun.com/solaris/jdk/download.1.2.1_02/

http://sunsolve.sun.com/



ouervere

ress

tyou

ablyistra-

stem

1. Determine your operation system version by typing “showrev ”.

2. List the patches installed on your system by typing “showrev -p ”.

If the required patches arenot installed, follow these steps to install the patches:

a. Become root (either login as root or use thesu command).

b. Extract the contents of the tar file onto a local disk.

At a command prompt, type:

# uncompress tar filename

# tar xvf each component extracted in previous command

For example, for the JDK 1.1.7 patches on Solaris 2.5.1 on CD, type:

# uncompress 1.1.7_08_sparc_jdk_patches.tar.Z

# tar xvf 1.1.7_08_sparc_jdk_patches.tar

# tar xvf 103566-25.tar

# tar xvf 103640-17.tar

For example, for the JDK 1.1.7 patches on Solaris 2.5.1 downloaded, type:

# tar xvf 1.1.7_08_patches_sparc_5.5.1.tar

# tar xvf 103566-25.tar

# tar xvf 103640-17.tar

c. Reboot into single user mode by typing “init s ”.

d. Install each patch by following each patch’s install instructions found in itsREADME file.

e. Reboot.

f. Remove the tar files and temporary extraction directories.

4.1.3 Solaris Only: Install as Root in Order to Run on Port 80 (Or Any Port NumberBelow 1024)On Solaris, port numbers less than 1024 are “protected” ports and run as root. If yplan to use the Java Web Server as your default web server (port 80), or to run the son a port number less than 1024, you must install and run the software as root. SeSec-tion 6.3, "Changing the Default Ports" for details on how to configure the server to runon port 80.

4.1.4 Solaris Only: Installation Occurs Upon Untarring the DownloadWhen you download the software, you get a compressed tar file. First you uncompthe file, then you untar it. Note that untarring the fileis the installation. User and groupidentification will be assigned to files and directories at this point, and this will affecwho can run the server. So if you want to install as root, be sure you are root beforeuntar the downloaded file.

Remember that even though you may have root access to your local drive, you probdon’t have root access to NFS-mounted directories unless you are a system admintor.

For users other than root, the user and group identification can be changed by the syadministrator after installation if necessary. SeeSection8.1.3 for more informationabout changing user and group identification.



thee 2):

SSLdft

(sees.

toer.

ate

4.1.5 VersionsDownload Versions

There are four versions of Java Web Server available for purchase by download —two types listed here are available for Microsoft Windows and for Solaris (see Tabl

• US & Canada Only version with Domestic SSL

• International version with International SSL

Packaged Versions

There are two versions of Java Web Server available in packaged form. A DomesticPackage contains both the Solaris and Microsoft Windows Domestic SSL downloafiles listed above. The International SSL Package contains the Solaris and MicrosoWindows International SSL download files mentioned above.

30-Day Trial Versions

There are also two versions of Java Web Server available for a 30-day trial period Table3). The International SSL version is available for Solaris and Microsoft WindowSeeSection2.1 for more information on trial versions.

TABLE 3. Java Web Server Download Files for 30-Day Trial

4.1.6 Java Runtime Environment (JRE)The Java Web Server 2.0 product ships with JRE 1.1.7, therefore you do not haveinstall the Java Development Kit (JDK) on your computer to run the Java Web ServYou can, however, choose to use your own JRE if preferred, by using the appropriscript supplied with the Java Web Server.

TABLE 2. Java Web Server Download Files for Purchase

Installation Version File Name Size

Solaris

Domestic SSL (US &Canada Only)

jwsr2_0-solsparc-do.tar.Z 12 Mb

International SSL(Global)

jwsr2_0-solsparc-gl.tar.Z 12 Mb

MicrosoftWindows

Domestic SSL (US &Canada Only)

jwsr2_0-win-do.exe 9 Mb


jwsr2_0-win-gl.exe 9 Mb

Installation Version File Name Size

SolarisInternational SSL(Global)

jwsr2_0-solsparc-try-gl.tar.Z 12 Mb

MicrosoftWindows


jwsr2_0-win-try-gl.exe 9 Mb



ver

rec-

efilesl.

S-an be “serv-

odi-

Serv-

4.1.7 Estimated Time Needed to InstallIt takes about 20 minutes to do the download and installation when downloading oEthernet. Downloads could take longer depending on the connection.

4.2 Installation Details

4.2.1 Default Installation Path

• Solaris – There is no default installation path. Installation occurs in whichever ditory the tar file is untarred.

• Microsoft Windows – The default installation path isC:\JavaWebServer2.0\ ; thiscan be manually changed during installation.

4.2.2 Changes to System Files

Solaris

No changes are made to system files during installation.

Microsoft Windows NT

If you have NT Administrator privileges and choose to install JWS as an NT servicthen after installation, new entries will have been made to your machine’s registry including the addition of the Java Web Server service to the Services Control PaneEntries can be found in the HKEY_LOCAL_MACHINE registry in:

\SOFTWARE\Sun Microsystems\Java Web Server

\SOFTWARE\Microsoft\Windows\CurrentVersion\App-Paths\jws2.0.exe

\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\Java Web Server 2.0

Microsoft Windows 95

No changes are made to system files during installation.

4.2.3 Directories Created at InstallationThe/ path_to_JavaWebServer/JavaWebServer2.0 directory (also referred to asserver_root) contains the following directories:

• admin – Administrative binary classes and Administration Tool applet.

• bin – Web server executables.

• cgi-bin – Default directory where CGI scripts are found on your system.

• classes – This directory is automatically added to the Java Web Server’s CLASPATH at startup. Java classes that you want loaded by the system class loader cplaced here. E.g., you may choose to put Servlet classes here instead of in thelets” directory. Note: classes placed here are not automatically reloaded when mfied. You must restart JWS to reload the modified classes. Typically duringdevelopment, you will place your servlet classes in theservlets directory to takeadvantage of servlet reloading by accessing the servlets by way of the Invoker let (http:// your_server/servlet/ ). For deployment, you may want to place



cu-ec-

ation

uct

erv-

r

his that

s file

the

u

is

tom

your servlet classes in thisclasses directory and access them through a servletalias. This method is more secure and efficient than using the Invoker Servlet.

• doc – This is the default Document Root Directory containing the JWS online domentation. When you first install the Java Web Server, the default document dirtory isserver_root/doc . You can change this to be any directory you choose, forexample, a document directory inside your own home directory.

In addition, a default file-alias has been set up to allow access to the documentthrough the URL:http:// host:port/doc/ . It is recommended that this file alias beremoved when JWS is deployed to avoid inadvertently accessing the JWS proddocumentation.

• examples - This directory includes examples of presentation templates, JSP, slets, servlet beans, server-side includes, RMI, and JDBC.

• jre – Java runtime

• lib – Web server binary libraries (jar files). You must restart the web server afteadding to this directory. This directory is automatically added to the JWSCLASS-PATH.

• logs – Log statistics for each of the services.

• native_lib – Native libraries used by servlets can be placed in this directory. Tdirectory is automatically picked up by Java Web Server at startup. This meansthe “native_lib ” directory is appended to theLD_LIBRARY_PATH(on Solaris) orPATH (on Windows) environment variable.

• properties – Web server configuration files

• public_html – This directory contains the default homepage for the Java WebServer. The initial file (index.html ) is meant simply as a placeholder and shouldbe replaced by your own homepage before you advertise your site to others. Thiis server_root/public_html/index.html, whereserver_rootis the directory ofyour installed Java Web Server.

• realms – Database of users, groups, and access control lists.

• secure_html – This directory contains the default secure service homepage forJava Web Server. Theserver_root/secure_html/index.html file is meant sim-ply as a placeholder and should be replaced by your own homepage before yoadvertise your site to others.

• security – This directory contains thejserv.policy file. When JWS is runwith Java 2, it defines the location of thekeystore file, and grants permissions forjar files in thelib directory, files in theclasses directory, local servlets, localservletbeans, and generated servlets. A good reference site for Java 2 securityhttp://java.sun.com/products/jdk/1.2/docs/guide/security/ .

• servletbeans – Default directory for servlets which are beans (jar files). Usesthe JWS custom class loader.

• servlets – Default directory for servlets; servlet examples. Uses the JWS cusclass loader.

• system – Documentation and error pages, alsosystem/sessionSwap/ which isused with session tracking and persistence.

Additional Directories Created for Solaris Installation Only


http://java.sun.com/products/jdk/1.2/docs/guide/security/


ing

er-

d

is

-le.

ss

n run

web

• etc – Startup scripts for the server.

• native – Sources for building Solaris-specific native code support (e.g., changUID and GID when starting server as root).

4.2.4 Directories Created After Running Java Web Server the First Time

• system/sessionSwap – Swap space directory used with session tracking and psistence.

• tmpdir –directory used by JSP and Page Compilation for dynamically generateservlets.

4.2.5 Daemons Started for the ApplicationTheCLASSPATH variable is handled by thejserv daemon, which can be started byeither thejserv or httpd scripts.

In all releases prior to Java Web Server 1.1, thehttpd daemon and script controlled theJava Web Server, notjserv . To acknowledge historical precedent, Java Web Servershipped with two scripts that sit in front of thejserv script—httpd andhttpd.nojre . Thehttpd script runs with the included JRE (in distributions thatinclude a JRE), thehttpd.nojre script runs assuming that you already have a properly configured Java Runtime Environment (such as the JDK) installed and availab

The Java Web Server runs under multiple processes. On Solaris, to find the procenumbers for the JWS processes, type:

% ps -eaf | grep jre

For example, these might be the results:

UID PID PPID ... CMD

user 25264 25261 ... /bin/sh bin/jserv -jre

user 25301 25264 ... server_root/jre/bin/../bin/sparc/native_threads/jre ...

user 25311 25301 ... server_root/jre/bin/../bin/sparc/native_threads/jre ...

Process 25264 is thejserv daemon. Process 25301 (a child of 25264) is the admin-server process. Process 25311 (a child of 25301) is the javawebserver process.

NOTE: “/usr/ucb/ps -auxwww ” gives more text output for each process, thus show-ing process25301 includes “-Dserver.name=adminserver ”, while process25311includes “-Dserver.name=javawebserver ”.

These last two processes control the Administration and Java Web servers and cain either thenative_threads or green_threads VM.

4.3 Tutorial: Download and Install Java Web Server

4.3.1 Solaris

1. Download the Java Web Server compressed tar file from the Java Web Server site,http://www.sun.com/software/jwebserver/buy/index.html . Thename of the downloaded file depends on the version you download. SeeSection4.1.5 for the available options.


http://www.sun.com/software/jwebserver/buy/index.html


le, ifp ithe

ro-ult,

oand

s

-ep it

2. Move the compressed tar file to the directory where you want to install the JavaServer software directory.

Note: The Java Web Server can be installed in any directory in your system. When youuncompress and install the tar file, theJavaWebServer2.0 directory is created withinthe current directory.

% mv tarfile directory

% cd directory

3. Uncompress the tar file. Enter:

% uncompress tarfile.Z

The tar file is now ready to be installed.

4. Install the contents of the tar file. Enter:

% tar -xvf tarfile

This creates a directory calledJavaWebServer2.0 , which contains the productrelease. TheJavaWebServer2.0 directory (and the path to it, if appropriate) isalso referred to asserver_root. This term is used throughout the Java Web Serverdocumentation and this training document.

5. After you have finished installing the Java Web Server, you can delete the tar fiyou wish. If you don’t have to delete it for space reasons, it makes sense to keefor a while. Then if you have to reinstall for some reason, you don’t have to do tdownload again.

4.3.2 Microsoft Windows 95 and Microsoft Windows NT

1. Download the Java Web Server self-extracting (.exe ) file from the Java Web Serverweb site,http://www.sun.com/software/jwebserver/buy/index.html .The name of the downloaded file depends on the version you download. SeeSection4.1.5 for the available options.

2. Double-click on the self-extracting file and follow the instructions in the Setup pgram to install Java Web Server in a directory location on your hard disk. By defaSetup installs Java Web Server inC:\JavaWebServer2.0 . TheJavaWebServer2.0 directory (and the path to it if appropriate) is also referred tasserver_root. This term is used throughout the Java Web Server documentationthis training document.

Note: You can install the Java Web Server in a different directory, but be sure the direc-tory name does not have any spaces in it. If there are spaces in the directory name, thimay cause problems for environment variables used by JWS.

3. If you are installing in Microsoft Windows NT, InstallShield will ask if you wantJWS to start automatically on system reboot (i.e., be an NT service).

If you click Yes, an entry is added to Control Panels→ Services and the Java WebServer will be set up to start automatically when your machine boots.

Note: You must have Administrator privileges to choose this option.

If you click No, no entry will be made to Control Panels→ Services. You can stillset up JWS to run as an NT Service later (seeSection6.2.2).

4. After you have finished installing the Java Web Server you can delete the downloaded file. If you don’t have to delete it for space reasons, it makes sense to ke


http://www.sun.com/software/jwebserver/buy/index.html


he

ult,. It isict

youse

ny

for a while. Then if you have to reinstall for some reason, you don’t have to do tdownload again.

4.4 Post-Installation Considerations: Verifying a Successful Installation

After you have installed Java Web Server be sure to read theREADME file and theRelease Notes.

You can confirm that the installation was successful by bringing up the Java WebServer’s default home page.

Manual start-up of the JWS is described below. You may wish to refer toSection 6.2,"Starting the Java Web Server Automatically", as well.

4.4.1 Tutorial: Start the Server (Solaris)

4.4.1.1 Using the Default Java Runtime EnvironmentJava Web Server 2.0 ships with a Java Runtime Environment (JRE 1.1.7). By defathe Java Web Server uses this included JRE and ignores your CLASSPATH settingrecommended that you unset your JAVA_HOME environment variable to avoid conflwith JWS’s Java setting. Given thatserver_rootis the location where you installed JWS,you would do the following:

% unsetenv JAVA_HOME

% cd server_root/bin

% ./httpd &

Note: Starting JWS with the-verbose option provides logs and other informationabout running the server to the standard output stream.

4.4.1.2 Using your Existing Java EnvironmentTo use your existing JDK and environment rather than the JRE provided with JWS,should use thehttpd.nojre startup script. You can use one of two approaches (theexamples assume/usr/java1.2 is the location of your full JDK):

1. You can choose to set yourJAVA_HOME environment variable to include your fullJDK location and then start JWS:

% setenv JAVA_HOME $JAVA_HOME:/usr/java1.2


% ./httpd.nojre &

2. You can explicitly pass your full JDK location when starting JWS (this overrides aJDK location that may be found in your JAVA_HOME):


% ./httpd.nojre -javahome /usr/java1.2 &


4.4.2 Tutorial: Start the Server (Microsoft Windows NT)Start the Java Web Server by following these steps:



com-can

thewill will

ur

ass-pe in

by

1. Go to the Network Control Panel -> Services

2. Select JavaWebServer

3. Click Start

The word “Started” will show next to the JavaWebServer entry.

4.4.3 Tutorial: Start the Server (Microsoft Windows 95)Starting the Java Web Server manually means issuing a command in a terminal ormand prompt window. The process is owned by the user issuing the command. Youminimize, but not close, the window in which the command was issued. If you closewindow or log off the system before shutting down the Java Web Server, the serverattempt to shut down but may leave some processes running. If this happens, youneed to end the orphan processes (jserv andjre ) using the Windows NT Task Man-ager.

Note: To see logs and other information about the running server in standard output,start the Java Web Server with the-verbose option.

1. Change to the bin directory under the Java Web Server installation.

C:> cd JavaWebServer2.0\bin

2. Choose the JRE or JDK you wish to use.

To use the bundled JRE (default), unset yourJAVA_HOME environment variable (ifset), and invokehttpd . For example:

C:> httpd

To use the JDK as set by yourJAVA_HOME environment variable, invokehttpdnojre . For example:

C:> httpdnojre

To explicitly set a JDK for this particular session of the server process, unset yoJAVA_HOME environment variable (if set), and invokehttpd with the-javahomeoption to indicate the JDK’s location. For example:

C:> httpdnojre -javahome C:\JDK1.2

3. If you have created a server certificate with Authstore, the server will require a pword during startup. Simply start the Java Web Server as indicated above and tythe passphrase when prompted.

4.4.4 Checking that the Server is RunningTo check that the server is running, connect to the web server default home page entering the URL for the server and port address in your browser’s locator field.

For example, the default port upon installation is 8080:

http:// your_server_name:8080/

Note: On Windows,your_server_name is the name specified in the Network ControlPanel -> Identification in the “Computer name” field.

You should see a web page with the following text:

Congratulations!



ay

t serverse

he the

per-

roper-

he

nd

If you have just installed the Java Web Server and can see an image of server Duke onthis page, it means that your Java Web Server has been installed correctly and is servingfiles properly.

4.5 Common Problems with Installation

4.5.1 Solaris

4.5.1.1 Download CorruptionIf the download is corrupted somehow, the error messagetar: directory check-sum error will appear after installing the contents of the tar file. Some directories mbe missing. Delete all the files and do the download again.

4.5.1.2 Avoiding Permission Problems When RestartingBefore restarting the Java Web Server under a new owner, the current owner muschange permissions (ownership) on certain files. This is necessary because somefiles are created after installation, when the server is first started. Ownership of thofiles is based on the user running the server at this initial time.

For example, when first installed, nosystem/sessionSwap/ directory is created.This directory is created by the server runtime the first time the server is started. Tfiles are owned by the user running the server at the time. If you run the server forfirst time as usernameA, this directory will be owned by usernameA. Subsequentrestarts of the server by any other user (including root) will result in failures due tomission problems.

To change permissions (ownership) on files, use thejschangeowner conveniencescript. The script changes the ownership of the files such as logs, sessionSwap, pties, and realms to allow writing by the new owner. To use the convenience script:

1. Become root.


# cd server_root/bin

3. Invoke the script

# ./jschangeowner -r server_root -o new_owner

whereserver_root is the installed JWS location andnew_owner is the user name ofthe person who will subsequently run JWS.

For example, if JWS was installed in the/opt directory and first started by root, butnow JWS will be started by usernameB, root would run enter this command from tserver_root/bin/ directory:

# ./jschangeowner -r /opt/JavaWebServer2.0 -o usernameB

4.5.2 Microsoft WindowsIf the download is corrupted somehow, the self-extracting file could be corrupted awill not install properly. Delete all the files and do the download again.


Uninstalling the Java Web Server

reused

e

ing

thel be

e

nd

d:

Do not install the Java Web Server in a directory with spaces in its name. If there aspaces in the directory name, this may cause problems for environment variables by JWS.

5.0 Uninstalling the Java Web Server

5.1 Stopping the Java Web Server

5.1.1 Using the Graphical User InterfaceThe recommended procedure for shutting down the Java Web Server is through thAdministration Tool as follows:

1. Connect to the Java Web Server’s Administration Tool through a browser by typits URL:

http:// machine_host_name: admin tool port/

For example: http://schnauzer:9090/

2. Log into the Java Server Administration Tool

3. Select the Java Web Server entry on the screen

4. Click the Shutdown button

Note: Clicking “Shutdown” closes down all JWS server and services but leavesautostart list (states) alone (i.e., all services running at the time of shutdown wilstarted when the server is restarted). Clicking “Stop” closes down the particularserver or service entry selected and removes it from the autostart list.

5.1.2 Using a Command LineAs an alternative to the recommended method of using the graphical user interfac(GUI) as described inSection5.1.1, here is a procedure for stopping the Java WebServer from the command line:


cd server_root/bin (Solaris)

cd server_root\bin (Windows)

2. Start the shutdown process.

./jsadmin user/ password -stop

For example, in the default username and password case, you would type:

./jsadmin admin/admin -stop

5.1.3 Microsoft Windows NTIf you started JWS from an MS-DOS window, you can select that MS-DOS window apress CTRL-C.

If JWS is installed and running as an NT service, you can use the following metho

1. From the Control Panel, select Services

2. Select Java Web Server


Uninstalling the Java Web Server

r’s

d

that

3. Click Stop

5.2 How to Uninstall the Java Web Server

It takes approximately 5 minutes to uninstall the Java Web Server.

5.2.1 SolarisTo remove Java Web Server from a Solaris machine:

1. Shut down the Java Web Server (seeSection5.1).

2. Remove the Java Web Server files manually:

% cd server_root

% rm -r *

3. If you created automatic startup scripts, remove them as well:

% rm /etc/rc3.d/S42jserv

% rm /etc/rc3.d/K42jserv

5.2.2 Microsoft Windows NTTo remove Java Web Server from a Windows NT 4.0 machine:

1. 1. Shut down the Java Web Server (seeSection5.1).

2. If you installed the NT service, manually remove it from the NT Service Manageregistry (i.e., de-register):

C> cd server_root\bin

C> jservsvc JavaWebServer remove

whereserver_root is the name you chose for the directory into which you installethe product. By default, the install program names that directoryJavaWebServer2.0.

3. Remove the Java Web Server itself:

a. Click on the Control Panel.

b. Click on Add/Remove Programs.

c. Highlight the Java Web Server entry then click on Add/Remove.

NOTE: On Windows NT 3.5.1, double-click on the UnInstall icon from the JavaWeb Server program folder.

4. Remove any leftover files since Add/Remove Programs won’t remove any files are created after installation.

C> cd path-to-installed-JavaWebServer

C> rmdir JavaWebServer2.0 /s /q

5.2.3 Microsoft Windows 95To remove Java Web Server from a Windows 95 machine:

1. Shut down the Java Web Server (seeSection5.1).

2. Remove the Java Web Server itself:

a. Click on the Control Panel.

b. Click on Add/Remove Programs.

c. Highlight the Java Web Server entry then click on Add/Remove.


Java Web Server Configuration

that

ter-

elp

hisnset

you

Web

or

le,re is

3. Remove any leftover files since Add/Remove Programs won’t remove any files are created after installation.

C> cd path-to-installed-JavaWebServer

C> rmdir JavaWebServer2.0 /s /q

5.3 Common Problems with Uninstalling

5.3.1 Microsoft Windows NT Registry Entries Are Not All DeletedMicrosoft Windows NT stores its configuration information in a database called theRegistry. Sometimes Registry entries will be left over after installation, and could infere if you reinstall (seeSection4.2.2). The Registry is not intended for user-levelaccess, it is a system administrator’s tool. See the Microsoft Windows NT online hfor more information.

6.0 Java Web Server Configuration

6.1 Using Environment Variables

Java Web Server 2.0 ships with JRE 1.1.7. By default, the Java Web Server uses tincluded JRE and ignores your CLASSPATH setting. It is recommended that you uyour JAVA_HOME environment variable to avoid conflict with JWS’s Java settingbefore using thehttpd startup script.

To use your existing JDK and environment rather than the JRE provided with JWS,should use thehttpd.nojre startup script. You can either ensure that yourJAVA_HOME environment variable is set to include your full JDK location (whichincludesjavac ), or explicitly pass your full JDK location when using thehttpd.nojre startup script by means of the-javahome option.


If you want to add classes that can be used by your servlets, place the classes inserver_root/classes . This classpath is automatically picked up by the server.

If you want to use your own environment, use the -cp option to add entries to JavaServer’s CLASSPATH.

Under Windows NT, environment variables (i.e., PATH, JAVA_HOME, and CLASS-PATH) set using quoted strings cause the httpd program to exit without warning. Fexample, usingJAVA_HOME=C:”\PROGRAM FILES\JAVA” causes trouble for the star-tup scripts found inserver_root/bin .

Under Windows NT, remove any trailing backslash in the PATH environment variabas there is a known bug in JWS 1.1.3 and 2.0 that prevents JWS from running if thea trailing backslash.


Java Web Server Configuration

d

.

ple,ed

erg

runforthe

cethat

ceps:

anu-

6.2 Starting the Java Web Server Automatically

6.2.1 SolarisTo have JWS started automatically whenever your machine boots, use the providejava-server.startup shell script. To configure, follow the instructions in the fileitself. Here is a brief summary of the necessary steps; perform these steps as root

# cp server_root/etc/java-server.startup /etc/rc3.d/S42jserv

# cd /etc/rc3.d

# chmod +x S42jserv

# ln S42jserv K42jserv

Edit the S42jserv script according to the directions containing in the file. For examyou must set the JSERV_HOME variable to be the location where you have installJWS.

Once you have configured yourS42jserv , you can verify that it works by typing“ ./S42jserv start ”. Then make sure your browser can connect to the web servusing the appropriate port, and make sure that “ps” shows that the processes are runninwith the correct user ID. If you notice a configuration mistake, type “./K42jservstop ”, fix the configuration, and retest.

On other versions of UNIX, you will need some special support that enables you tothe JWS as some user other than “root”. At this time, we provide this support only Solaris SPARC platforms. However, we do provide POSIX-compatible sources for native code needed to provide this functionality on other versions of UNIX.

6.2.2 Microsoft Windows NTIf you clicked yes when the InstallShield utility asked you if you wanted the NT Serviapplication installed, simply reboot your system. Rebooting sets up your system soeach subsequent reboot automatically starts the Java Web Server.

If you clicked no when the InstallShield utility asked you if you wanted the NT Serviapplication installed, you can still set up for automatic starting by following these ste

1. Make sure you have administrator privileges.

2. Run these commands:

C> cd server_root\bin

C> jservsvc JavaWebServer install

3. Reboot your system.

(If you wish to configure the server before rebooting, you can start the server mally as described inSection4.4.2. Once configured, shutdown the server thenreboot.)

6.2.3 Microsoft Windows 95Microsoft Windows 95 does not support the automatic startup of system services.


Using the Java Web Server

field

o if

thatWeb

ies

sing

iar

ool

d in

ing

l.

6.3 Changing the Default Ports

The Java Web Server port settings define the port that your services listen with forrequests. A port number can be any number between 1 and 65535.

Java Web Server default ports:

• Web Service (HTTP) – 8080

• Secure Web Service (HTTPS) – 7070

• Admin Tool (external) – 9090

• Admin Tool (internal) – 9091

• Session Service – 9094

Port 80 is the industry-wide port for running an HTTP web service on the Internet. SJava Web Server onmymachine uses port 80, then anyone connecting to it will onlyhave to specifyhttp://mymachine/ . (As opposed tohttp://mymachine: port-number for a service that uses any other port number.) The restriction on port 80 isin Solaris port numbers less than 1024 are considered “protected” ports, so the JavaServer has to be started as root if it uses port 80 (seeSection8.1.3 for details).

Note: The industry-wide port for running a secure web service (HTTPS) is port443, therefore the same restrictions apply as above. When using this port youmust start the service asroot as well.

You can change the default port in the Administration Tool by clicking on the Propertbutton and selecting External port. SeeSection7.1 for details. When you change theport number, you must save these changes and log in to the Administration Tool uthe new port number.

Note: The Java Web Server will automatically close the Administration Toolafter you save your port setting changes.

7.0 Using the Java Web Server

At this point you have started the Java Web Server on your machine and are familwith its features and functionality. Now it is time to get familiar with your own JavaWeb Server. It is recommended that you begin by logging into the Administration Tand change both the password and the port it uses.

7.1 Tutorial: Configure Your Admin Tool

If your Java Web Server is currently not up and running, start it manually as describeSection 4.4.

1. Connect to the Java Web Server’s Administration Tool through a browser by typthe Admin Tool’s URL:

http:// machine_host_name: admin tool port/

For example:http://schnauzer:9090 /

2. Log in using the default user name “admin” and the default password “admin”.

3. Select the Properties button to bring up the Properties Panel for the Admin Too



).

our

4. Select the Admin Password tab.

5. Enter and verify a new password for the “admin” user name.

6. Use the Apply button to save your changes.

7. Select the Internal Ports Tab.

8. Enter the internal port used by the Admin Tool for internal communication, e.g.,when managing servers (i.e., replace 9091).

9. Use the Apply button to save your changes.

10.Select the External Port Tab.

11.Enter the external port used to access the Administration Tool (ie, replace 9090

12.Use either the Apply button to save your changes or the OK button to both save ychanges and exit the Properties window.

Note: Changing the Admin Tool’s External Port property will cause the Admin Tool tobe restarted. Then you must edit your URL to use the correct new port for the AdminTool, and re-login as “admin”.

7.2 Java Web Server’s Administration Tool

Table 4 details the functions available through the Administration Tool.

TABLE 4. Administration Tool Functionality Breakdown: Quick Reference

Java WebServer

Setup Monitor Security Servlets

Web Service Network

Site

Service Tuning

File Aliases

Servlet Aliases

Virtual Hosts

MIME Types

Log Files

access agent combined error event referer

Log Output

Log Statistics

Resource Usage

Users

Groups

Access ControlLists

Resources

Add

Configure

cgi counter dateservlet error file imagemap invoker jsp92servlet jspservlet linkcheck ndservlet pagecompile phone pservlet session simpleformservlet simpleservlet snoop ssinclude template

templatefilter



f

tra-

dmin-ts, ifowser

7.2.1 Additional Controls

• Properties – Use to set admin password, external port, internal ports

• LogOut – Logs you out of the Administration Tool

• Help – Displays on-line help documentation

• Manage – Use to manage any of the available services

• Start – Starts the highlighted web service

• Stop – Stops the highlighted web service (only if the service is already running)

• ShutDown – Shuts down the entire Java Web Server

7.2.2 Links to Administration Tool DocumentationThe following web page is an index to pages with documentation for the features oAdministration Tool:

http:// your.server:8080/doc/en/docindex.html

You can also click on the Help button in the upper-right-hand corner of the Administion Tool for context-sensitive help.

7.3 Using the Java Web Server to Invoke a Servlet

Before you can use the Java Web Server to invoke a servlet, you have to use the Aistration Tool to load the servlet and configure its default parameters and argumenany. Once this has been done, you can use the servlet’s assigned name in your brto see the output of the servlet.

Note: Remember that servlets can be used with many types of servers, not just the JavaWeb Server.

Secure WebService

Network

Site

Service Tuning

File Aliases

Servlet Aliases

MIME Types

Log Files

access agent combined error event referer

Log Output

Log Statistics

Resource Usage

Users

Groups

Access ControlLists

Resources

Ciphers

Add

Configure

TABLE 4. Administration Tool Functionality Breakdown: Quick Reference

Java WebServer

Setup Monitor Security Servlets



t.

nelbut-

be

lude

der-

on-

ol,

t.

-o

7.3.1 Tutorial: Configure the Java Web Server to Use Your Servlet

1. Move your servlet (.class file) into theserver_root/servlets/ directory.(Remember,server_rootis your Java Web Server directory.) By putting your servlein theservlets directory you are making the servlet local and therefore trusted

2. Using the Administration Tool from your Java Web Server, go to the Servlets paunder managing Web Service (highlight Web Service and click on the Manage ton).

3. Select Add from the list of choices on the left.

4. To add a new servlet, fill in the following fields:

– Servlet Name: Enter the unique name of the servlet you are adding. This canany name that you choose.

– Servlet Class: Enter the name of the Java class for the servlet. You do not incthe.class extension.

5. Click on the Add button. This adds your servlet to the list of servlets located unneath Configure.

6. Select your servlet name under Configure to configure or modify the servlet’s cfiguration information as well as its properties.

7.3.2 Tutorial: Invoke Your Servlet Using the Java Web Server

1. Invoke your Servlet by entering the following URL in your browser:

http:// host:port/servlet /name_of_your_servlet

2. Again, you should see the text of your servlet.

Note: The wordservlet in this path is used to call the servlet. It is not the same thingas yourservlets directory.

7.4 Mapping Servlets to URLs Using the Java Web Server

Once you've added a servlet to your Java Web Server using the Administration Toyou can also alias that servlet to a unique URL. This is done in the Servlet Aliasesscreen, under the Setup panel.

7.4.1 Tutorial: Map Your Servlet to a Unique URLThis is how you would add your own Servlet Alias.

1. Using the Administration Tool, invoke Web Service management (highlight WebService and click on the Manage button).

2. In the management window, select Servlet Aliases in the Setup panel.

3. Click on the Add button.

4. In the “Alias” field, type the URL path name you want to use to invoke the servle

5. In the “Servlet Invoked” field, type the name of the servlet that will be run inresponse to the alias.

To specify arguments, type the name of the servlet followed by a “?” then the arguments. Server redirects can be performed by providing arguments in this fashion tRedirectServlet . For example, you could alias /oldlocation to /Redirect-Servlet?http://www.newcompanyname.com/newinformation .)


ut no

rvlet.uest

sidegsts areple asble

ntes

serv-oth

dwrit-

in

To specify a servlet chain, type the name of each servlet, separated by commas bspaces (eg:finger,snoop,date ). A servlet chain is two or more servlets linkedtogether so that each servlet in the chain is called in succession by the previous seAll of the servlets in a servlet chain can be aliased to one alias name. When a reqarrives for that alias, all the servlets in the chain will be invoked.

6. Click Save.For example, if you are adding a Servlet Alias with Alias set to “/hi ” and ServletInvoked set to “hello”, then users could invoke the hello servlet by typinghttp:// host:port/hi instead of http:// host:port/servlet/hello .

7.5 Server Side Includes (SSIs): Another Way to Invoke a Servlet Using theJava Web Server

Server-Side Includes (SSI) give you the ability to embed instructions to the server inan HTML document. These instructions are given using extensions to the HTML talanguage. A special file extension, .shtml , signals the server that the document containSSI directives. The server parses the document, executing SSI code in-line. Resulembedded in the document before it is served to the client. The SSI can be as simembedding boilerplate text (eg, copyright notices) or as powerful as calling executaprograms (eg, servlets).

NOTE: By default, only files with a “.shtml ” extension are searched for SSI tags.Refer to Setup -> Servlet Aliases which shows the Alias “*.shtml ” uses ServletInvoked “ssinclude”.

The NCSA SSI scripting language’s format for directives is a SGML/HTML comme(thus if served to the client unparsed, the directive’s coding won’t be visible). Directivhave this format:



The standard commands includeconfig , include , echo , fsize , flastmod , andexec .

Note: Most commands take only one tag at a time.

Note: There should be no spaces between the<!-- and the#.

JWS provides support for both standard and servlet-specific SSI commands. The let-specific SSI commands provide a convenient way to load and invoke servlets. Blocal and remote servlets can be used in this manner.

Restrictions: Because the HTTP header information is written before the embeddeservlet is executed, embedded servlets cannot perform any functions which requireing to the HTTP header. Therefore, these restrictions apply to servlets embedded .shtml pages:

• No cookies

• No redirects

• No errors or status (HttpServletResponse.sendError() or sendStatus() )

• No setHeader()


ed

ify

ed

• No setting of the content length

The syntax of a SSI tag for inclusion of servlets differs from the previously mentionNCSA syntax but is very similar to theapplet tag.

For example:

<servlet code=TestServlet codebase=http://blitz/initParam1=val1 initParam2=val2><param name=serviceParam1 value=val3><param name=serviceParam2 value=val4>...</servlet>

Thecode parameter is the name of the class file to be loaded. The optionalcodebaseparameter refers to a remote location for the servlet. Optional servlet initializationparameters can be specified. Finally, an optional list of name-value pairs can specrequest parameters (accessible using thegetParameter or getParameters methodson theServletRequest object).

Note: By omitting thename parameter, the servlet will be reloaded each time it isaccessed.

In this example:

1. The contents of the .shtml file up to the<servlet> tag is sent to the client unmod-ified.

2. ThenTestServlet will be loaded fromhttp://blitz and invoked with theappropriate init and request parameters. The output ofTestServlet is embeddedinto the response.

3. The contents of the.shtml file after the ending</servlet> tag is then appendedunmodified.

Note: Setup -> MIME Types shows that the extension “.shtml ” is Type/Subtypejava-internal/parsed-html .

7.5.1 Tutorial: Create a .shtml File Using an SSI Tag

1. Create a file containing the following HTML:

<HTML><HEAD><TITLE>Using SSI</TITLE></HEAD><BODY><H1>Amazing Server Side Include Text Follows:</H1><servlet code= Servlet_Name></servlet></BODY></HTML>

2. Save the file (use any name that you will remember) using the.shtml extension andplace this in yourserver_root/public_html directory.

3. In your browser, access and test this file by entering its URL,server_root/Name_of_File.shtml .

4. You should see the heading “Amazing Server Side Include Text Follows:” followby the output of your servlet.


Tuning and Troubleshooting

stal-

tyons.

ensure

are

8.0 Tuning and Troubleshooting

8.1 Installation and Configuration “Gotchas”

A detailed and comprehensive list of frequently asked questions (FAQ) covering inlation and configuration issues is available athttp://www.sun.com/software/jwebserver/faq/faq.html#100 . Some additionalthings to watch out for are included in this section. Refer also toSection4.5,"CommonProblems with Installation".

8.1.1 Running Servlet Compatibility ModeSome methods (that return a value in the Servlet 2.0 APIs) now return null or empenumerations in the Servlet 2.1 APIs. These changes were made for security reasThe methods that were changed are shown here:

These methods have been deprecated. Remove the references to these methods tocompatibility with other Servlet 2.1 engines.

Until you update the servlets, you can run them in a 2.0 compatibility mode. Theretwo compatibility flags: one for theServletContext methods and one for theHttpSessionContext methods.

To revert to the older behavior of theServletContext methods:

1. If Java Web Server is running, shutdown it down.

2. Edit theservlet.properties file.

Unix systems:server_root/properties/server/javawebserver/webpageservice/servlets.properties

Windows systems:server_root\properties\server\javawebserver\webpageservice\servlets.properties

3. Uncomment the compatibility mode flag and set it to true:servlets.2.0.compatibility=true

4. Start the server. Java Web Server now runs with the old behavior for thegetServ-let , getServlets andgetServletNames methods.

To revert to the older behavior of the HttpSessionContext methods:

1. If Java Web Server is running, shutdown the server.

2. Edit the session.properties file.

Unix systems:server_root/properties/server/javawebserver/sessionservice/session.properties

Windows systems:server_root\properties\server\javawebserver\sessionservice\session.properties

HttpSessionContext.getIds() Returns empty enumerationHttpSessionContext.getSession(String id) Returns nullServletContext.getServlet(String name) Returns nullServletContext.getServlets(); Returns empty enumerationServletContext.getServletNames(); Returns empty enumeration


http://www.sun.com/software/jwebserver/faq/faq.html#100


s

’s

r serv-

ss the

Dall-

ity of

3. Uncomment the compatibility mode flag and set it to true:servlets.2.0.compatibility=true

4. Start the server. Java Web Server now runs with the old behavior for thegetIds andgetSession methods.

8.1.2 Running Native CodeIf you have a package that includes native code, you must make the native librarieavailable to the Java Web Server. In JWS 2.0, you can put the native libraries inserver_root/native_lib . This directory is automatically added to Java Web ServerLD_LIBRARY_PATH (in Solaris) orPATH (in Windows) variable. Otherwise, you mustmodify theLD_LIBRARY_PATH or PATH variables to include the location of the nativelibraries.

Like Java applications, servlets can access native code. To use native code in youlets, follow the procedure outlined above.

Due to a JDK1.1.x class loader bug, native code and the classes that directly accecode must be loaded by the system class loader. Since servlets found in theserver_root/servlets andserver_root/servletbeans are loaded by the JWS customclass loader, these servlets cannot contain or directly access native code underJDK1.1.x. Rather, servlets in theCLASSPATH (with thehttp.nojre startup or inserver_root/classes ) are loaded by the system class loader and may contain ordirectly access native code under JDK1.1.x.

8.1.3 Running Java Web Server as Root in the Solaris Operating EnvironmentIn Solaris, there is a user and a group identification (UID, GID) assigned to files inserver_rootwhich affect who can start the server. During installation, the UID and GIare set to “nobody” if you are installing as root, and to the login ID of the person insting if you are not logged in as root.

Since the UID and GID forserver_root/ are assigned as “nobody” when you install asroot, you may wish to change the UID and GID to unique names because the secur“nobody” is weak, since it is in common use. If you do so, theserver.propertiesfile must be modified to reflect the new identifications.

Note: Theserver.user andserver.group sections of theserver.propertiesfile are ignored unless you start the server as root, which is why you do not need tomake this change to run as someone other than root.

After theserver.properties file is modified, when the server is run as root, thejserv process will be owned by root, but thejre process will be owned by the newidentification. Any subsequent servlet code will also be run under the new UID andGID.

To make the necessary changes, follow these steps:

1. Log in as root.

2. Open the fileserver.properties which can be found inserver_root/proper-ties/server/javawebserver/ .



ngew

oule

.

cto-inis-

,

3. Look for the following lines:

# POSIX ONLY:# If server.user is specified, the server will change UID after startup.server.user=nobody

# POSIX ONLY:# If server.group is specified, the server will change GID after startup.server.group=nobody

4. Changenobody to theuserid andgroupid you have decided upon.

5. Save and exit the file.

6. Change theuserid of server_root files:

# chown -R userid server_root

7. Change thegroupid of server_root files:

# chgrp -R groupid server_root

The jschangeowner convenience script can also be used by root to change the fileownership. For example:

# server_root/bin/jschangeowner -r server_root -o new_uid:new_gid

Using Port 80 as the Default Port

To use port 80 as the default port in Solaris, you must log in as root before you chathe port, and be logged in as root whenever you start the server in the future. Follothese steps to make the change:

1. Log in as root on your machine.

2. Optional: Change the User and Group IDs to something other than “nobody”. Yprobably want to do this for security reasons, since it would be better to have fiownership by someone other than “nobody.”

3. Start the Java Web Server.

4. Use the Administration Tool to change the port number to 80 and restart.

In the future, to start the Java Web Server you will need to be logged in as root

8.1.4 Running Java Web Server as Someone Other than Root in the Solaris OperatingEnvironmentTo run the server as someone other than root, the UID and GID for the files and direries inserver_rootneed to be that of the person starting the server. The system admtrator or a person with root access can use thechown andchgrp commands to changethe UID and GID if necessary. (If the person who will be running the server alsoinstalled the files then the UID and GID should already be set properly.)

Note: Even though execute permission on the installed files is set for group and othersno one but the user can start the server.

The jschangeowner convenience script can also be used by root to change the fileownership. For example:

# server_root/bin/jschangeowner -r server_root -o new_uid:new_gid



ed.

tion the

duenot

for

und

8.2 Known Bugs and Their Workarounds

8.2.1 Using the Java 2 SDK (formerly code-named “JDK 1.2”)

8.2.1.1 SolarisThe production version of the Java 2 SDK with the Java Web Server is recommend

For the production version of the Java 2 SDK, use at leastSolaris_JDK_1.2.1_03_pre-release or Solaris_JDK_1.2.1_03 available athttp://www.sun.com/solaris/java /. If you use an earlier production release,you may experience problems running Secure Sockets Layer (SSL) with the JWS.

For the reference implementation, use any Java 2 SDK 1.2.x release available athttp://java.sun.com/products/jdk/1.2/ .

8.2.1.2 Windows

1. When running JWS with Java 2 earlier than JDK 1.2.2, you might get an excepand have the Java Web Server fail to start after creating a server certificate withauthstore utility. The exception will look similar to this:

Exception in thread “main” java.lang.NoClassDefFoundError: com/sun/server/util/ ErrorMessagesat com.sun.server.util.ErrorMessages.class$ (ErrorMessages.java:31)at com.sun.server.util.ErrorMessages.<clinit> (ErrorMessages.java:33)at com.sun.server.ServerProcess.<clinit>(ServerProcess.java:51)at java.lang.Class.forName0(Native Method)at java.lang.Class.forName(Compiled Code)at sun.security.Login.getClass(Login.java:78)at sun.security.Login.main(Compiled Code)

To avoid this problem, disable the JIT (Just-In-Time compiler).

Note: disabling the JIT has a negative impact on performance.

To disable the JIT, start the server using thejserv startup script and specify “-vmargs -Djava.compiler=NONE ”. For example:

jserv -javahome d:\jdk1.2 -vmargs -Djava.compiler=NONE

2. When running JWS with Java 2, resource locations relative to the partition root(\)(the drive containing the JWS) are not resolved properly (Bug 4256359). This isto a JDK1.2.2 problem resolving relative root directories when the drive letter isspecified.

Therefore you must specify the drive letter when setting protection or file aliasesresources not contained in theserver_root. For example, you might modify theSetup -> File Aliases default for/~user from \home\$user\public_html tobec:\home\$user\public_html .

8.2.2 Environment Variables with Quoted Strings Won’t WorkUnder Windows NT, environment variables set using quoted strings will cause thehttpd program to exit without warning. The affected variables arePATH, JAVA_HOME,andCLASSPATH. For example, this setting causes troubles for the startup scripts foin server_root/bin (whereserver_root is the directory where JWS is installed):


http://java.sun.com/products/jdk/1.2/



char-

ib-

ty for

gis-

le,re is

r

aded.

erv-nor-

JAVA_HOME=C:”\PROGRAM FILES\JAVA” <--- do NOT use quoted strings

8.2.3 Limitations on JavaServer Pages 1.0 SupportRegarding JWS 2.0’s implementation of the JavaServer Pages 1.0 spec:

• TheTaglib directive (tag) is not implemented.

• Java is the only supported scripting language.

• Included files: <%@ include file=”pathToFile” % > directive:If the included file subsequently changes, the page is not recompiled.

• Buffering: The current JSP engine treats buffer size incorrectly, it uses units of acters instead of bytes.

• Forward: The servlet engine crashes with aStackOverflowException if there isan infinite recursion inRequestDispatcher.forward/include or <jsp:forward/include .../ >.

8.2.4 Incorrect Version of JRE Redistribution InformationOn Solaris, the file containing configuration information for people wishing to redistrute the JRE reflects the wrong JRE release. The file is forJRE 1.1.6_03 while theJava Web Server actually shipsJRE 1.1.7_05 . The configuration instructions are vir-tually the same between the two releases, however, and should cause little difficulthose in need of such information. The file in question isjre_config.txt . It can befound inserver_root/jre (whereserver_root is the directory where JWS is installed).Anyone requiring the JRE 1.1.7 version of the file can go through this website for retration and download:http://www.sun.com/solaris/jre/download.1.1.7/ .

8.2.5 Trailing Backslash in the PATH Environment VariableUnder Windows NT, remove any trailing backslash in the PATH environment variabas there is a known bug in JWS 1.1.3 and 2.0 that prevents JWS from running if thea trailing backslash.

8.3 Common User/System Administrator Errors

• A system’sCLASSPATH is ignored. When a user adds things like JDBC libraries othird-party classes to theCLASSPATH, the Java Web Server won’t find the classes.

• Both thejserv script in Solaris and thejserv.c file in Microsoft Windows can bereviewed and edited.However, if the user changes it, Sun no longer supports it.

• Problems with reloading classes: Classes in theservlets andservletbeansdirectories are reloaded when modified, classes in other directories are not relo

8.3.1 Locking Yourself Out of the Java Web ServerIt is not recommended that you assign access controls to any of the core internal slets. Assigning access controls to any of these servlets can prevent you from havingmal access to your Java Web Server. These include theadmin , error , file , invoker ,linkcheck , loganalyzer , snoop , cgi , andssinclude servlets.


http://www.sun.com/solaris/jre/download.1.1.7/


nt oftions

ess

cess

in

ilure try to

If you do find yourself locked out of the Java Web Server because of the assignmeaccess controls to any of the core internal servlets, you can recover from this situaby editing theacl.properties file for the service in which you assigned the accescontrols. To edit theacl.properties file:

1. Change to the directoryserver_root/properties/server/javawebserver/service_name/

2. Open the fileacl.properties in a text editor.

3. Look for the line containing the name of the servlet and its realm.

Comment this line out or delete it from the file. For example, if you have set acccontrols on the admin servlet in the realmdefaultRealm using the Access ControldefaultACL , the line would look like this:Servlet.admin=Basic:default-Realm:defaultAcl

4. Stop the Java Web Server processes.

5. Close your browser then re-open it.

6. Restart your Java Web Server.

You should now be able to log in normally to the Java Web Server.

8.3.2 Administration Password ForgottenIf you change your Administration password and then forget it and can no longer acthe Administration Tool, you can recover as follows:

1. Stop your Java Web Server.

2. Edit the fileserver_root/realms/data/adminRealm/keyfile

3. Change the file’s admin line so that it reads:

admin::YWRtaW4=

4. Save the revised keyfile file.

5. Restart your Java Web Server.

You should now be able to access the Administration Tool using “admin” as the logand “admin” as the password.

8.3.3 Running Multiple ServersWhen running multiple servers on one machine, you may get an error regarding faof the additional Session Service startup, since each server’s Session Service willuse port 9094. To avoid this error, manually edit thesessionservice/end-point.properties file to changeendpoint.main.port=9094 for the additionalSession Service.

8.4 Troubleshooting Utilities

8.4.1 netstat

On Solaris, to see if a port is bound, typenetstat -a in a terminal window. This willgive you a list of all sockets currently active. The-a option means it will include thosethat are just listening.



roto-

e

r ortra-

, but

histheirS,nd

youline

ries for

tionscrip-

d. log

t log

eader

8.4.2 ping

Typeping localhost in a terminal window. If that doesn’t work, there are networkproblems that need to be solved before you try to run the server.

8.4.3 telnet

To rule out your browser as the cause of problems, manually simulate the HTTP pcol:

1. Type telnet localhost port

2. Type GET / HTTP/1.0 and press Enter twice.

3. This will give you the raw HTML of the top web page. If this works, you know thproblem points toward the browser, not the server.

8.4.4 Alternate BrowsersTrying a different browser is another way to establish if the problem is with the servewith the browser. For example, if Netscape Navigator won’t work to run the Administion Tool, try HotJava Browser.

8.4.5 BugsGo tohttp://developer.java.sun.com/developer/bugParade and do asearch on Java Web Server to view bug information. Registration on this site is freeis required to use BugParade.

8.4.6 Log FilesWhen managing a service with the Admin Tool, you can use Setup -> Log Files. Tenables you to select which types of log files you would like to keep and to define settings. Log files are used to store information about the general operation of JWincluding its servicing of client requests. These files can be useful for monitoring aanalysis purposes. By default, these six log types are defined for JWS:

The Monitor -> Log Output panel enables you to view the entries made in the logshave selected. For more information on viewing log entries, see the Log Output ondocument (administration/log_contents_gui.html ).

The Monitor -> Log Statistics panel enables you to sort and display the log file entas various charts or tables. For more information on the presentation of log entriesanalysis, see the Log Statistics online document (administration/log_stats_gui.html ).

Access Log Contains a log of all incoming requests and lets you track and get informaabout clients of the server, such as date, remote user, remote host, and detion string. Uses common log format.

Agent Log Lists the user-agent headers used to determine the browser type making arequest.

Combined Log Same as the Access Log, but with Agent and Referer information appendeError Log Lists internal server errors and is useful for troubleshooting. Uses arbitrary

format.Event Log Lists server tracing events (for example, a startup or shutdown) and servle

information (by default). Uses arbitrary log format.Referer Log Lists the referer header, and the name of the file it requests. The referer h

document holds the link that points to the requested document page.


http://developer.java.sun.com/developer/bugParade


g its

with

gk.

will

ing thehread

htcond

Each log has its own log file name, and each service has its own directory for storinlogs. The service log directories are:

• Web Service -server_root/logs/javawebserver/webpageservice/

• Secure Web Service -server_root/logs/javawebserver/secureservice/

Set the buffer size to “0” so that messages are written immediately to the files.

8.4.7 Thread DumpOn Solaris, you can get a thread dump of the server process as follows:

1. Look at the processes associated with the server. If you started the web serverjserv , you will find three processes;jserv and two Java processes.

jserv is the parent of the first Java process (theadminserver process), which inturn is the parent of the second Java process (thejavawebserver process).

2. Send aSIGQUIT to the second Java process (thejavawebserver process):

kill -QUIT pid_of_second_process

The following is a sample thread dump:

javawebserver: SIGQUIT 3* quitjavawebserver: si_signo [3]: SIGQUIT 3* quitjavawebserver: si_errno [0]: Error 0javawebserver: si_code [0]: SI_USER [pid: 6923, uid: 1002]javawebserver: stackbase=EB362000, stackpointer=EB35DF70javawebserver:javawebserver: Full thread dump:[... more information follows ...]

If the data looks similar but doesn’t start with “javawebserver :”, then you did athread dump on theadmin process. If you didn’t get a thread dump, try commentinout code or use a load testing tool to run specific servlets to see if they deadloc

There are several situations where theSIGQUIT may be blocked:

• The Java Web Server was started withnohup .

• The Java Web Server was started from the/etc/rc3.d/ script (which back-grounds the process and blocks the signal).

• The Java Web Server was started with the-bgnd flag.

• The Java Web Server was started and backgrounded in a Bourne Shell.

In these cases, you can get a thread dump by sending a SIGABRT signal (whichkill the process):

kill -ABRT pid_of_second_process

3. Look at the Register Monitor Dump at the end of the thread dump. If you are runnwith green threads, you may have a case where all threads are waiting to enterHeap Lock. This means that a call in one of the threads is hung, and no other tcan get time on the heap. (This is what you will see with thegetRemoteHost()bug as mentioned in Section 8.4.9.)

You may be able to improve this deadlock by moving to native threads. You migalso have a “classic” deadlock: one thread has a lock and is waiting to enter a selock; another thread has the second lock and is waiting to enter the first lock.



.)

m-

canandyournnec-

reyte

ts will

ut

trolrun

rror thatclient

kingThis

ation

4. Once you find the thread(s) that is causing the problem, look at the informationabove the Register Monitor Dump. From this information, you should be able totrack down the problem (or at least know where and why the deadlock occurred

8.4.8 Stack Trace Line NumbersIn order to have line numbers displayed on a stack trace (instead of the words “Copiled Code”), you can disable the JIT (Just-In-Time compiler) by using-Djava.com-piler=NONE . For example:

bin/authstore -Djava.compiler=NONEjserv -vmargs -Djava.compiler=NONE

Note: disabling the JIT has a negative impact on performance.

8.4.9 What to Try When JWS is Not RespondingThe Java Web Server may not be responding because it may be busy. The systemback up if the servlets are slow (for example, if a servlet takes 10 seconds to run, you have 1000 requests and only 100 handler threads). To check for problems, runservlets outside the server. Check if all instances of a servlet are using the same cotion to a database (instead of using a connection pool). Also check if all servlets areading or writing data from a socket or file that is not buffered. The default is a 1-bread, which is slow for large chunks of data.

If the system does not recover when the load decreases, it may be hung. These hinhelp you debug a system that is hung:

• If you are not running a JDK with native threads, check if you are usingHttpRe-quest.getRemoteHost() . There is a known bug injava.net.InetAd-dress.getHostName() that hangs the system when this method is called. If yoare usinggetRemoteHost() , comment it out to see if the problem goes away. If idoes, consider running JDK 1.1.7 and native threads.

• If you are running with green threads, check if the problem still occurs with JDK1.1.7 running native threads.

• If you are running on Solaris, get a thread dump of the server process.

8.4.10 Debugging Security Manager Problems with Java 2Java 2 has a different security infrastructure that allows for a finer granularity of conover resources. Most problems which require additional permissions for a servlet tocorrectly can be debugged simply by looking at theSecurityException or Access-Exception thrown when the problem occurred. When aSecurityException isreceived, a stack trace showing where the exception occurred will be output to the elogs (either the main error log for the server or the error log for the specific servicereceived the exception). In specific cases, a 500 error may also be displayed to theaccessing the server.

The type of exception that was received and the current line of code which was worwhen the problem occurred should indicate the permission needed by the servlet. permission should then be added to thejserv.policy file.

Please read the Java 2 security documentation (see Section 9.1.3) for more informon the policy file.



herrmis- the

et

e

kedssed

d) and

Unfortunately, because a Java class may extend classes which are loaded from otlocations (and all sub and super classes must have the privileges in order for a pesion to be granted), it can be difficult to track down the correct code base requiringpermission.

For example, the Snoop Servlet (sunexamples.SnoopServlet located in the serv-lets directory) extendsjavax.servlet.http.HttpServlet . Thejavax classes aredefined in theservlet.jar file located in thelib/ directory.

In this case, theSnoopServlet has a code Base offile:${server.root}/serv-lets/- and its super classHttpServlet has a code Base offile:${server.root}/lib/- . In order forSnoopServlet to read a file, both codebases (lib andservlet ) must have the correct read privilege.

If you are unable to find the correct place to grant a privilege, you may be able to gadditional debug information with thejava.security.debug property. By settingthe property toaccess,failure , you can determine the exact code Base where thaccess is failing. This property will generate output onstderr .

Note: This is an unsupported/undocumented flag and may NOT be available in all ver-sions of JDK1.2.

To use the property, start the server usingjserv with this argument:

jserv -vmargs -Djava.security.debug=access,failure

This setting will cause the JDK to print out each time a security permission is checand also indicate why any permission failed. Each time the security manager is acceyou will see a line like:

javawebserver: access: access allowed (java.lang.RuntimePermission accessClassInPackage.sun.beans.infos)

When a security check fails, the debug output will show you where the access faile(because there is a hierarchy of classes, this may not be where you expect it to bethe permissions of that code base. You can then add the required policy to thejserv.policy file usingpolicytool .

Here is an example of a failure:

javawebserver: access: access denied (java.lang.RuntimePermission exitVM ) <--permission failingjavawebserver: access: domain that failed ProtectionDomain(file:/export/servers/JavaWebServer2.0/servlets/ <no certificates>) <--URL of codebasejavawebserver: com.sun.server.security.JWSPermissions@185215f (javawebserver: (java.lang.RuntimePermission readFileDescriptor )javawebserver: (java.lang.RuntimePermission modifyThreadGroup )javawebserver: (java.lang.RuntimePermission stopThread )javawebserver: (java.lang.RuntimePermission loadLibrary.* )javawebserver: (java.lang.RuntimePermission queuePrintJob )javawebserver: (java.lang.RuntimePermission accessClassInPackage.sun.net.www )javawebserver: (java.lang.RuntimePermission modifyThread )javawebserver: (java.lang.RuntimePermission writeFileDescriptor )javawebserver: (java.net.SocketPermission * connect,listen,accept,resolve)javawebserver: (java.io.FilePermission <<ALL FILES>> read,write,execute,delete)javawebserver: (com.sun.server.security.RestrictPermission exitVM )javawebserver: (java.util.PropertyPermission java.specification.name read)javawebserver: (java.util.PropertyPermission java.version read)javawebserver: (java.util.PropertyPermission java.specification.version read)javawebserver: (java.util.PropertyPermission java.vm.vendor read)javawebserver: (java.util.PropertyPermission java.vm.specification.version read)


Reference Information

is

a

it the

some

javawebserver: (java.util.PropertyPermission os.arch read)javawebserver: (java.util.PropertyPermission java.vendor.url read)javawebserver: (java.util.PropertyPermission line.separator read)javawebserver: (java.util.PropertyPermission os.name read)javawebserver: (java.util.PropertyPermission java.vendor read)javawebserver: (java.util.PropertyPermission * read,write)javawebserver: (java.util.PropertyPermission java.vm.specification.vendor read)javawebserver: )

8.4.11 JWS Version InfoAt the Admin tool login screen, click the About button for JWS info:

About Java Web ServerJava Web Server 2.0(w)August 1999Copyright 1995-1999 Sun Microsystems, Inc.

8.4.12 Verbose FlagUse the-verbose flag to get more information as to the options and variables JWSrun with.

8.4.13 Snoop ServletUsehttp:// yourserver:8080/snoop.html which provides an easy way to see Javruntime version, where it came from, and theCLASSPATH for a running server.

9.0 Reference Information

9.1 Technical Documentation

To see the latest documentation updates, and benefit from answers in the FAQ, visJava Web Server Web site (http://www.sun.com/software/jwebserver/ ) on aregular basis.

9.1.1 Primary DocumentationThe Java Web Server 2.0 product is packaged with online documentation; here arehighlights from the documentation contents:

• Important Information

• Release Notes

• Features

• Copyright and Trademarks

• FAQ

• Installation

• README.installNT

• README.installSol

• Installing on Unsupported Platforms

• Configuration

• Changing Ports

• Moving the Document Root


http://www.sun.com/software/jwebserver/


• Installing Beans

• Simplifying Webpage Updates

• Tuning Server Performance

• Creating Custom Logs

• Setting up Multiple CGI Directories

• Adding Services

• Configuring Virtual Hosts

• Table of Standard Port Settings

• Server Administration

• Accessing the Administration Tool

• Starting, Stopping, Removing JWS

• Changes Requiring Server Restart

• Security Administration

• Setting up ACLs

• Creating and Managing Server Certificates

• Managing Security for Groups and Users

• Requiring Client Authentication

• Creating Customer Realms

• Security your JWS

• Secure Sockets Layer (SSL)

• Servlet Sandbox

• JWS Security Features

• Overview: Understanding Security under Java 2

• Java 2: Controlling the Accessibility of Packages

• Java 2: JWS’s Default Policy File

• Server-Side Programming

• Servlets

• JSP

• Traditional Server-side Code

• (Deprecated) Page Compilation

• Samples (found inserver_root/examples/ )

• Website Content and Design

• Presentation Templates (control file appearance and content)

• JavaServer Pages

• Server-side Imagemap

• Server-side Includes

• Server-Side Programming

• Simple Servlets

• Servlet Beans

• Applet-servlet Communication

• Database Application (JDBC access servlet)

• Security



• Applications

• Remote Method Invocation (RMI)

• Miscellaneous Servlets

• Administration Tool Help

• Initial Screens (Login, Manage, Properties)

• Setup

• Monitor

• Security

• Servlets

• API documentation

• Servlet API changes from version 2.0 to 2.1

• JWS API class and member descriptions (javadoc)

• Glossary

• Index



ing

9.1.2 Release NotesThe Release Notes contains information on these topics:

• Quick List

• Known Issues

• Documentation Changes

• Code Changes

• Bug Fixes

• Troubleshooting

• Page-compilation

• Troubleshooting Servlets

• The CLASSPATH Environment Variable and the Java Web Server

• Removing Java Web Server on the Windows Platform

• Permissions on Logs

• Changing Your Admin Password and Default Port

• If You Have Lost Your Password

• If You Are Locked Out of the Java Web Server

• Maintaining Security When Changing the Document Root

• File Descriptors

• Changes Requiring Server Restart

• Additional Sources of Information

9.1.3 Additional DocumentationFor more information on Java Web Server, seehttp://www.sun.com/software/jwebserver/

For more information on Java Security and Security Manager issues, see the followlocations:

The Java Tutorial’s section on Java 2 security at:http://java.sun.com/docs/books/tutorial/security1.2/index.html

The Java 2 Security documentation (includes tools, API, and general info)http://java.sun.com/products/jdk/1.2/docs/guide/security/index.html

The Java 2 Security Toolshttp://java.sun.com/products/jdk/1.2/docs/tooldocs/tools.html#security

The Java Security whitepaper (PostScript file)http://java.sun.com/security/whitepaper.ps

The Security API pagehttp://java.sun.com/security/index.html


http://java.sun.com/software/jwebserver/

http://java.sun.com/software/jwebserver/

http://java.sun.com/docs/books/tutorial/security1.2/index.html

http://java.sun.com/products/jdk/1.2/docs/guide/security/index.html

http://java.sun.com/products/jdk/1.2/docs/guide/security/index.html

http://java.sun.com/products/jdk/1.2/docs/tooldocs/tools.html#security

http://java.sun.com/products/jdk/1.2/docs/tooldocs/tools.html#security

http://java.sun.com/security/whitepaper.ps

http://java.sun.com/security/index.html


sers.

va

.

on

The Servlet API pagehttp://java.sun.com/products/servlets

The JSP pagehttp://java.sun.com/products/jsp

For NCSA’s Server-Side Includes on-line tutorial, seehttp://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html .

9.2 Additional Reference

9.2.1 Email AliasesThe following alias is available to users:

[email protected]

Problem-solving advice and discussion of Java Web Server-related issues by JWS uInstructions for subscribing can be found athttp://www.sun.com/soft-ware/jwebserver/faq/index.html .

[email protected]

9.2.2 ListServsThe following listservs may come in handy when trying to get help regarding the JaWeb Server and its many features:

• comp.lang.java.help

• comp.lang.java.security

9.2.3 FAQ Reference Sectionhttp://www.sun.com/software/jwebserver/faq/faq.html

You’ll find lots of helpful information in this Frequently Asked Questions documentThe Java Web Server FAQ is divided into these categories:

• Installation/Configuration

• 1.1.1 Upgrade

• 1.1.2 Upgrade

• Java 2

• Server

• Servlets

• Security

• Reference

In particular, the FAQ Reference section includes pointers to find more informationsubjects such as:

• public sites and ISPs using JWS

• HTTP and other W3 protocols


http://java.sun.com/security/index.html

http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html

http://www.sun.com/software/jwebserver/faq/index.html

http://www.sun.com/software/jwebserver/faq/index.html

http://www.sun.com/software/jwebserver/faq/faq.html

http://java.sun.com/products/servlets

http://java.sun.com/products/JSP

Product Support

digitn

ack,call

t

• NCSA’s Common Gateway Interface (CGI)

9.2.4 BooksCORE: Java Web ServerChristopher Taylor/Tim Kimmet1998, paperbound, 608 pages, includes CD-ROMPrentice HallISBN 0-13-080559-9

Illustrated Guide to HTTPPaul S. Hethmon1997, softbound, 400 pages, includes CD-ROMManning PublicationsDistributed by Prentice HallISBN 0-13-858226-2

How to Set Up and Maintain a Web Site, 2/eLincoln Stein1997, paperbound, 816 pages, includes CD-ROMAddison-WesleyISBN 0-201-63462-7

10.0 Product Support

10.1 Warranty/Installation Support

Enterprise Services (formerly Sun Service) must ask customers to provide the 18-alpha-numeric serial number in order to receive the 90-day free warranty/installatiosupport. The serial number is included on the Support/Registration card, the Digipand/or the purchase invoice. The 90-day period begins on the date of the first phonelogged by Enterprise Services.

The following URL is for serial number validation:

http://javashop.sun.com/ECom/docs/SerialNumber.html

Note: Although some Java Software products ask for a serial number when the producis first launched, it is just a “storage location” for the serial number for the user’s futurereference—it will not affect the use of the product in any way.



Product Support

ing the

m is

10.2 Using the Serial Number Validation URL

1. Open your browser and enter the following URL:http://javashop.sun.com/ECom/docs/SerialNumber.html . This screenwill appear:

2. In the Serial Number field, type the whole serial number, without spaces, includany leading alpha characters (for example, JS2802373191710218) and click onSubmit button. Letters can be typed upper- or lower-case—the validation progranot case-sensitive.




Product Support

If the serial number is valid, this screen will appear:

If the serial number is not valid, this screen will appear:


us-xam-ed byI

to ae,le

n ofsep-

eforet ser-

Appendix A: Java Web Server,Migrating 1.1.3 to 2.0

Java Web Server (JWS) 2.0 installs “out of the box” with a default configuration. Ctomizations refer to any changes you have made to that default configuration. For eple, you may have changed the port through which clients access documents servthe web server. Or you may have installed and configured your own servlets or CGscripts.

This provides guidance on migrating your existing JWS 1.1.3 customizations over new JWS 2.0 installation. Because the opportunities for customization are extensivthis document can not address every possibility. However, it should prove a valuabguide and reminder of what to consider when migrating customizations.

Note: If your customizations were minor or few, you may prefer to simply install JWS2.0 and repeat your customizations on the new installation, rather than attempting tomigrate them from the old verions. The choice is yours.

1.0 Requirements

These instructions assume two JWS installations: an existing, customized installatioJWS 1.1.3 and a new, default installation of JWS 2.0. These installations must be inarate directories.

If your existing JWS 1.1.3 uses the default port settings, reset those port numbers binstalling JWS 2.0 (see Table 1, “Resetting Port Numbers,” on page 2. If you do noreset them, you will experience port conflicts when the JWS 2.0 attempts to installvices on the existing, active ports.

SUN MICROSYSTEMS, INC. A-1

Approach

S(notrty

per-tep

stal-

ou

TABLE 1. Resetting Port Numbers

To install the new JWS 2.0, follow the 2.0 installation instructions.

2.0 Approach

The general approach to migration is to identify and copy files from the existing JW1.1.3 installation to the new installation. Once files have been identified and copiedmoved), the Administration Tool for the two installations is run in parallel and propesettings (customizations) verified on a screen-by-screen basis.

3.0 Migrating Customizations

These steps guide you through the stops of migration in the order they need to beformed. If you have made no customizations in a particular area, simply skip that sand move on to the next.

3.1 Executables

3.1.1 Servlets and Servlet BeansCopy all your servlet and servlet bean files from your JWS 1.1.3 to your JWS 2.0 inlation.

For example, you might have servlets under development located in theservlets orservletbeans directory of the web server:

Solaris

% cp /opt/JavaWebServer1.1.3/servlets/myServlet.class /opt/JavaWebServer2.0/servlets/

Windows

C> cp C:\JavaWebServer1.1.3/servlets/myServlet.class C:\JavaWebServer2.0/servlets/myServlet.class

Or, you might have servlets ready for deployment located in some other directory ycreated in the web server:

JWS 1.1.3 Service Default Temporary Administration Toolonline doc:

Web Service 8080 8085 Network Setup

Secure Service 7070 7075 Network Setup

AdminTool(external)

9090 9095 Properties

AdminTool(internal)

9091 9096 Properties


Migrating Customizations

f

the

-

r

->

Solaris

% mkdir /opt/JavaWebServer2.0/classes% cp /opt/JavaWebServer1.1.3/classes/myServlet.class /opt/JavaWebServer2.0/servlets/

Windows

D:\>mkdir C:\JavaWebServer2.0/classes

D:\>cp C:\JavaWebServer1.1.3/classes/myServlet.class

C:\JavaWebServer2.0/servlets/myServlet.class

Changed in 2.0. In JWS 1.1.3, servlet examples classes resided inserver_root/serv-lets/ . In JWS 2.0, servlet examples classes now reside inserver_root/serv-lets/sunexamples/ .

3.1.2 CGI Scripts

1. If you did not use the default CGI script directory,cgi-bin , create your customCGI script directory in the new installation.

2. Copy all your CGI script files from the old installation to the new. For example, iyou used the default CGI script directory,cgi-bin :

% cp /opt/JavaWebServer1.1.3/cgi-bin/myScript /opt/JavaWebServer2.0/cgi-bin/myScript

3. If you used a custom-named CGI script directory, update the CGI servlet alias inAdministration Tool to reflect that directory name.

Note: Although the default CGI script directory is the same for both the webpage andsecure services, it is possible to designate a different CGI directory for each. If you havedone so, you must repeat the CGI script migration instructions for each service..

3.1.3 Startup ScriptsIf you were starting the old JWS automatically, you will need to remove it from automatic startup and add the new JWS instead.

Solaris

1. Stop your java-server startup script for JWS1.1.3. For example:

/etc/rc3.d/K42jserv stop

2. If you modified yourjava-server startup script file(s) for JWS 1.1.3, you need tomake similar modifications to yourjava-server startup script file(s) for JWS 2.0.

Repeat the instructions in thejava-server.startup file, including moving,renaming, and linking the file. Edit the file in the new installation to reflect similacustomizations to those you made to the same file in the old installation.

3. Test the new script file(s) by typing:

/etc/rc3.d/S42jserv start

Windows NT

1. Stop your JWS NT service. For example, click the Stop button in Control PanelServices.



ce

er-

n

hisng

iscon-

ure,

he

2. If you created and usedjservargs.txt file in old_server_root\bin , copy thejservargs.txt file tonew_server_root\bin .

3. If you have VM arguments in yourjservargs.txt file, consider moving them tovmargs.txt file. In addition tojservargs.txt file, you could addvmargs.txtfile to each VM,adminserver or javawebserver VM, in JWS 2.0. For moreinfo onvmargs.txt , please see the Release Notes document.

4. Remove your JWS NT service. For example, if you used default JWS NT serviname, JavaWebServer:

D:\> C:\JavaWebServer1.1.3•in\jservsvc JavaWebServer remove

5. Add your new JWS NT service. For example, if you want to use default JWS NTservice name, JavaWebServer:

D:\> C:\JavaWebServer2.0•in\jservsvc JWS install

6. You should be able to start it by clicking the Start button in the Control Panel -> Svices.

3.2 Log Information

Due to changes in the log files and formats for JWS 2.0, migration of log informatiofrom 1.1.3 to 2.0 is not recommended.

You may wish to simply keep your old logs in the same location as your new logs. Tmay be accomplished by renaming the old log files to avoid conflict and then movithem to the new location.

We recommend you use a name that indicates the product version and/or date of dtinuation of the log file. For example, you may want to renameaccess_log tojws113_access_03jun99 .

3.3 Security

Follow these instructions only if SSL was setup on the old version. If you are not slook for a keys file inold_server_root/ of the old installation. If the file exists, it meansSSL was set up and you should follow the migration instructions in this section. If tfile does not exist, skip this section.

3.3.1 CertificatesCopykeys , CAstore , andkeys.passphrase files from theold_server_root direc-tory to thenew_server_rootdirectory.

In JWS 1.1.3, theCAstore file might be in the machine’s root directory (/ or C: ). ForSolaris, it might be in the user’s home directory such as/home/ $user. A CAstore fileshould be there only if you imported root certificates and akeys.passphrase fileshould be there only if you created this file to contain password or passphrase.

Note: Bug ID 4198423 is fixed in JWS 2.0.CAstore should only be inserver_root ifyou imported root certificates. If you do copy over yourCAstore file from JWS 1.1.3,it must be placed in the 2.0server_root. keys.passphrase file (if it exists) should bein server_root.



rs.

ing

nTool.

3.3.2 Realms

1. Back up your current realm files in the old installation. For example:

Solaris

% mv /opt/JavaWebServer2.0/realms /opt/JavaWebServer2.0/realms_bak

Windows

D:\> ren c:\JavaWebServer2.0\realms c:\JavaWebServer2.0\realms_bak

2. Copy the realm files recursively fromold_server_root/realms tonew_server_root/realms . For example:

Solaris

% mkdir /opt/JavaWebServer2.0/realms

% cp -R /opt/JavaWebServer1.1.3/realms/* /opt/JavaWebServer2.0/realms

Windows

D:\> ren c:\JavaWebServer2.0\realms c:\JavaWebServer2.0\realms_bak

D:\> mkdir c:\JavaWebServer2.0\realms

D:\> xcopy c:\JavaWebServer1.1.3\realms c:\JavaWebServer2.0\realms /E

3.4 Environment Settings

If you have modified any environment variables for use with JWS 1.1.3, remove orrevise those values to reflect the new JWS 2.0 installation.

Typical examples of this include:

• If you have added servlet classes to yourCLASSPATH.

• If you have been using yourJAVA_HOME to indicate a JDK other than that bundledwith JWS.

• If you have been using native code:

Solaris: SOs pointed to by yourLD_LIBRARY_PATH

Windows: DLLs pointed to by your PATH

3.5 Properties

3.5.1 Available Through the Administration Tool

1. Start both the new and old JWS. Make sure they are using differentport numbe

2. Login to both new and old JavaWebServer Admin Tools.

If you performed the steps in the migration Security section (3.3), the file containyour old administration password was copied over to the new installation. Thatmeans your password on the new installation is the same as on the old.

If you did not perform the steps in the Security section of this document, you cachange the default password to one of your choosing using the Administration

3. For each service of JWS, follow these two steps:



ly the

o be

aultew

JWS

ocu-re

1. Select same service in both Admin GUI and click Manage button.

2. All the settings must be compare from both Admin GUI and modify new JWSsetting based on old JWS setting.

For security setting, don’t forget to check all the realms.

Change all the port numbers after all the upgrade steps are done.

Removed in 2.0.The simple Proxy Service has been removed in JWS 2.0.

3.5.2 Available Only Through the Properties FileIf you customized session-tracking properties in your old installation, you’ll probabwant to perform those same customizations in the new installation. To do so, copycustomizations from:

JWS1.1.3/properties/server/javawebserver/server.properties

to each of the following files:

JWS2.0/properties/server/javawebserver/sessionservice/session.proper-ties

JWS2.0/properties/service_defaults/sessionservice/session.properties

Changed in 2.0.A session service has been added in JWS 2.0, allowing sessions ttracked server-wide, across services.

3.6 Documents

If you used a custom document directory in your old installation, rather than the defdirectory (public_html ), create the same custom document directory name in the ninstallation.

Copy all the document files from your old installation to the new.

For example:

# cp /opt/JavaWebServer1.1.3/public_html/myHTMLfile

/opt/JavaWebServer2.0/public_html/myHTMLfile

Changed in 2.0.In JWS 1.1.3, the same default directory was used for both thewebpage and secure services (although you could choose to use different ones). In2.0, the default directory for the webpage service remains the same (public_html ),but the default directory for the secure service is nowsecure_html .

Changed in 2.0.In JWS 1.1.3, document files for the samples were in the default dment directory (public_html ). In JWS 2.0, document files needed for the samples ain the examples/ directory of the server installation, under the relevant sample.

3.7 Additional Possibilities for Migration

• Did you add a new service to your old JWS? If so, usenew_server_root/bin/addservice to add the new service to the JWS 2.0. Once



e

you have added the additional service, follow the instructions under theser-vice /server Properties section to customize the service.

• Did you modify any of the default servlets, CGI scripts,jhtml files, orshtml files?

• Did you create any custom realms? If so, don’t forget to copy all the necessaryclasses for your custom realm from your old installation to you new. An examplmight be:

Solaris

% cp /opt/JavaWebServer1.1.3/classes/myCustomRealm.class

/opt/JavaWebServer2.0/classes/myCustomRealm.class

Windows

D:\> copy C:\JavaWebServer1.1.3\classes\myCustomRealm.class

C:\JavaWebServer2.0\classes\myCustomRealm.class

• Were you using any additional native code?

• Are there any other files in old_server_root hierarchy that do not appear in thenew_server_root hierarchy?
