This document has the following sections:

• Supported Platforms
• Prerequisites
• Installation
• Environment Variables
• Startup
• Shutdown
• Removal
• Documentation

The Java Web Server runs on any platform that supports the Java Development Kit (JDK^TM) 1.1 or above.

Prerequisites

Hardware Prerequisites

• the download file is approximately 14 MB.
• to install it, you require roughly 20 MB of hard drive space,

For Windows NT or Windows 95

• the download file is approximately 10 MB.
• to install it, you require roughly 13 MB of hard drive space.

Software Prerequisites

To use Java Web Server, you need a server environment (to run the server itself) as well as a client environment (from which to run administrative tools).

For the server environment, you need EITHER:

• JDK1.1 or above, OR
• a JDK1.1 (or above)-compliant Java runtime environment (JRE)

Note: The Windows and Solaris distributions of this product take care of this for you; they are bundled with the JRE 1.1.4.

For up-to-date information on whether your target platform supports JDK 1.1, please contact the platform's vendor.

In addition, on Windows 95, you need:

• Windows Sockets 2 (WinSock 2)

  WinSock2 may be downloaded from Microsoft's site at:
  http://www.microsoft.com/win32dev/netwrk/winsock2/ws295sdk.html

  Note: You cannot run the Java Web Server on Windows 95 in disconnected mode. This is because Windows 95 will not recognize local host with WinSock2 installed. (This problem does not affect Windows NT 4.0, which ships with WinSock2.)

For the the client environment, you need:

• a JDK 1.0.2-compatible browser

Note: Most browsers are JDK 1.0.2-compatible. Current versions of Netscape Navigator (3.0, 4.0), Microsoft Internet Explorer (3.0), and AppletViewer (1.0.2, 1.1) are known to be compatible.

Installation

Installing on Solaris

1. Download the Java Web Server compressed tar file from the Java Web Server web site. Instructions for doing this are available at the site.

2. Move the compressed tar file to the directory where you want to install the Java Web Server software. The Java Web Server can be installed in any directory in your system.
3. Uncompress the tar file (this will remove the .Z extension). To uncompress, enter:

   % uncompress tarfile

   The tar file is now ready to be installed.
4. Install the contents of the tar file. To do this, enter:
   

   % tar xvf tarfile

   This creates a directory called JavaWebServer1.1, which contains the product release. The JavaWebServer1.1 directory is also called the server_root. This term is used throughout the Java Web Server documentation.

After you have finished installing the Java Web Server, you can delete the tarfile, if you wish.

Security Note:

If you extract the Java Web Server 1.1 release on UNIX^TM, using some user account other than "root", you should be aware that the "TAR" command will use your UMASK when creating directories, and this can create security holes. The distribution has no need for any files which are writable by "group" or "world".

To work around this problem, either:

• Restore permissions after you extract the release

  chmod -R og-w JavaWebServer1.1

OR

• Extract the release using the "p" option to TAR, to preserve the file modes found on the distribution.

  % tar xvfp tarfile

Installing on Windows95 and Windows NT

1. Download the Java Web Server self-extracting file (.exe) from the Java Web Server web site. Instructions for doing this are available at the site.
2. Move the self-extracting file to the directory where you want to install the Java Web Server software. The Java Web Server can be installed in any directory in your system.
3. Double-click on the self-extracting file to extract the Java Web Server installation files into the directory and launch the Setup program.
4. Follow the instructions in the Setup program to install Java Web Server in a directory location on your hard disk. By default, Setup installs Java Web Server in C:\JavaWebServer1.1. The JavaWebServer1.1 directory is also called the server_root. This term is used throughout the Java Web Server documentation.
5. If you are installing on Windows NT, a question will be asked by InstallShield if you want to install the NT Service application.

   If you click yes, an entry will be added to the Control Panels -> Services and the Java Web Server NT Service will be started up automatically and every time you restart your system.

   If you click no, no entry will be made and you can still start up the NT Service as described in Starting automatically on Windows NT.

After you have finished installing the Java Web Server you can delete the temporary directory, if you wish.

Environment Variables in Java Web Server

