Ganymede

Ganymede File Glossary
2.0 - 5 April 2013


This page contains descriptions of various significant files that are part of the Ganymede package.

Installation Scripts

configure

configure is the first script that must be run after unpacking the UNIX Ganymede distribution. configure asks a few questions to determine the location of Perl 5.003 or later, Java, and Ant. configure then builds the Ganymede software for you and creates the installServer, installClient, and installWeb scripts used to actually install the server and client software.

installServer

installServer is a Bourne shell script generated by the configure script when the Ganymede distribution is first unpacked and configured. installServer configures and installs the Ganymede server in its own directory, along with all documentation and necessary files.

installServer will ask a number of questions about your environment, including the identity of the machine on which the Ganymede server will be run, the location where you want the Ganymede server installed, and the port number that the server's rmi registry should be run on. Once all questions have been answered, installServer will create an installation directory for the server to be run out of. During this process, installServer creates bin, db, doc, jars, html, and optional schema directories under the installation location, and installs various files into them to support the server's execution.

Many files installed by installServer are customized as they are copied to their destination. This customization is sufficient to be able to run the server immediately from the installation directory.

Once installServer creates the installed server tree, you should probably set the file permissions on the tree to restrict who has access to the server installation, as there will be sensitive data held under the server's installation directory.

installServer only needs to be run once. Once you have generated the server and client installation directories, you can dispose of the original Ganymede distribution directory unless you will want to edit and rebuild the Ganymede sources at some later time.

installClient

installClient is a Bourne shell script generated by the configure script when the Ganymede distribution is first unpacked and configured. installClient configures and installs the Ganymede client and admin console in their own directory, along with all documentation and necessary files.

The directory created by installClient includes a bin directory containing ganymede, ganymedeAdmin, and xmlclient.

installClient only needs to be run once. Once you have generated the server and client installation directories, you can dispose of the original Ganymede distribution directory unless you will want to edit and rebuild the Ganymede sources at some later time.

installWeb

installWeb is a Bourne shell script generated by the configure script when the Ganymede distribution is first unpacked and configured. installWeb configures and installs html and jar files that will allow users to run the Ganymede client and admin console from a web browser.

When installWeb is run, it prompts for the address of your Ganymede server and where you want to install the web resources to. This should be a directory that you have created to hold the Ganymede web files. Once installWeb is finished running, you should be able to publish the target directory with your web server. You can then visit the published directory through the web to use the Ganymede clients in your web browser.

There are two convenient ways to run the Ganymede clients from a Windows web browser. The first is to visit java.sun.com/products/plugin/ and download the latest version of the Java JRE. The JRE for Windows includes the Java plug-in, which is currently the best way to run Ganymede within a web-browser. You should be running at least version 1.2.2 of the JRE, which fixes many problems with earlier versions.

In addition to the Java Plugin, however, you may also want to use the Java Web Start or the OpenJNLP Launcher in order to support your users running the Ganymede clients from the user's desktop. Java Web Start runs on Windows, Linux, and Solaris, while the OpenJNLP Launcher works on the Macintosh and other platforms. Another choice for JNLP services is the JavaURL project.

In order to use the JNLP launch option, your web server will have to be configured to associate the application/x-java-jnlp-file MIME type with the .jnlp extension. See the web server configuration section in the Install Guide for more details.

We have not run the Ganymede clients from within a browser on Solaris.. if anyone has success on this or any other unusual environment, please let us know.

distribclean

distribclean is a Bourne shell script, used to remove all of the scaffolding and unnecessary files created when building the Ganymede distribution. distribclean is run immediately before creating a Ganymede distribution archive, and probably has no practical use if you are not packaging Ganymede for download.

config.sh

config.sh files are generated by the configure and installServer scripts, to customize various build and loader scripts in the source and server trees. Both Bourne shell and Perl scripts consult these files to get file paths and other customized information.

Server Files

ganymede.properties

ganymede.properties is the server's configuration file, located in the top-level directory of the server installation tree. ganymede.properties sets a bunch of file paths used by the server, as well as RMI and password information needed by both the runServer and the stopServer commands.

ganymede.properties may contain schema-specific configuration as well as the basic configuration properties needed by the server.

