
   Ganymede Logo
   
                          Ganymede Installation Guide
                       Release 1.0.11 - 9 December 2002
                                       
     _________________________________________________________________
                                      
   Note: If you are reading this as the INSTALL text file in the Ganymede
   distribution directory, you are missing a bunch of hyper-links that
   link to extra information about many topics discussed. If you can,
   view this document with a web browser as doc/install.html.
   
_-1. Quick Install Cheat Sheet_

   I really, really, really recommend you try and read through this whole
   document to learn how to install Ganymede, but if you absolutely,
   positively refuse to read something this long, here is the thumbnail
   sketch:
   
    1. Run configure in the Ganymede distribution top-level directory
    2. Run the installServer, installClient and installWeb scripts
       generated by configure to install the server, clients, and web
       access clients.
    3. Configure your web server to recognize the
       application/x-java-jnlp-file MIME type if you want to support a
       JNLP launcher such as Sun's Java Web Start (at
       http://java.sun.com/products/javawebstart/) application launch
       manager as a convenience for your users.
    4. Install a schema kit on top of the server using the schema kit's
       installKit script.
    5. Run the server by running <server-dir>/bin/runServer
    6. Run the schema kit's loader.pl script to generate a data.xml file
       that will contain all the configuration information and directory
       data to be imported into the Ganymede server.
    7. Run <server-dir>/bin/xmlclient on the XML file generated by the
       schema kit's loader.pl script.
       
   Pretty easy, huh? Of course, the devil is in the details, and to learn
   about those, you'll want to read the rest of this file in detail, as
   well as whatever documentation comes with any schema kit you may be
   using.
   
_0. Overview_

   Ganymede is a client-server system with three distinct components that
   need to be installed in order to use it. These parts are the Ganymede
   server, the Ganymede client suite, and the schema kit.
   
   The server acts as a central repository and control system, storing
   your network directory information in its built-in object database and
   updating various network services when changes are made. The server is
   designed to be installed on a UNIX system, and depends on Java and
   Perl to carry out its internal and external operations.
   
   The Ganymede client suite includes a variety of command-line, web, and
   GUI clients that can connect to the Ganymede server over the network.
   The Ganymede distribution includes a script to install these clients
   on UNIX systems, but most of the clients can be accessed over the web
   from a PC or Macintosh with a suitable version of Java installed.
   
   A schema kit contains all the pieces needed to turn the raw Ganymede
   engine into a custom-tailored database system shaped to fit a
   particular application. A schema kit defines the kinds of data to be
   held in the Ganymede server's database, custom logic to provide
   intelligent management of that data, and external scripts that take
   the data from the Ganymede server and integrate it into your network.
   Assuming that you don't want to try and develop your own database
   definition from scratch, you'll want to download a pre-built schema
   kit for use with your Ganymede server.
   
   The Ganymede distribution that you downloaded includes everything you
   need to install the server and client suite, but does not include a
   schema kit. You will need to visit
   ftp://ftp.arlut.utexas.edu/pub/ganymede/ or one of the mirrors listed
   at http://www.arlut.utexas.edu/gash2/Download.html in order to
   download a schema kit.
   
   This document will cover the installation of Ganymede from start to
   finish, using the 1.0 version of our newly developed userKit as an
   example. Any other schema kits that are developed will have some
   differences, but will likely be installed and used in similar ways.
   
