Contents:
IntroductionThis article is intended for Sun system administrators and Java servlet developers. Reader should know what the X Windows system is and should be able to understand shell scripts in /etc/rc*.d and /etc/init.d. Here's the scenario: you've got a great servlet that generates JPEG images, and it works fine on the developer's desktop system. Now you must deploy it on a server that looks nothing like the developer's desktop: no keyboard, mouse, or screen, maybe not even a graphics adapter. You've heard that Java platform graphics depend on the X Window system -- what do you do now? You can set up your server system with the Java 2 Platform Standard Edition (J2SE) SDK and the X Window system. Read on to configure the Solaris 7, 8, or 9 OE to use the J2SE SDK v1.2.2, v1.3, or v1.4. See the References section for information on programming servlets to create images, or on installing a servlet engine like Tomcat. The latest versions of J2SE SDK and Solaris OE can make the job very easy. If you're using J2SE v1.4, you don't even need an X server, while the Solaris 9 OE provides an X server (Xvfb) that doesn't need a graphics adapter. If you're using J2SE v1.3.x or v1.2.2, your system will need an X server. The startup of the X server is designed for desktop systems, and it doesn't work well on servers. This article provides an easier startup method for X on server systems using /etc/rc*.d scripts. If you want to skip to setup, jump to the section called "What Should You Run?" and the decision tree that follows it. Servlets and GraphicsYou can use Java servlets to create images in JPEG or PNG (portable network graphics) formats and serve them out in web pages. While you see server-side graphics everyday -- images served from web servers -- servlets can generate or modify images using Java platform graphics APIs. Servlets can draw diagrams, charts, and graphs; label maps and photographs; add watermarks and steganography (hidden messages, not drawings of dinosaurs); and render 3D models -- everything that desktop Java platform-based applications can draw. On the Solaris OE, Java platform graphics have been dependent upon the presence of an X server and hardware graphics adapter. Without an X server, Java platform applications could not use AWT, Java 2D API, Java 3D API, the Java Advanced Imaging (JAI) API, or other graphics APIs. Recent changes in the Solaris OE and in J2SE v1.4 provide easier ways to configure Sun servers for Java platform graphics. J2SE v1.4 -- Java Platform Graphics Without XThe original Java platform graphics API was written to use peer components from a native window system: on Solaris, the peers are provided by the X Window System. In J2SE SDK v1.4, a command-line option can remove the need for the X Window System. This feature, called headless support, is discussed in AWT Enhancements in the Java 2 SDK, v1.4. Headless operation doesn't allow use of GUI classes such as Java Foundation Classes (Swing), but does allow the use of graphics rendering APIs such as Java2D, Java3D, or JAI.
The command-line option is: For more information, see the section called Setting Up Java Platform for Headless Operation Without an X Server. X ServersAn X server implements the X Windows System. If you're using J2SE v1.3.x or earlier, you need an X server to use Java platform graphics APIs. The Solaris OE comes with several variants of the X server, but for servlets, two are important:
Because an X server handles both graphical display and user input, it uses software drivers for the graphics adapter, keyboard, and mouse. Xsun requires a hardware graphics adapter, and it normally requires a mouse and keyboard -- something that a reasonable system manager does not want on a server system. "Null keyboard and mouse drivers" are provided that eliminate the need for keyboard and mouse. The null drivers are available as patches to the Solaris 8 OE, and they are included with the Solaris 9 OE. The minimum patch revisions for the Solaris 8 OE (SPARC® Platform Edition) are 108652-51 and 112663-01. The null software drivers are not available for the Solaris 7 OE. See the Why use Xsun? It uses accelerated graphics adapters to allow applications using the Java 3D API or other APIs based on OpenGL® to run much faster. The adapters available as of this writing are: Sun Creator3D, Sun Elite3D, Sun Expert3D, Sun Expert3D-Lite, Sun XVR-500, and Sun XVR-1000. The graphics adapters implement some OpenGL graphics operations in the hardware. In contrast to Xsun, Xvfb does not need graphics or I/O hardware -- no keyboard or mouse, and it uses system RAM instead of a graphics adapter. Xvfb is great if you're not using Java 3D or another OpenGL-based API. Solaris 9 OE is the first Solaris OE to include Xvfb, but since Xvfb is part of the freely available X source distribution, anyone can obtain and compile Xvfb for earlier versions of the Solaris OE. If you build it, you are also responsible for support. The References section includes some sites with binaries of Xvfb already built for Solaris OE, but for the greatest safety and security, you should build your own executable of Xvfb from X.org. In normal operation, Xsun requires a user to log in to the console. The X server runs while the user is logged in. In contrast to desktop systems, a server should always be ready to work, even when no one is logged in. The server must come up after a reboot ready to do its job. Here I describe how to set up the system so that the X server is always running. I'll cover how to control access to the X server, so that only the processes that are supposed to use graphics can. The X server must run as the same user that runs your servlet engine. Select or create the user account when you install and configure your servlet engine, whether it is a standalone servlet engine such as Tomcat, a web server such as Sun Java System Web Server, or an application server such as IBM WebSphere Application Server or BEA WebLogic Server. In the scripts, the default user is named tomcat, on the assumption that you create a user named tomcat to run the Tomcat servlet engine. Running X Servers
Normally, the dtlogin program starts the X server when a user logs in, but that's no good for a system that runs 24 hours a day, and reboots automatically. The scripts
The X server is normally started by the Common Desktop Environment (CDE) dtlogin program. X provides other mechanisms: xdm and xinit are two other programs that spawn X servers. These are all intended for running X servers to be used by interactive clients. These mechanisms have shortcomings when used to start X servers for use by Java servlets. Here I present /etc/rc*.d startup scripts that run Xsun and Xvfb:
The scripts reside in /etc/init.d. The
#!/sbin/sh
#
# Copyright (c) 1997-2002 by Sun Microsystems, Inc.
# All rights reserved.
#
# xsun.server - start/stop Xsun X server
# 20 September 2002
# CONFIGURE THESE OPTIONS FOR YOUR INSTALLATION
# change this to avoid conflict with existing X servers
DISPLAY_NUMBER=:2
# allow another device to be specified, e.g. vfb or /dev/fb1
DISPLAY_DEVICE="/dev/fb"
# Avoid running X server as root user
# For Java3D servlets, the same user must
# run the X server and the servlet engine.
RUN_AS_USER=tomcat
# END CONFIGURATION
# determine numeric user id from user name
RUN_AS_UID=`/usr/xpg4/bin/id -u $RUN_AS_USER`
# begin X server options
# this script is intended for graphics cards that provide at
# 24-bit (TrueColor) support
# for 8-bit cards, delete "defdepth 24"
X_OPTIONS="-clients 1024 -nobanner -dev $DISPLAY_DEVICE defdepth 24"
# add for Solaris 8 and later
# null keyboard and mouse drivers
# Solaris 8 requires patches 108652-51 112663-01 or later
# Solaris 9 required no patches
NULL_IO_DRIVERS="+nmouse +nkeyboard"
# add for Solaris 9
# restrict X server connections to non-TCP (local only)
NO_TCP="-nolisten tcp"
# end X server options
if [ ! -d /usr/openwin/bin ] ; then
echo Cannot find /usr/openwin/bin/Xsun
echo Exiting...
exit 1
fi
# turn version number from 5.x into x,
# for example 5.8 into 8
SOLARIS_VERSION=`/bin/uname -r | sed -e 's/^5\.//'`
# add in Xsun options based on Solaris version
if [ $SOLARIS_VERSION -ge 8 ]; then
X_OPTIONS="$NULL_IO_DRIVERS $X_OPTIONS"
elif [ $SOLARIS_VERSION -ge 9 ]; then
X_OPTIONS="$NO_TCP $X_OPTIONS"
fi
case "$1" in
'start')
# only real devices need this section
if [ -f $DISPLAY_DEVICE ] ; then
# set the screen's resolution
/usr/sbin/fbconfig -dev $DISPLAY_DEVICE nocheck \
-res 1280x1024x60 2> /dev/null
# prevent ttymon (login) process from changing ownership
# of display devices by commenting out /dev/fbs
# This will comment out the line only once.
# don't change the indenting of the line: EOF
ed logindevperm <<EOF >>/dev/null
/^[ ]*[^#].*\/dev\/fb/s/^/# for \/etc\/init.d\/xsun.server # /
w
q
EOF
# set ownership of the display device
# to match that of the servlet engine
# this is required for Java3D servlets
/usr/bin/chown $RUN_AS_USER $DISPLAY_DEVICE
fi
echo Starting Xsun as $RUN_AS_USER user for display $DISPLAY_NUMBER
# run as non-root user
# don't change the indenting of the line: EOF
su $RUN_AS_USER <<EOF
/usr/openwin/bin/Xsun $DISPLAY_NUMBER $X_OPTIONS &
EOF
;;
'stop')
echo "Stopping Xsun for display $DISPLAY_NUMBER ..."
/usr/bin/pkill -x -u $RUN_AS_UID "(Xsun)"
;;
'status')
# use /usr/ucb/ps to see the entire command line
/usr/ucb/ps axwwwwww | egrep "Xsun|^ *PID" | grep -v grep
;;
*)
echo "Usage: $0 { start | stop | status}"
exit 1
;;
esac
exit 0
Security IssuesSeveral security issues affect X server, including:
A general rule of system security is to avoid running processes as the root user, and to avoid assigning set user ID and set group ID permissions to programs. The
Both Xvfb and Xsun will normally prevent access by users on other systems, and they will allow local access only to the processes run by the user who is running the X server. It is important that you configure the
Controlling access to the display is part of system security. Dtlogin and the login process (ttymon) normally control access to the display, but with dtlogin disabled, What Should You Run?What method should you use to run Java platform graphics? The answers to these questions will determine how to configure your system:
The Decision Tree Figures 1 and 2 provide decision trees. If your application uses the Java3D API, use the decision tree in Figure 2; otherwise, use Figure 1.
Figure 1: Servlets Without Java3D or OpenGL-Based API
Figure 2: Servlets With Java3D or Other OpenGL-Based API The options for server-side Java platform graphics, in increasing order of difficulty, are as follows. Do you use Java 3D or any OpenGL-based API?
If not, can you use J2SE v1.4? If not, can you use the Solaris 9 OE?
If not, can you use a graphics adapter?
Can you use the Solaris 8 OE? If not: If all else fails: To recap: an application using Java 3D requires a system running Xsun server on an accelerated graphics adapter. Java 3D on Solaris OE requires an OpenGL-enabled card such as Sun XVR-500 or Sun XVR-1000. Use the most recent OpenGL release, as it includes significant performance improvements. At the time of this writing, OpenGL 1.2.3 is the latest version available from Sun`s OpenGL site. ProceduresSetting Up Tomcat or Other Servlet Engine to Use X Display Variable
Set the Setting Up Java Platform for Headless Operation Without an X Server
This works only for J2SE v1.4 and later. Add the option
For Tomcat 4.0, add Setting Up Xvfb (Supported) on Solaris 9 OE
In a local directory on the system, save copies of the
# CONFIGURE THESE OPTIONS FOR YOUR INSTALLATION # change this to avoid conflict with existing X servers DISPLAY_NUMBER=:1 Ignore these lines: # NOTE: Solaris 8 and earlier: set the directory # for the user-supplied copy of Xvfb XVFB_DIR=/usr/X11R6/bin Change the user name to match the one that runs your servlet engine: # Avoid running X server as root user # For Java3D servlets, the same user must # run the X server and the servlet engine. RUN_AS_USER=tomcatds # END CONFIGURATION Once you've configured the xvfb.server script, you can test the Xvfb server. As root: # ./xvfb.server start Starting Xvfb as tomcat user for display :1 You can see it running: # ./xvfb.server status PID TT S TIME COMMAND 15467 ? S 0:02 /usr/openwin/bin/Xvfb :1 -screen 0 1280x1024x8 -fbdir /tmp And stop it: # ./xvfb.server stop Stopping Xvfb for display :1 ...
Once you're confident the server is working correctly, run /bin/ln -s /etc/init.d/xvfb.server /etc/rc0.d/K09xvfb.server /bin/ln -s /etc/init.d/xvfb.server /etc/rc1.d/K09xvfb.server /bin/ln -s /etc/init.d/xvfb.server /etc/rcS.d/K09xvfb.server /bin/ln -s /etc/init.d/xvfb.server /etc/rc2.d/S98xvfb.server You can now stop and restart the server from /etc/init.d/xvfb.server. If you can, reboot the system now, and see that Xvfb starts after the reboot. Setting Up Xsun With Null Keyboard and Mouse Drivers Install the graphics adapter in your server. For Java 3D use an accelerated graphics adapter such as Sun XVR-500 or Sun XVR-1000. Install any required packages such as the latest version of OpenGL. Your system cannot use the graphical head and adapter as its console. Make sure you have set up a serial console or Ethernet console before continuing. Connect to your system via telnet or over the non-graphical system console to carry out these instructions. Copy the following two scripts:
Copy these two scripts into a temporary directory on your system.
Edit the following section of # CONFIGURE THESE OPTIONS FOR YOUR INSTALLATION # allow another device to be specified, e.g. /dev/fb1 DISPLAY_DEVICE="/dev/fb" DISPLAY_NUMBER=:2 RUN_AS_USER=tomcat # END CONFIGURATION
As the root user, run the /bin/cp xsun.server /etc/init.d /bin/chmod 0544 /etc/init.d/xsun.server # create links for the various run levels /bin/ln -s /etc/init.d/xsun.server /etc/rc1.d/K09xsun.server /bin/ln -s /etc/init.d/xsun.server /etc/rc0.d/K09xsun.server /bin/ln -s /etc/init.d/xsun.server /etc/rcS.d/K09xsun.server /bin/ln -s /etc/init.d/xsun.server /etc/rc2.d/S99xsun.server # terminate DtLogin /etc/init.d/dtlogin stop # prevent DtLogin startup /bin/mv /etc/rc2.d/S99dtlogin /etc/rc2.d/.S99dtlogin
Now you can run You can now test your configuration change by running the script as the root user: # cd /etc/init.d # ./xsun.server start Starting Xsun as tomcat user for display :2 You can see it running: # ./xsun.server status PID TT S TIME COMMAND 19665 ? S 0:03 /usr/openwin/bin/Xsun :2 -clients 1024 -nobanner -dev $DISPLAY_DEVICE defdepth 24 +nmouse +nkeyboard -nolisten tcp And stop it: # ./xsun.server stop Stopping Xsun for display :1 .. Setting Up Xsun With Actual Keyboard and Mouse (Pre-Solaris 8) Attach a keyboard and mouse to the system, then follow the directions in Setting Up Xsun With Null Keyboard and Mouse Drivers. Setting Up Xvfb (Unsupported) for Solaris 8 and Earlier A search on Google shows several prebuilt Xvfb binaries for the Solaris OE. You can also obtain and compile the software yourself. I do not endorse any particular Xvfb binary for Solaris OE -- make sure you're complying with your site's policy on downloaded binaries. You may need to download the X sources and compile Xvfb yourself.
Obtain and install a copy of Xvfb. You'll probably put it in /usr/local/bin or /usr/X11R6/bin. The Copy the xvfb script from this article into a temporary directory. You'll need to change X_DIR to the directory containing Xvfb. # CONFIGURE THESE OPTIONS FOR YOUR INSTALLATION DISPLAY_NUMBER=:1 X_DIR=/usr/X11R6/bin # pre-Solaris 9: wherever Xvfb lives RUN_AS_USER=tomcat # END CONFIGURATION Now continue in the "Setting Up Xvfb (Supported) on Solaris 9 OE" section with the step of testing the xvfb.server. (See: "Once you've configured the xvfb.server script, you can test the Xvfb server.") Testing and Troubleshooting
Once the X server is running, you can use your servlet application to confirm that Java platform graphics are working. If you have trouble, check that the X server is operating properly. As the user running the X display (tomcat by default) follow these steps, matching the value of % /usr/openwin/bin/xclock -display :2 &
You can use % /usr/X11R6/bin/xwd -display :2 -root -out /tmp/xclock.xwd
Then copy the image file over to another system and display it to check that graphics are working, using % /usr/openwin/bin/xwud -in /tmp/xclock.xwd
If xclock won't run, then the server is probably not running. Make sure that Other Issues and Future WorkMultiple instances of the servlet engine may allow you to support more clients from a single server system. This can work around scaling problems with the Java 2 runtime environment. You can run multiple X servers on a single system, and run separate instances of the servlet engine, with each instance using a different value for its DISPLAY environment variable. Setting up the necessary /etc/init.d and /etc/rc*.d scripts is left as an exercise for the reader.
As of this writing, the Solaris 9 OE's version of Xvfb cannot support 24-bit color operation. If you need 24-bit deep graphics, continue to use the X11 distribution's version of Xvfb. A future update of the Solaris 9 OE might include a special graphics pseudo device named vfb, which would allow Xsun to perform the same role that Xvfb does today. The ConclusionNow you've followed the decision tree and picked the right X server for your installation. Good luck and happy servlets! ReferencesGraphics Programming
Servlet Programming With Images
Java Advanced Imaging (JAI) and JAI Supplementary API Writing an Image From Memory J2SE v1.4 Image I/O API Java Platform Headless Graphics
Java Advanced Imaging (JAI) and JAI Supplementary API
Servlet Engines
OpenGL
Documentation You can search on docs.sun.com (Sun Product Documentation) for the following:
Also refer to the man pages for The XFree86 Project: Patches
Appendix A: AttachmentsThe files included are:
Appendix B: List of FilesThe files to be installed are: /etc/init.d/xsun.server /etc/init.d/xvfb.server Symbolic links to be created are: /etc/rc0.d/K09xsun.server /etc/rc0.d/K09xsun.server /etc/rcS.d/K09xsun.server /etc/rc2.d/S99xsun.server /etc/rc0.d/K09xvfb.server /etc/rc1.d/K09xvfb.server /etc/rcS.d/K09xvfb.server /etc/rc2.d/S98xvfb.server File to be moved: /etc/rc2.d/S99dtlogin to /etc/rc2.d/.S99dtlogin File to be edited: /etc/logindevperm AcknowledgmentsThierry Manfe showed me how to run X without dtlogin. Thanks to my colleagues in MDE, Sun SEs, and the Sun X11 group for feedback. About the AuthorTom Gould, an engineer in Sun's Market Development Engineering group, helps ISVs develop applications. He has been a contestant on Jeopardy! November 2002 | |||||||||
 | |
| ||||||||||||
Print-friendly Version