The ganymede.properties file is commented, and most properties in it should be self-explanatory. The one property that you should be particularly aware of is the ganymede.defaultrootpass property, which holds the server's supergash (root) password. This property is used to set the server's password every time that runServer is run, unless runServer has been edited to remove the "-resetadmin" command line flag. You can remove the ganymede.defaultrootpass property entry if you want to keep the plaintext password out of your file system, but if you do remove ganymede.defaultrootpass, the stopServer command will have to prompt for the server's "root" password in order to log into the server to shut it down.

The Ganymede client installation has its own client.properties file.

ganymede.db

ganymede.db is the server's binary database file, located in the db subdirectory of the Ganymede server directory. ganymede.db contains both the database contents and the database schema definition used by the server. Everything the server knows about its configuration and stored data is held in the ganymede.db file. If you ever upgrade to a new version of Ganymede, you can generally just copy your old ganymede.db file to the new server's db directory to bring your data and configuration forward.

The ganymede.db file is read by the server on start-up. Once loaded, the server never consults the ganymede.db file on disk. Changes made to the database during operation are written to the journal file. Periodically, and on shut-down, the server will consolidate the database by writing out a new copy of ganymede.db, and resetting the journal file. The consolidation logic is written so that if the server is killed at any time during the consolidation, the server will be able to properly recover when restarted.

Manually deleting the ganymede.db file would be a really bad idea, however.

journal

The journal file is located in the db subdirectory of the Ganymede server directory. journal is a binary file which contains a transcript of transactions committed since the server last consolidated the ganymede.db file. If the server is killed and the journal file is deleted, all transactions not consolidated into the ganymede.db file will be forgotten, although the log file will still record the details of the lost changes.

log

The log file is located in the db subdirectory of the Ganymede server directory, and contains a text record of all changes made to the server's database, as well as user and admin login and logout events. The log file is designed to be both human readable and easily parsed, and is actually consulted by the Ganymede server to report history information for database objects.

See the log file format file for details on the log file's structure.

ganymedeServer.jar

The ganymedeServer.jar contains all of the compiled Java code needed by the runServer and stopServer commands. It is located in the jars sub-directory of the Ganymede server installation directory.

custom.jar

The custom.jar contains any custom classes included with the installed schema kit needed by the Ganymede server. It is located in the schema sub-directory of the Ganymede server installation directory.

See the Customization Guide for details on the contents and construction of custom.jar.

debug.log

The debug.log file in the server directory records an on-going trace of all RMI network calls made to the Ganymede server by remote clients. Any server exception that occurs in direct response to a client's network request will be logged to this file. This exception trace information is essential if there is to be any hope of diagnosing many kinds of problems in the server, so you should always be sure that the runServer script is configured to capture this information, even though there may be a performance and disk space penalty from logging everything.

Server Scripts

runServer

runServer is a Perl script, located in the bin directory under the location where you installed the server using the installServer script. runServer runs the Ganymede server for you.

If you look at the runServer script, you will see that it includes a few Perl variables that were customized by the installServer script. These include the location of the java executable, CLASSPATH information, and the location of the ganymede.properties file, which contains the configuration information consulted by the server during its operation.

The runServer script is commented, and may be edited to enable a high level of RMI debug logging and to disable automatic resetting of the supergash password. Consult the runServer script for details.

The runServer script writes the Ganymede server's stderr and stdout logging to the server.log file in the Ganymede server directory.

Notice that it is not necessary to manually background the runServer script.. it forks and runs the Ganymede server in the background.

If you kill the backgrounded Ganymede java process, the Ganymede server will do a clean shutdown, with shutdown notices sent to any logged in users.

You could also kill the server with the admin console's 'Shutdown Ganymede' menu item or the stopServer script.

stopServer

stopServer is a Bourne shell script, located in the server's bin directory, which when run will connect to the server using RMI and order it to shut down. It depends on having access to the ganymede.properties file in order to determine the address of the running server as well as the server's supergash password. If you have removed the supergash password from the ganymede.properties file in order to keep the password secret, stopServer will prompt for the server's supergash password in order to shut down the server.

stopServer uses the admin console's API to shut the server down, and it may take a small amount of time to shut down the server, in order to allow transactions in the process of being committed to complete. When the server goes down, all users logged onto the Ganymede server will receive a message indicating that the server is immediately going down, and that they have been disconnected. Any uncommitted changes made by active users will be lost.