_1. Requirements_

   The Ganymede system is designed to be easy to install for anyone
   running a Unix or Linux system with Java, Perl, and Bourne Shell
   installed. Ganymede is designed to work with any version of Java equal
   to or better than 1.1.7, but you will get very much better performance
   if you use Java 1.2.2 or later for the Ganymede server. Java 1.3 (or
   better) with the HotSpot server JVM will give you the best
   performance, and is recommended. You will need the full Java
   Development Kit (JDK or SDK) on your UNIX server so that you can
   compile any custom plug-in classes.
   
   Generally speaking, you should try to use the latest version of Java
   available when running the Ganymede clients on a UNIX-type system such
   as Linux, FreeBSD, Solaris, etc. However, be aware that Java version
   1.2 and 1.3 have extremely bad performance when you use X Windows to
   display the clients on a remote display. Java 1.4 is much faster when
   using networked X Windows, and is recommended.
   
   The Ganymede clients will also run using JDK 1.1.7 and 1.1.8, and you
   may find that this gives you the best performance when using X Windows
   on a remote display. JDK 1.1 also supports monochrome X displays,
   which later versions of Java do not. If you have to use a 1.1 series
   JDK, you will need to download and install the Swing/JFC GUI libraries
   from Sun, as the Ganymede clients require Swing, and Swing is not
   included with JDK 1.1. We anticipate that future versions of Ganymede
   will eventually drop support for JDK 1.1, however, so we would
   recommend using a later version of Java if you can.
   
   To run the Ganymede clients in a web browser on a desktop PC running
   some version of Windows 95/98/NT/2000/ME/etc., you will want to
   download and install version 1.3 (or better) of the Java Runtime
   Environment (JRE) for Windows. Version 1.3 and later of the Java
   Runtime Environment for Windows includes support for the Java Plug-In,
   a code module that will allow you to run the latest JVM's inside
   Netscape, Internet Explorer, and Mozilla.
   
   You can download any current version of the Java platform for Solaris,
   Linux, and Windows at http://java.sun.com/j2se/. Versions of Java for
   a number of other platforms may be found at
   http://java.sun.com/cgi-bin/java-ports.cgi. The Ganymede server has
   primarily been developed and tested on Solaris and Linux, but the
   Ganymede clients have been successfully run on Solaris, Linux, Windows
   95, Windows NT, MacOS 9, OS/2, FreeBSD, AIX, HP/UX, and others.
   
   In addition to Java, you will need /bin/sh and Perl 5.003 (or later)
   to run the Ganymede installation scripts. The Ganymede distribution,
   server and client, is designed to be unpacked and installed on a UNIX
   system with support for symbolic links. There is no installer provided
   for Windows or Macintosh. Instead, you have to install the clients on
   the UNIX system and then use a web server to publish the clients to
   your network, using either the Java Plugin or the Java Web Start
   tools.
   
   By default, Java's security model will not allow a downloaded applet
   to establish a network connection to any system other than the one it
   was downloaded from, so you will need to install Apache or another web
   server on the same machine on which you will be running the Ganymede
   server. You should probably go ahead and install the Ganymede server
   and Apache on a dedicated machine rather than installing the Ganymede
   server on your existing web server machine, if you are worried about
   performance.
   
   Note that Ganymede will not work through most firewall configurations,
   as the RMI protocol involves communications on a number of high port
   numbers that are chosen and assigned at runtime. In addition, as
   mentioned in the FAQ, Ganymede 1.0 does not encrypt its client/server
   communications. This is something that we are planning on adding for
   Ganymede 1.1, which will require Java 1.2 or better to run everything.
   For now, however, you should plan on keeping Ganymede safely behind a
   firewall. We have had success at running the Ganymede client on both
   the Cisco and Nortel VPN's. If you find yourself in that situation,
   send mail to the Ganymede mailing list at ganymede@arlut.utexas.edu
   and ask for the details.
   
_2. Configuring the Distribution for Your Site_

   The Ganymede distribution comes packaged with all of the Java classes
   for the server and clients pre-compiled and packaged up into jar files
   (located under the _jars/_ directory in the distribution directory).
   It is not necessary to compile anything in order to install the
   Ganymede server and clients, but you do have to run the configure
   script in the distribution directory in order to prepare the
   distribution for installation. The configure script is a
   custom-written Bourne shell script which searches around on your
   system to find Perl 5 and Java, and then uses that information to
   bootstrap the rest of the installation process.
   
   When you run configure, it will copy a few scripts from the _scripts/_
   directory into the top-level distribution directory, editing them to
   set the proper location for the Perl interpreter on your system, and
   otherwise setting everything up for you to proceed with installation.
   These scripts are installClient, installWeb and installServer. You
   will use these scripts to install the command-line UNIX clients, the
   web applet clients, and the server itself, respectively.
   
   In addition, the configure script goes through the _src_ directory and
   sets up scripts that can be used to compile the Ganymede sources.
   Generally speaking, you should not need to do this, as everything is
   precompiled in the _jars_ directory, but if you want to hack on the
   Ganymede server or clients, configure sets everything up so you can.
   See the README.source file in the top-level distribution directory for
   information on building the source tree if you want to investigate the
   source code.
   
