INSTALL

                          Ganymede Installation Guide
                           Release 2.0 - 5 April 2013

   --------------------------------------------------------------------------

   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 scripting languages
   such as Perl or Python 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 server is designed to be easy to install for anyone running a
   Unix, Linux, or Mac OS X system with Java, Perl, Bourne Shell, and Apache
   Ant installed. Ganymede 2.0 is designed to work with Java 6 or later. 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.

   Ganymede has no dependencies on any Java classes other than what comes
   with the JDK or in the Ganymede distribution.

   You can download Oracle's official release of the Java platform for Mac OS
   X, Linux, Windows or Solaris at
   http://www.oracle.com/technetwork/java/javase/downloads/index.html/. The
   Ganymede server has primarily been developed and tested on Linux, but the
   Ganymede clients have been successfully run on Solaris, Linux, Windows XP,
   Vista, Mac OS X Jaguar and later, FreeBSD, AIX, HP/UX, and others.

   If you're running Linux, your distribution probably provides an up-to-date
   version of OpenJDK, which Ganymede is also fully compatible with.

   As well as Java, you will need /bin/sh, Perl 5.003 (or later), and Apache
   Ant to build and install the Ganymede software. The Ganymede distribution,
   server and client, is designed to be unpacked and installed on a
   UNIX-style system.

   There are command line client scripts for Unix style systems (ganymede,
   ganymedeAdmin, xmlclient), but most of your users will probably use Java
   Web Start to run the graphical clients on their desktops.

   To run the Ganymede clients in a web browser on a desktop PC running some
   version of Windows, you will want to download and install version 6 or
   better of the Java Runtime Environment (JRE) for Windows. Oracle's Java
   Runtime Environment includes support for Java Web Start, a code module
   that will allow you to launch the Ganymede client directly from your
   choice of web browser.

   In order to user Java Web Start, you'll need a web server on your network
   that can serve the clients to your network. We typically run a limited web
   server on the same system that we run the Ganymede server, but you don't
   have to.

   We don't provide any files for launching the Ganymede client from the Mac,
   Windows, or Linux GUI environments, but Java Web Start will offer to
   create desktop icons to run the Ganymede client the first time your users
   run Ganymede from the web.

   +------------------------------------------------------------------------+
   |2. Configuring and Building the Distribution for Your Site              |
   +------------------------------------------------------------------------+

   The Ganymede 2.0 distribution comes without any code precompiled for you.
   In order to get everything compiled and ready for you to install, you will
   need to run the configure script in the distribution directory. The
   configure script is a custom-written Bourne shell script which searches
   around on your system to find Perl, Java, and the Apache Ant build tool,
   and then uses that information to bootstrap the rest of the configuration
   process.

   One of the first things configure will do is to build the Ganymede
   software for you, and create the jar files that you will use to deploy
   Ganymede. When configure compiles Ganymede for you, it will create SSL key
   and certificate material that is unique to your installation. The SSL key
   is placed into the server's ganymedeServer.jar file, and the matching
   certificate material is placed into the client's ganymede.jar and the
   admin console's ganymedeAdmin.jar files. In this way, your Ganymede client
   and admin console will be tied to your Ganymede server. By generating
   unique keys and certificates for each installation, you can be assured
   that the clients you distribute are talking to your Ganymede server.

   After building the Ganymede software, configure 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.

   +------------------------------------------------------------------------+
   |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 / IP address that the Ganymede server will run on?

           This information is used to configure the RMI system in the server
           and in 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 or address for
           the server that will resolve to an i.p. address that is accessible
           by your clients.

           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 Ganymede server use for its internal RMI registry?

           The RMI registry is a network lookup service that is used to
           initialize communications between the Ganymede clients and the
           Ganymede server. By default, port number 1099 is used for RMI
           registration. 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 port should the Ganymede server use to publish its RMI objects?

           The answer to this question will control what TCP port number the
           Ganymede server uses to listen for communications from clients
           once the clients have logged in. By default, communications to
           this port will be SSL encrypted.

   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 you don't want the Ganymede server
           ever to send email, you can leave this blank. Otherwise you should
           enter the DNS name or IP address of a mail server that will accept
           unauthenticated SMTP mail from the Ganymede server.

   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. Note that you will be able to create
           additional admin accounts with superuser privileges later if you
           like, but you need to have this initial, generic superuser account
           to bootstrap the system.

   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 is an unprivileged (non-admin end user
           equivalent) user that is granted the privilege to login to the
           Ganymede admin console and monitor the server's performance and
           activity logging, without being able to stop the server, edit the
           schema, or trigger server tasks.

   What password do you want the monitor account to have?

           The password for the monitor account.

   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 binary ganymede.db file, which contains all data objects and
       schema definitions held by the Ganymede server.
     * A running binary 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 human-readable and Ganymede-parseable 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.

   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.

   The Ganymede 2.0 runServer script takes care of detaching the Ganymede
   server from the console and automatically captures the server's stdout and
   stderr streams to the server.log file in the server installation
   directory.

   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 pre-configured with various options to run the
   Ganymede server smoothly on your system. If you look at runServer,
   however, you will see that there are a number of ways you can edit the
   runServer script to tweak the Ganymede server's behavior.

   Of particular interest in this regard are the -resetadmin and the -logrmi
   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 at least once,
   however.

   If the -logrmi parameter is used, the Ganymede server will log all network
   calls made by clients to a file titled debug.log.. 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 -logrmi parameter as you find it. The
   installServer script will install the runServer script with -logrmi
   enabled. If you want to have the RMI log placed somewhere else, you can
   use logrmi=filename rather than accepting the default RMI log file that
   -logrmi will generate for you.

   While the server is running, you should see one Java process running, that
   being the Ganymede server. All builds and other background activity are
   done with threads in this single process.

   When you want to shut the server down, you can send the running Java
   process a QUIT signal directly with the kill command on Unix-type systems,
   or you can 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.

   Whichever you choose, the server will kick any active users off the
   system, consolidate its database to disk, wait for any running builder
   tasks to complete, and then cleanly shut down. The Ganymede server is
   designed to recover smoothly on restart if it is forcibly killed or if the
   system crashes or is rebooted at any point during its execution, but if
   the server is not shut down cleanly, it might spend a bit of time
   consolidating data from its journal when it starts up again.

   +------------------------------------------------------------------------+
   |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 2.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 should 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 Java 6 or better.

   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 client. 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 files and the 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 like Java Web Start 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 Java 6 or better, 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 that supports Java 6 but which doesn't have a JNLP launcher
   available, 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, JNLP 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?

           The answer to 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 that the Ganymede server is placing its internal
           rmiregistry on. 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.

   With Java RMI-using applets, it is typically necessary to download the
   applets from a web server running on the same machine as the RMI server,
   so that the default restrictions on an unprivileged applet suffice to
   allow a network connection to be made back to the RMI server. The Ganymede
   2.0 applets are signed, however, so you are not required to run a web
   server on the same machine as your Ganymede server, as you were for the
   Ganymede 1.0 series. Running a web server on your Ganymede server may make
   it easier to redeploy the client jar files and etc., if you need to
   upgrade things later, though.

   Wherever you decided to serve the Ganymede clients from, you'll probably
   want to set up an appropriate path or alias. If you are using Apache, you
   might set up an alias in your httpd.conf file that maps a URL path like
   "/ganymede" to your web client directory. Whatever directory you are
   serving Ganymede files from 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 that. 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,
   either with support for running Java 1.6 applets directly, or for passing
   a JNLP file to Java Web Start.

   IMPORTANT NOTE: whenever you run applets from the launch page using the
   'Native' mode, 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.

   In general, we recommend the 'Java Web Start' launch method above all
   others, but you do need to do a bit more configuration work to support
   this option.

   +------------------------------------------------------------------------+
   |9. Configure your web server to support Java Web Start                  |
   +------------------------------------------------------------------------+

   Ganymede supports the use of Java Web Start (see
   http://en.wikipedia.org/wiki/Java_Web_Start) to handle launching the
   Ganymede client and admin console. With Java Web Start, your users should
   be able to run the Ganymede client applets on their Windows, Mac, or Linux
   desktops without needing to bother with a web browser.

   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.

   These days, all web servers you are likely to use should know the
   appropriate mime type for JNLP files, but if you have problems launching
   the clients, make sure that your web server environment knows to assign
   .jnlp files the application/x-java-jnlp-file MIME type.

   In addition to the server-side configuration, your users' web browsers
   must be configured to run the JNLP launcher when a resource of MIME type
   application/x-java-jnlp-file is downloaded. The Java Web Start package
   should take care of that automatically on Windows and Mac OS X, but on a
   Linux or FreeBSD system, your users may have to do some manual
   configuration.

   If you don't configure your server and your users' clients for the use of
   JNLP, 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.

   --------------------------------------------------------------------------

    Jonathan Abbey