If the stopServer command is run with the '-delay' command line switch, the server will not be shut down immediately, but rather will perform a deferred shutdown. In this case, after the stopServer -delay command is executed, no new users will be allowed to connect to the server, and when all active users are logged out, the server will automatically shut down.

While initially stopServer or the equivalent command sent from the Ganymede admin console was the only way to have the Ganymede server do a clean shutdown, the Ganymede server now implements a SIGQUIT handler, so you can do a clean shutdown with a standard Unix kill command on the Ganymede server process.

If you want to do a delayed shutdown, you'll still need to use stopServer or the admin console to order a delayed shutdown, however.

xmlclient

xmlclient is a Bourne shell script used to do bulk data loading into the Ganymede server. It is configured and installed in the client installation's bin directory by the installClient script as well as in the server installation's bin directory by the installServer script.

See the xmlclient documentation for details on how to use the xmlclient.

See the Ganymede XML Guide for details on the XML file format supported by xmlclient.

logscan.pl

logscan.pl is a Perl script that is used to accelerate log searches on behalf of clients. The Ganymede server uses logscan.pl to quickly scan through the Ganymede log file, filtering out lines in the log file that do not match what the server is looking for.

ganypass.pl

ganypass.pl is a Perl script that uses CGI, xml, and xmlclient to log into the Ganymede server and change a user's password. All attempts to use this form are logged, and email may be sent to the user on either success or failure, depending on the configuration of the Ganymede server.

Client Files

client.properties

client.properties is the client and admin console's configuration file, located in the top-level directory of the client installation tree. The client's client.properties file contains much less information than the server's ganymede.properties file.. mostly just enough information to be able to find the server's RMI address. The client.properties file is commented, and most properties in it should be self-explanatory. The ganymede.rootname property contains the root account name so that the admin console can verify supergash-level permissions. This is more for interface convenience sake on the part of the admin console.. changing this property will not allow the user to gain any privileges through the admin console.

client.properties is used by the ganymede, ganymedeAdmin and xmlclient commands, but not by the .html files used for client web-access. The .html files include the properties held in the client.properties file in the form of applet parameters, and are self-contained.

ganymede.jar

The ganymede.jar contains all of the compiled Java code needed by the ganymede and xmlclient client executables, and for the ganymede client when run from a web browser. It is located in the jars sub-directory of the Ganymede client installation directory, and in the install directory specified by installWeb.

ganymedeAdmin.jar

The ganymedeAdmin.jar contains all of the compiled Java code needed by the ganymedeAdmin client executable, and for the Ganymede admin console when run from a web browser. It is located in the jars sub-directory of the Ganymede client installation directory, and in the install directory specified by installWeb.

Client Scripts

ganymede

ganymede is a Bourne shell script used to run the GUI Ganymede client from a UNIX command prompt. It is configured and installed in the client installation's bin directory by the installClient script.The DISPLAY environment variable must be set to your X display.

The ganymede script uses the client.properties file to locate the Ganymede server's RMI address.

ganymedeAdmin

ganymedeAdmin is a Bourne shell script used to run the GUI admin console from a UNIX command prompt. It is configured and installed in the client installation's bin directory by the installClient script. The DISPLAY environment variable must be set to your X display.

The ganymedeAdmin script uses the client.properties file to locate the Ganymede server's RMI address.

xmlclient

xmlclient is a Bourne shell script used to do bulk data loading into the Ganymede server. It is configured and installed in the client installation's bin directory by the installClient script as well as in the server installation's bin directory by the installServer script.

See the xmlclient documentation for details on how to use the xmlclient.

See the Ganymede XML Guide for details on the XML file format supported by xmlclient.

Web Files

client.jnlp

client.jnlp is an XML file formatted according to the Sun Java Network Launch Protocol Community Standard, that allows the Ganymede client to be launched from a user's web browser or desktop.

The client.jnlp is created, configured, and installed by the installWeb script. Read more about this in the installWeb script's glossary entry, and see the Web Server Configuration section in the Install Guide for more details on the use of JNLP with the Ganymede client.

console.jnlp

console.jnlp is an XML file formatted according to the Sun Java Network Launch Protocol Community Standard, that allows the Ganymede admin console to be launched from a user's web browser or desktop.

The console.jnlp is created, configured, and installed by the installWeb script. Read more about this in the installWeb script's glossary entry, and see the Web Server Configuration section in the Install Guide for more details on the use of JNLP with the Ganymede admin console.


Jonathan Abbey