_3. Installing the Server_

   Installing the Ganymede server is the next thing to be done after you
   have unpacked and configured the distribution. You should plan on
   installing the Ganymede server on a system that has Java and Perl
   installed, and which has a web server available to provide downloads
   of the Ganymede client applets for your users who will be accessing
   Ganymede through a web browser.
   
   The installServer script produced in the distribution directory by the
   configure script will ask you a series of questions, then install the
   Ganymede server in its own directory.
   
   These questions include the following:
   
   _Where are the jdk binaries located?_
          This is just asking for the directory that contains your
          system's java binaries. The configure script will attempt to
          provide a reasonable default for this question, but you may
          have to correct it if you have more than one version of java
          installed on your system and it chooses wrong.
          
   _Where should the server tree be installed?_
          This question is asking where you want to install the server at
          in your UNIX system's filesystem. The Ganymede server tree
          should not be installed in a location that is accessible to the
          average user, as all of your directory data is held in this
          directory tree. There is no default answer for this question,
          so you will have to pick a location. You can use either
          absolute or relative directory names here.
          
          Note that when you install the server, the installServer script
          customizes the server installation with the paths where you
          have installed the server. If you ever decide to move the
          server in your filesystem, you will need to create a symlink at
          the old location to allow the old paths to resolve properly, or
          you will need to go through the various scripts and files and
          make sure that any reference to the old path has been updated.
          
   _What is the name of the system that the server will run on?_
          This information is used by the stopServer and xmlclient
          clients that are installed into the server tree. This may be an
          I.P. address or a fully qualified DNS host name. The
          installServer script will provide the name of the system you
          are on as a default.
          
          Note that the Ganymede server needs to know a name for the
          server that will resolve to a network-accessible I.P. address.
          Some Linux systems are configured by default so that the system
          'hostname' command returns the system's name without any DNS
          domain information, and so that the system's name is mapped to
          '127.0.0.1' in the /etc/hosts file. On such systems, the
          Ganymede server may report an error message on startup,
          complaining that the system hostname and the
          _ganymede.serverhost_ definition both resolve to '127.0.0.1'.
          
          By answering this question with either a fully qualified DNS
          name or a network-accessible numeric address, the Ganymede
          server will be able to generate a proper network address for
          clients to use. If you discover after installing the server
          that you need to change the name that the Ganymede server uses
          to identify its network address, you can edit the
          ganymede.properties file and change the _ganymede.serverhost_
          definition to something that will resolve to a network
          accessible address.
          
   _What port should the RMI registry supporting Ganymede run on?_
          The RMI registry is a network lookup service that is used by
          the Ganymede clients to establish communications with the
          Ganymede server. By default, port number 1099 is used. If you
          are running certain other Java services, you may already have
          an RMI registry running, in which case you should pick another
          port number to run the Ganymede registry on. You may want to
          use 1100, 1101, or another non-used tcp port.
          
   _What mailhost should Ganymede use to send out diagnostic mail?_
          The Ganymede server is able to send out email in response to a
          variety of system events. If the UNIX system you are installing
          Ganymede on is able to send mail, you are probably okay with
          the default.
          
   _What email address should Ganymede sign on email that it sends out?_
          This question is asking you what Ganymede should put in the
          'From:' field of mail that it sends out in response to system
          events. In many configurations, the Ganymede server will send
          out mail using the name of the user whose action triggered
          mail, but for things like system shutdown/restart, etc. it
          needs an email address to go by. If this email address is not
          valid, users who reply to system event mail from Ganymede will
          have their replies bounce.
          
   _What name do you want the Ganymede superuser account to have?_
          The default 'supergash' name is probably okay here, but you can
          change it if you want.
          
   _What password do you want the superuser account to have?_
          This password provides complete access to the Ganymede server's
          database, and is necessary for a variety of system operations.
          
   _What name do you want the Ganymede monitor account to have?_
          The monitor account has no privileges to do anything at all to
          other than to login with the Ganymede admin console and view
          the server's activity log.
          
   _What password do you want the monitor account to have?_
          This password provides the right to watch the server's
          activities using the admin console, but provides no permission
          to log into the server and view or edit any data.
          
   Once you answer all these questions, the installServer script will
   proceed to install the Ganymede server in the location specified.
   
   Once installed, you will have a server directory that contains a
   number of directories, some documentation files, and a
   ganymede.properties file that the Ganymede server executables use as a
   configuration resource.
   
   The _bin/_ directory contains:
   
     * runServer, which actually runs the server
     * stopServer, a script that can be used to cleanly shut the server
       down.
     * xmlclient, a script that is used to load XML-formatted data into
       the Ganymede server.
     * logscan.pl, a script that is used by the server to accelerate
       searches through the Ganymede log file.
       
   The _db/_ directory contains:
   
     * The ganymede.db file, which contains all data objects and schema
       definitions held by the Ganymede server.
     * A running journal file that records all transactions made by the
       server so that the server can fully recover if it ever crashes or
       if the system running it goes down.
     * A comprehensive log file, which documents all changes made to the
       database.
       
   The _jars/_ directory contains the compiled java classes that actually
   comprise the Ganymede server and the Java-based stopServer and
   xmlclient clients.
   
   The _doc/_ directory contains copies of all of the Ganymede
   documentation.
   
   The _backups/_ directory is used by certain schema kits to store
   backup copies of any networking files written out by the schema kit's
   builder tasks. These back up copies will be written into
   subdirectories that are named by date, and which will be automatically
   zipped up once a day. Nothing in this directory is used by the
   Ganymede server for any purpose other than your peace of mind in case
   you have a problem with the Ganymede server and need to get back an
   old copy of a passwd or nis file in a pinch. If you don't want to
   spend the disk space on archival copies of your network data files,
   just edit the ganymede.properties file and comment out the
   'ganymede.builder.backups' property.
   