Using the Default Java Runtime Environment

The Java Web Server ships with a Java Runtime Environment (JRE). By default, the Java Web Server uses this included JRE -- which means you don't have to be concerned about your CLASSPATH or JAVAHOME settings, their values are ignored. (For this default situation, the Java Web Server uses the httpd startup script or the httpd.exe executable. )

Using your Existing Java Runtime Environment

To use your existing runtime and environment rather than the provided JRE, invoke the httpd.nojre startup script or httpdnjre.exe executable.

Accessing your Servlets

If you are using the default JRE and its associated class path, create a /classes subdirectory to your Java Web Server install directory. The default class path will always have the classes subdirectory in the server_root directory included. Note that these classes cannot be in jar format.

If you are using your existing runtime and class path, simply make sure the directory containing your servlets is in the CLASSPATH environment variable.

Environment Variables with Quoted Strings

JAVA_HOME=C:"\PROGRAM FILES\JAVA"

The affected variables are PATH, JAVA_HOME, and CLASSPATH.

Startup

Starting the Java Web Server on Solaris

When first installed, no log directory is created. It is created by the server runtime the first time the server is started. Permissions on the logs are granted based on the user running the server at this initial time.

For example, if you run the server for the first time as a usernameA, the logs are owned by usernameA. Subsequent runs by any other user (including root) will result in a "failure to open logs" error due to permission problems.

To correct this problem, either run the server for the first time as "nobody" or reset the permissions on the logs.

To manually start the Java Web Server on Solaris:

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

   % cd server_root/bin

2. Invoke the server process.

   % ./httpd

3. Connect to the server by entering the server/port address in your browser's locator field. For details, see displaying the default home page.

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

To automatically start the Java Web Server on Solaris

On Solaris systems, to start the Java Web Server whenever your machine boots, use the server_root/etc/java-server.startup shell script. It is a standard /etc/init.d style script and it contains installation directions. This requires setting two environment variables (pointing to the Java runtime environment and the server_root/etc/java-server.startup directory).

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

To manually start the Java Web Server on a Windows platform:

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

   C> cd server_root\bin

2. Invoke the server process.

   C> ./httpd

3. Connect to the server by entering the server/port address in your browser's locator field. For details, see displaying the default home page.

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

Note: The source file for httpd.exe is called httpd.c, and is located in the bin directory. If you want, you can edit httpd.c and then recompile it.

To automatically start the Java Web Server on a Windows NT platform:

• If you clicked yes when the InstallShield utility asked you if you wanted the NT Service application installed, simply restart your system.

  The Windows NT service application $HTTP_HOME/bin/jservsvc is generally installed during the Java Web Server installation using the InstallShield facility. Once it is installed, you can start it automatically by rebooting your machine. Rebooting sets up your system so that each subsequent reboot automatically starts the Java Web Server.

• If you clicked no when install program asked you if you wanted to install the NT Service application, you can still set up for automatic starting by following these steps:
  1. Make sure you have administrator privileges.
  2. Run the following command
     1. C> cd server_root\bin
     2. C> jservsvc JavaWebServer install

  Note: The automatic startup of system services applies only to Windows NT, versions 3.5.1 and 4.0. Windows 95 does not support the automatic start up of system services.

1. Log in as root on your machine
2. Start the Java Web Server
3. Start the Administration Tool
4. Go to the Network section for the Web Service and change the port number to 80.

If you want to run your server with a different user and group ID than nobody/nobody, then do the following:

1. Log in as root on your machine
2. Open the file server_root/properties/server/javawebserver/server.properties
3. Look for the following lines:

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

4. Change nobody to the user and group names you have decided upon, if any. Note that usernames with spaces are not allowed by the Java Web Server.
5. Save and exit the file.
6. Issue the command to change owners:

         # chown -R userid  server_root
     

7. Issue the command to change groups:

         # chgrp -R userid  server_root
     

After you have started the Java Web Server, you can connect to the server by displaying the default home page.

Displaying the Default Home Page

http://Server_Host_Name: port /

