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.