_4. Installing A Schema Kit_

   Once you have the server installed, you can proceed to install a
   schema kit, which will customize and configure the server for your
   requirements.
   
   When you download and unpack a schema kit, you should find
   documentation that will walk you through the installation process.
   Essentially it comes down to running a _installKit_ script, which will
   ask you where you installed your server and where Java is, and will
   then create a _schema_ directory under your server directory. This
   directory should include:
   
     * a _custom.jar_ file that includes the Java classes to be added to
       your server by the schema kit
     * a _src/_ directory that contains all of the Java source code that
       was compiled into the custom.jar file.
     * a _scripts/_ directory, that contains various Perl scripts used by
       the schema kit.
     * an _output/_ directory that contains any networking files that are
       written out by the Ganymede server when transactions are
       committed, as well as the scripts that are run to handle external
       actions when those transactions are committed.
     * and finally, you will probably see some kind of loader script that
       can import data from your existing environment and generate an XML
       file for use with the xmlclient.
       
   The most important of these as far as the server is concerned is the
   custom.jar file. Once that file is in place, you can proceed to run
   the Ganymede server, which will then start up and find the extra
   classes needed to run the server with your schema kit.
   
   The schema kit that you install should include a README that will talk
   in great detail about the operational aspects of running the server
   with that schema kit installed. This will include but is not limited
   to what sort of data is written out to disk when transactions are
   committed in the server, and how that data is integrated into the
   network environment.
   
   For now, however, we are going to continue with a generic discussion
   of how one runs the server, how one typically loads data into the
   server, etc. For further details on all of this works with the schema
   kit you choose to use, see the schema kit README file.
   