where Server_Host_Name is the name of your machine and port is 8080 by default. (For example, if your machine is named galaxy, http://galaxy:8080).

On Windows 95 and Windows NT platforms, the Server_Host_Name is the name assigned to your computer, as specified in the Network control panel. To find this name:

1. Open the Network control panel

2. Click on Identification. Use the name supplied in the "Computer name" field for the Server_Host_Name.

To set up your own web site, use your normal web authoring tools to change the contents of the default home page. Then tell your clients about your site!

Shutdown

• Through the Administration Tool (Recommended)

  On all platforms, the recommended procedure for shutting down is through the Java Web Server GUI, as follows:

  1. Connect to the server through a browser
  2. Choose "Administer the Web Server"
  3. Choose "Start the Adminstration Tool"
  4. Log in to the Java Server Administration Tool
  5. Select the Java Web Server
  6. Click the Shutdown button

  Note:

  • Clicking Stop closes down the the server or service and removes it from the autostart list.
  • Clicking Shutdown closes down the entire Java Web Server (server and services) but leaves the autostart list (states) alone. All services running at the time of shutdown will be started when the server restarts.

  If shutting down the Java Web Server through the Administration Tool is not possible or desirable for some reason, the second choice is to shut it down from a command line prompt. Instructions for performing a shutdown from the commandline for the UNIX and Windows platforms is provided in the following sections.

• From a command line

  On all platforms, a command line utility is provide to shut down the server and its services.

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

     % cd server_root/bin

  2. Invoke the shutdown process.

     % ./jsadmin user/password -stop

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

     % ./jsadmin admin/admin -stop

Removing the Java Web Server

1. % cd server_root
2. % rm -r *

Removing Java Web Server From a Windows Machine

• On Windows NT 4.0
  1. If you installed the NT service, manually remove it first:
     1. C> cd server_root\bin
     2. C> jservsvc JavaWebServer remove
  2. Then remove the Java Web Server itself either automatically:
     1. Click on the Control Panel.
     2. Click on Add/Remove Programs.
     3. Highlight on the Java Web Server entry in the window and then click on Add/Remove.

     or, remove it manually:

     1. C> cd server_root
     2. C> rm -r *

• On Windows NT 3.5.1,
  1. If you installed the NT service, manually remove it first:
     1. C> cd server_root\bin
     2. C> jservsvc JavaWebServer remove
  2. Then remove the Java Web Server itself either automatically:
     • Double-click on the UnInstall icon from the Java Web Server program folder.

     or, remove it manually by typing:

     1. C> cd server_root
     2. C> rm -r *
• On Windows 95, remove it automatically.
  1. Click on the Control Panel.
  2. Click on Add/Remove Programs.
  3. Highlight on the Java Web Server entry in the window and then click on Add/Remove.

Using Java Web Server Administration

1. From the default home page (on port 8080) click on the link labeled Administer the Web Server.

   Note: You can also connect to the Administration Tool by typing its URL. For example, if the host name for your Java Web Server is bagua, then you enter the URL http://bagua:9090/index.html.

2. Login using the default user name admin and the default password admin

Once you have logged in, you'll want to change the password for the default "admin" account. For more information on using the Java Web Server Administration, see the Administration Contents page.

NOTE: Most server properties can be changed without needing to restart the server. However, if you change the default port, you must restart the server. To change the default port number, use the Network Setup page.

Changing Your Admin Password and Default Port

• Change your default password
.
• Assign your Administration Service to a new port (not 9090)
.

For details on doing how to perform these steps, see the Properties document.

If You Have Lost Your Password

1. Stop your Java Web Server.
2. In your favorite text editor, open the file

   server_root/realms/data/adminRealm/keyfile

3. Change the admin line there so that it reads:

   admin::YWRtaW4=

4. Save the file.
5. Restart your Java Web Server.

Using the Documentation

To display the documentation, enter the following URL:

http://Server_Host_Name:8080/system/doc

You can also display the documentation by:

Clicking "Help" from any of the Server Administrator screens.

Look for Frequently Asked Questions and updates to the documentation on the Java Web Server web site.

Top java-server-feedback@java.sun.com

Copyright © 1997 Sun Microsystems, Inc. All Rights Reserved.