JavaServer for Debian -------------------------------------------------------------------------------- CONFIGURATION Some options described below can be configured when javaserver is installed. These options can be reconfigured with this command: dpkg-reconfigure --default-priority javaserver Note: if you wish to reconfigure *all* options regardless of your default priority setting, then do not specify "--default-priority". * /etc/init.d/javaserver The JavaServer backend is started via this init script. This init script reads from the following files and directories for configuration options. * /etc/defaults/javaserver The init script reads configuration values from this file for 0. the directory to run JavaServer under (default "/usr/share/javaserver/empty/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z") 1. the user to run JavaServer as (default "javaserv") 2. the group to run JavaServer under (default "javaserv") 3. the umask to run JavaServer under (default 002) 4. the port to run JavaServer on (default 2000) 5. the X Window System DISPLAY variable (default empty) * /etc/javaserver/classpath.d If you need additional CLASSPATHs or JAR files to be searched, you can specify them, one per line, in one or more files in this directory. The "run-parts" program will be used to read in these files and each line of these files will be added to the CLASSPATH environment variable before the JavaServer backend is started. For example, to use JavaServer with Apache FOP you might set up a file /etc/javaserver/classpath.d/apache-fop with the following contents: /usr/share/java/fop.jar /usr/share/java/xalan2.jar /usr/share/java/xercesImpl.jar /usr/share/java/xmlParserAPIs.jar /usr/share/java/logkit.jar /usr/share/java/avalon-framework.jar /usr/share/java/batik.jar /usr/share/java/jimi-1.0.jar * /etc/javaserver/java-opts.d If you need additional Java options defined, you can specify them in one or more files in this directory. You may place them on separate lines if you wish--they will automatically be concatenated and separated by spaces. The "run-parts" program will be used to read in these files and each line will be added to the JAVA_OPTS environment variable, which is then inserted into the Java command line by /usr/sbin/javaserver. Note that if the DISPLAY variable is empty, then the Java option "-Djava.awt.headless=true" will be added to JAVA_OPTS automatically. * /etc/javaserver/authfile The first line of this file is a shared secret for the JavaServer. This secret is used for authentication. Any frontend that connects to the JavaServer backend must supply the same shared secret before it will be allowed to invoke any Java classes. This file should only be readable by the JavaServer, that is, it should be owned by the user and group that JavaServer runs as and its permissions should allow only the user to read it, for example: ls -l /etc/javaserver/authfile -rw------- 1 javaserv javaserv 1 Oct 3 11:49 authfile When JavaServer is configured or re-configured in Debian, the owner and group of this file will be updated automatically according to your preferences, but the permissions will not change. This allows you to add group read permission at your discretion if another process needs access to it (your web server for example). * /etc/javaserver/log4j.conf Logging for JavaServer is provided through the log4j facility, which is configured in this file. By default, no logging is performed. Sample entries are provided for logging to a file or to the syslog. If you prefer to have your log4j configuration defined elsewhere, then edit /etc/javaserver/java-opts/javaserver and specify the location. To use the syslog appender it is necessary that the syslog daemon (syslogd) be started with the "-r" option so that it will listen on the network (which is how SyslogAppender talks to syslogd). On Debian with SysV-style init, you can set this option in /etc/init.d/sysklogd. Please be aware of the security issues related to providing syslog service remotely with the "-r" option (e.g., denial-of-service). For more information refer to the manual page for syslogd. -------------------------------------------------------------------------------- SUGGESTIONS If the Java application that you are invoking through JavaServer creates output files, then they will be owned by the javaserv user and the javaserv group. If you need to manipulate these files (rename or delete them), then consider adding your user id to the javaserv group. For example, if you are invoking JavaServer from a web application running under the Apache user www-data, you can add www-data to the javaserv group with this command (as root): adduser www-data javaserv You can then create a custom directory with a group of javaserv and direct the Java application to create files in that custom directory. For example, create a custom directory like this: mkdir /tmp/javaserver chown www-data:javaserv /tmp/javaserver chmod 770 /tmp/javaserver Then direct the Java application to create its files in /tmp/javaserver. Note that there is no way to change the current directory for Java applications invoked through JavaServer. Although daemons are usually started in the root directory, JavaServer is started by default under an empty directory several levels deep, /usr/share/javaserver/empty/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z, so that a Java application will not accidentally read some file from the root directory thinking it was started in a current directory somewhere else. A specific case for this issue is Apache FOP, which tries to read relative-defined external-graphics first from the current directory and second from the baseDir. It is therefore necessary to start JavaServer in an empty directory so that Apache FOP does not pull in some random external-graphic from the wrong directory when it should be using the baseDir. The empty directory is placed several directory levels down to help prevent problems with a relative-defined external-graphic starting with one or more "../". -------------------------------------------------------------------------------- DEBUGGING The JavaServer application does not automatically put itself into the background as a daemon, so the "--background" option of "start-stop-daemon" must be used in the init script "/etc/init.d/javaserver". Unfortunately, this option does not allow JavaServer to display any error messages. If you find that JavaServer is not starting and you don't know why, here are some suggestions for debugging: 1. Change the logging line in /etc/javaserver/log4j.conf to: log4j.rootCategory=DEBUG, file This will tell JavaServer to write debugging information to a file, by default /tmp/javaserver.log. 2. Remove the "--background" option from START_OPTS in /etc/init.d/javaserver and run it manually to see any error messages: invoke-rc.d javaserver start 3. Also add the "--debug-wrapper" option to DAEMON_OPTS in /etc/init.d/javaserver and run it manually to see CLASSPATH and JAVA_OPTS: invoke-rc.d javaserver start -------------------------------------------------------------------------------- REFERENCES http://sourceforge.net/projects/javaserver/ http://search.cpan.org/~metzzo/Java-4.7/Java.pm http://logging.apache.org/log4j/docs/ http://www.vipan.com/htdocs/log4jhelp.html -------------------------------------------------------------------------------- -- Ken Neighbors , Thu Dec 8 15:05:18 2005