_5. Running the Ganymede Server_

   Once you have installed your schema kit, you can go ahead and run the
   server. You do this by running the runServer script in the server's
   _bin/_ directory. runServer starts up the rmiregistry on the port you
   indicated when running _installServer_, then runs the Ganymede server
   itself.
   
   The Ganymede server is a pure Java application, so when you run it,
   you are really running your platform's java execution environment
   (which may be an interpreter, a JIT compiler, or an advanced hybrid).
   Java doesn't provide a lot of access to operating-system level
   functionality, so the Ganymede server doesn't know how to detach
   itself from your terminal window or console, and it doesn't know how
   to respond gracefully to kill signals.
   
   Because of these reasons, we suggest you run the Ganymede server in a
   fashion similar to this:
   
      server% bin/runServer >& server.log &

   if you are running csh or tcsh, or
   
      bash$ bin/runServer > server.log 2>&1 &

   if you are running sh or bash.
   
   In either case, you want to capture all stdout and stderr output from
   the server into a log file. The Ganymede server will print out status
   and error messages as it runs, and you really want to capture this
   information.
   
   You can view the server's log as the server runs with the tail
   command, using the -f option, as follows:
   
      server% tail -f server.log

   That way, if your window is killed or you absent-mindedly hit ctrl-c,
   you will only kill off the tail command. You want the server itself to
   run in the background, undisturbed.
   
   The _installServer_ script is smart enough to try and identify the
   version of Java you are running, and to install a version of runServer
   that matches. If you look at runServer, however, you will see that
   there are a number of optional command line parameters you can provide
   to tweak the Ganymede server's behavior.
   
   Of particular interest in this regard are the -resetadmin and the
   debug=xxx parameters. These are both documented in the runServer
   script itself, but it is worth discussing them here. The -resetadmin
   parameter causes the Ganymede server to reset the administrative
   'supergash' password in the system to the value defined in the
   server's ganymede.properties file. It is reasonable to remove the
   'ganymede.defaultrootpass' property from the ganymede.properties file
   if you don't want to leave your Ganymede 'root' password lying around
   in plaintext, but if you ever forget the password, you'll want to keep
   the -resetadmin parameter option in mind. You should not remove the
   ganymede.defaultrootpass property until the server has successfully
   started up and created its ganymede.db file, however.
   
   If the debug=xxx parameter is used, the Ganymede server will log all
   network calls made by clients to a debug log file of your choice. This
   may degrade performance very slightly, but it will provide an
   invaluable trace and exception log if the server ever hangs or
   crashes. Unless you know you will never need to worry about the
   possibility of exceptions in the server, I'd recommend you leave the
   debug=xxx parameter as you find it. The _installServer_ script will
   install the runServer script with the debug option set to generate a
   debug.log file in your server's top-level directory.
   
   While the server is running, you should see two separate Java
   processes running, one for the rmiregistry, and one for the Ganymede
   server. If you are running the Ganymede server on a Linux system, you
   may see what looks like a very large number of Java processes running.
   This is perfectly normal. In current versions of Linux, the ps and top
   commands will show you a separate entry for each thread that is
   running in a given process. Both the rmiregistry and the Ganymede
   server are heavily multithreaded, so you should expect to see dozens
   of Java threads running on a Linux system.
   
   When you want to shut the server down, you'll just need to order it to
   shut down from the Ganymede admin console (which we'll talk about
   below), or by using the stopServer script in the server's _bin/_
   directory. Either one will transmit to the server a shutdown message,
   which will result in the server kicking any active users off the
   system, consolidating its database to disk, and finally shutting down.
   The Ganymede server is designed to recover smoothly on restart if it
   is killed or if the system crashes or is rebooted at any point during
   its execution, but the server might spend a bit of time on clean up
   work on start up in such cases.
   
   Shutting down the server won't automatically stop the rmiregistry
   process, so you will have to do a bit of manual cleanup to get rid of
   it if it bothers you to leave it running. Otherwise, the Ganymede
   server will re-attach to the rmiregistry when you restart the server,
   but you'll see an exception message displayed when the runServer tries
   and fails to start a new rmiregistry process on the same port.
   
   If you know that you don't want to start the server back up again, it
   is perfectly fine to go ahead and use the Unix kill command to kill
   off the rmiregistry process. Just be careful you've got the one on the
   right port, or else you might cause problems for any other Java
   services that are running on your system.
   
_6. Loading Data Into the Server_

   Now you have installed the server, integrated a schema kit into the
   server directory, and started the server running. You can now proceed
   to use the schema kit to load data into the server.
   
   When you first run the Ganymede server, the server will look in its
   _db/_ directory for its ganymede.db file. When it doesn't find it, it
   will initialize itself with its default database configuration. The
   Ganymede server will only know about those objects and fields that it
   uses for its own operations. Before the Ganymede server can handle the
   data for your network's directories, you will need to define your
   custom object and field types in the Ganymede server.
   
   The Ganymede admin console has an 'Edit Schema' menu item which you
   can use to bring up a graphical schema editor. With the schema editor,
   you can define new object types and define fields within the object
   types. Designing and implementing a new schema definition is a bit
   involved, and is beyond the scope of this installation guide.
   
   Fortunately for you, though, you're using a schema kit, so we will
   just let it do that work. For the rest of this discussion, we'll
   pretend you have downloaded and installed a schema kit that is almost
   entirely not unlike the _userKit_ schema kit that we are releasing
   with Ganymede 1.0. If you are not using that schema kit, you'll have
   to improvise along the same lines.
   
   If you look in the _schema/_ directory that the schema kit's
   _installKit_ script placed in your server directory, you will see a
   _loader.pl_ script and a _schema.xml_ file. The _loader.pl_ script is
   designed to take the database definition information contained in the
   _schema.xml_ file and combine it with your data to create a _data.xml_
   file that you can then load into the Ganymede server.
   
   Actually running the _loader.pl_ script should be relatively straight
   forward, but you will want to consult the schema kit's documentation
   for information on what sort of data it can import, what configuration
   options the schema kit's plug-in logic classes support, and the full
   details on integrating Ganymede and that schema kit into your
   environment.
   
   For now, we'll just assume that _loader.pl_ has produced a _data.xml_
   file that is formatted according to the Ganymede XML File Format
   Guide. Now all you need to do is cd to your server's top-level
   directory and run
   
      server% bin/xmlclient schema/data.xml

   This will cause the xmlclient to log into the server and upload both
   the schema kit's schema definition and your data to the server.
   xmlclient will produce some output while it runs, but it is designed
   for speed over interactivity, and so it may go quiet for long periods
   of time while it waits for the server to chew through the XML that it
   has submitted. If you like, you can run the Ganymede admin console
   before starting xmlclient and actually watch as the xmlclient talks to
   the server and creates all your objects in the database.
   
   If all goes well, you should expect to see a bunch of messages about
   it editing the server's schema and then creating a bunch of objects
   from your data. If something goes amiss, you should see some
   information telling you where in the xml data stream it found
   something that it didn't like. With luck, a little hand-editing of the
   _data.xml_ file will let you put things right and try again.
   
   There is quite a lot more to say about how the schema kits are
   constructed and how they operate, but this isn't the place for it.
   Check in the schema kit for documentation on operations with the
   schema kit. For now, be aware that the _data.xml_ file generated by
   the userKit's _loader.pl_ script is designed to initialize the
   Ganymede database from scratch, and not to import new data to a server
   that has already been up and running with data for awhile. For the
   full story on how to write XML files to do data editing in the
   Ganymede server, see the xml.html file in the _doc/_ directory.
   
_7. Installing UNIX Client Files_

   The Ganymede system has two primary clients, the Ganymede GUI client
   and the Ganymede admin console. Both can be run from a UNIX command
   line with a shell script that will run java on them, or from a web
   browser with support for the 1.1 JDK standard with the Swing classes
   added.
   
   We have provided an install script for installing the Ganymede clients
   on a UNIX system. installClient will prompt you for the name of the
   machine that will be running your Ganymede server, and the directory
   which will contain the bin, html, and jars directories. The install
   script will then customize and install scripts for you so that the
   end-user client and admin console can easily be run.
   
   Don't try to install the client and server into the same directory..
   the two are meant to be installed separately, in separate directories.
   This is important because the server files need to be kept out of the
   reach of non-privileged users, while the client files are intended to
   be available for anyone to run.
   
   Note that we don't provide any kind of script to install the Ganymede
   clients on a Windows or Macintosh system directly, but you can use a
   JNLP launcher to achieve this. See the Web Server Configuration
   section of this document, below, for details on supporting JNLP
   launch.
   
   In general, you should be able to run the Ganymede clients on any
   platform that supports JDK 1.1 or better with the Swing classes, as
   the clients are written in pure Java. The Ganymede clients are
   dual-mode, and will work both as an applet and as a command line
   application. If you are trying to run the clients on a platform like
   OS/2, AS/400, or VMS, and can't take advantage of JNLP launch
   services, you may want to examine the ganymede and ganymedeAdmin
   launch scripts installed by the installClient script and create
   appropriate translations of the launch scripts for your platform.
   
_8. Prepare web access clients_

   The installWeb script is used to install, on your UNIX system, the
   html, cgi, and java files needed to support client access to Ganymede
   from a web browser. When you run installWeb, it will ask you a small
   number of questions, including the following:
   
   _What is the name of the system that the server will run on?_
          This question is used to configure the applet launch page that
          your users will access to run the Ganymede applets. This should
          be the name of the system on which you are going to run the
          Ganymede server.
          
   _What port is the RMI registry supporting Ganymede running on?_
          As with installClient and installServer, this is asking you for
          the port number for the Ganymede server's rmiregistry. This
          number must match the one used when you installed the server.
          
   _Where should the web access files be installed?_
          This is asking for the name of a directory in which to install
          the web access files. If this directory does not exist, it will
          be created in the directory containing it. This directory will
          need to be mappable to a url by a web server running on the
          same machine that will be running your Ganymede server.
          
   _What URL path will resolve to the ganymede web access directory?_
          This question is asking what URL the installed web access files
          will map to in your web server. The installWeb script needs
          this information in order to configure the Java Network Launch
          Protocol (JNLP) files for the Ganymede client and admin console
          for use with the Java Web Start launch manager.
          
          If you don't get this right when you install the clients, the
          Java Web Start option will not work properly. You can edit the
          installed client.jnlp and console.jnlp files to fix this after
          the fact, if need be.
          
   _Where will the ganymede client binaries be installed?_
          This is asking for the directory that contains (or will
          contain) the Ganymede text mode clients, in particular
          xmlclient. The directory containing xmlclient must be
          accessible by the user account that your web server runs under,
          so that the ganypass.pl CGI script can properly communicate
          with the Ganymede server.
          
   installWeb will configure and install a bunch of files into a
   designated directory, including an index.html file, a couple of jar
   files containing the classes for the Ganymede gui client and admin
   console, a CGI script that will allow your users to change their
   passwords through their web browser using an HTML file, and various
   support files. These files are customized during installation to point
   to the proper location for your Ganymede server.
   
   In order for your users to run the Ganymede client applets in their
   web browsers, you will have to install and configure a web server on
   the same machine that you will be running the Ganymede server. The
   reason for this requirement is that Java applets are run in a security
   "sandbox", which puts security restrictions on downloaded code. One of
   these restrictions is that unsigned applets are only allowed to open
   networking connections to the same machine that the applet was
   downloaded from.
   
   Because of this, you will have to install a web server on the same
   machine as your Ganymede server, and you will have to configure your
   web server so that your users can access the web client directory
   through the web server. You should set up an alias in your httpd.conf
   file that maps a URL path like "/ganymede" to your web client
   directory. This directory should be configured to allow running CGI
   scripts with the extension '.pl', to support the password change CGI
   script that is installed in that directory. If you want to support the
   Java Web Start launch option, you will also need to configure your web
   server to recognize .jnlp files as being of MIME type
   application/x-java-jnlp-file. See section 9, below, for details on
   this.
   
   Once the web server has been configured and the web clients installed,
   your users will be able to access your web client directory to run the
   Ganymede applet launcher (through the index.html file), or to run the
   Ganymede password change CGI script, ganypass.pl. The ganypass.pl
   script is useful because it allows any web browser that supports HTML
   forms to be used to change a user's password, whereas the full
   Ganymede client launcher requires both JavaScript and Java support.
   
   If you do want your users to be able to run the full Ganymede client,
   you will need to be sure that their web browsers are configured
   properly. The installed web files include versions of the Ganymede
   client pages designed for use with the Java plug-in on Windows
   (version 1.3.0 or better is really best.. see java.sun.com/j2se to
   download the Java plug-in), JNLP files to support client launch with
   the Java Web Start program, and a version of the client pages designed
   for use with a browser with built-in RMI and Swing support. The
   'native' option is intended for users of web browsers that have
   built-in support for Sun's latest JVM plug-ins. This includes the
   Netscape browser under OS/2, the Internet Explorer browser on
   Macintosh, and the Mozilla/Netscape 6 browser on Macintosh, Windows,
   Linux, and Solaris.
   
   On the Macintosh with Internet Explorer, you need to install the very
   latest version of Apple's Macintosh Runtime for Java. Current version
   of the MRJ for traditional MacOS are based on Java 1.1, and do not
   include the Swing class libraries required by the Ganymede clients. In
   order to make Ganymede work on such systems, you will need to extract
   the swingall.jar file from Sun's JDK and install it on your Macintosh
   in a directory of your choosing. Internet Explorer has a preferences
   option to add additional class paths to your browser's Java
   environment. Find and add the swingall.jar file to your Internet
   Explorer Java class list and you should be ready to go, using the
   native mode client.
   
   Windows users using Netscape 4.x or any version of Internet Explorer
   will need to use either the Java Web Start or the Plug-In launch
   modes. The Java Web Start mode is most convenient, but will require
   that your users have the Java Web Start software installed on their
   systems. The Plug-In mode is less convenient, as your users will have
   to run the Ganymede clients from within their web browser, and also
   requires that custom software be downloaded and installed on their
   systems.
   
   Installing the Java Plug-in software is pretty simple. If your users
   do not install the Java plug-in before trying to run the Plug-In
   clients, their web browser will help them download the Plug-In as
   needed. Once the Java Plug-In is downloaded, the user will need to
   quit out of the browser and run the Plug-In control panel. Configure
   the Plug-In so that the network and class access is unrestricted and
   unsigned applets are allowed. Apply the preference changes, and
   restart the browser. The Ganymede Plug-In clients should work properly
   now.
   
   _IMPORTANT NOTE_: whenever you run applets using the Java Plug-In, the
   applets can only run as long as the log-in applet is still displayed
   in the web browser. If you close the main browser window or click to a
   different page (either by following a link or by clicking back on the
   browser), the applet will be shut down. Both the Ganymede client and
   admin console have been written so that this shut-down is handled in
   an orderly fashion, but the shut-down is unavoidable, so be sure not
   to disturb the applet frame while you are using the client or console.
   
_9. Configure your web server to support Java Web Start_

   As of Ganymede 1.0.5, Ganymede supports the use of Sun's Java Web
   Start at http://java.sun.com/products/javawebstart/ to handle
   launching the Ganymede client and admin console. With Java Web Start,
   your users will be able to run the Ganymede client applets on their
   Windows desktops without needing to bother with a web browser. Users
   on platforms other than Windows may want to look at the OpenJNLP
   project at http://openjnlp.nanode.org/ or the JavaURL project at
   http://www.amherst.edu/~tliron/javaurl/.
   
   In order to support any JNLP launcher service on the client, your web
   server has to be configured to identify the proper MIME type for the
   Java Network Launch Protocol (.jnlp) files that tell the Java Web
   Start system how to manage the Ganymede clients.
   
   If you are running Apache, configuring your web server to support the
   Java Web Start option for launching the Ganymede clients is simple.
   You just need to add the following line to your httpd.conf:
   
        AddType application/x-java-jnlp-file .jnlp


   Alternately, you can add the following line to your server's
   mime.types file:
   
        application/x-java-jnlp-file jnlp


   Whichever approach you choose, you may need to cause your web server
   to re-read its configuration file. With an Apache server, this can be
   achieved by sending a HUP signal to the server. If you don't know what
   that means, simply stopping and restarting your web server should work
   too.
   
   If you don't perform this step, your users will not be able to use the
   Java Web Start launch option, but they should still be able to run the
   Ganymede clients from their web browser, with somewhat less
   convenience, if they have the Java Plugin installed.
   
     _________________________________________________________________
                                      
   
    Jonathan Abbey
    
   Last modified: Tue Apr 2 19:30:10 CST 2002
