Return to General UNIX Home Page.

Using Xvfb with Oracle9iAS

by Jeff Hunter, Sr. Database Administrator


This section is intended for anyone developing servlets on UNIX that call Java's AWT classes. It explains how to resolve the X DISPLAY error with Apache JServ, when executing servlets that manipulate AWT classes.

You have a servlet that runs fine on Windows, but fails to run on a Unix server. Typically, if you call the servlet on a default iAS configuration on Unix, the following errors will be logged in the JServ log file:

[21/12/2000 18:04:48:217] (EMERGENCY) Error initializing protocols
[21/12/2000 18:07:48:939 CET] init
[21/12/2000 18:07:51:494] (ERROR) ajp12: Servlet Error: java.lang.InternalError:
 Can't connect to X11 window server using ':0.0' as the value of the DISPLAY
 variable.: Can't connect to X11 window server using ':0.0' as the value of the
 DISPLAY variable.
[21/12/2000 18:07:51:495] (ERROR) an error returned handling request via
 protocol "ajpv12"
[21/12/2000 18:07:51:508 CET] java.lang.InternalError: Can't connect to X11
        window server using ':0.0' as the value of the DISPLAY variable.
        at org.apache.jserv.JServConnection.processRequest
        (, Compiled Code)
        (, Compiled Code)
Why do we get the error on Unix? This error happens when your servlet does some off-screen graphics to, for instance, generate a GIF file that will be displayed on the client's browser. There is no problem to run this servlet on Windows. The point is that on Unix, the AWT calls still require X-window connections to work. The reason for the error is that X11 has security mechanisms, which allow access to the X server to be restricted to certain users, as well as to certain machines. The most common causes of this error are that the user running Apache/JServ does not have access to the X server, or that there is no X server running at all.

The quick-and-dirty way to solve the problem is to have an X session open on the server's console, and to allow access to the X server to any X client running on the server. The "xhost" tool can be used to grant access to a particular machine:

# xhost +localhost
will allow any X client, directly running on the server, to access the X server. Once access to the X server has been granted to Apache Jserv, you will have to restart Apache for the changes to take effect. This command can be used for testing purposes. However, disabling machine-based access control is a security risk, and should be avoided in deployment environments.

This solution only works if you have a graphical console plugged on your server. If this were not the case, you would have to use an X server running on a remote machine (and change the DISPLAY setting in your or use the solution described below.

The alternative solution is to use Xvfb. Xvfb is an X server that can run on machines with no display hardware and no physical input devices. It emulates a dumb frame buffer using virtual memory. Xvfb can be started automatically at system boot (e.g. by adding a script to the /sbin/rc3.d directory on Tru64 Unix) To startup Xvfb, simply call:

/usr/bin/X11/Xvfb :1 -screen 0 1600x1200x32
The server will listen for connections as server number 1, and screen number 0 will have a resolution of 1600x1200 with a depth of 32. To verify that the server is running correctly, you can try to set your DISPLAY to ":1.0" in your environment, and call xclock. The xclock will not be displayed on your screen. If no error message is displayed, it means that Xvfb is working fine.

Once the server is started, you will have to tell Apache/JServ to use the Xvfb server, instead of the normal X server. This can be achieved by adding (or changing) the following entry in $ORACLE_HOME/Apache/Jserv/etc/

Restart Apache, and the servlet should run fine.


In Oracle9iAS (as well as many other products rendering graphics within servlets) there are three products that need the DISPLAY variable set.

Oracle Reports Multi-Tier Server

For Oracle Reports Multi-Tier Server you set the DISPLAY variable in the script $ORACLE_HOME/6iserver/reports60_server, e.g.:

Oracle Portal and Oracle Discoverer Viewer

For Oracle Portal and Oracle Discoverer Viewer, you set the DISPLAY variable in, e.g.:

The second requirement is that the DISPLAY is actually available, in other words, the machine at IP address must be logged on with an X session towards the server - or that the machine at IP address is actually the server console itself. It can be hard to accept that you need to have a logged on session somewhere to serve as a DISPLAY for Reports, Discoverer Viewer and Portal. Some servers don't even have a graphic adapter, so this is where you should install Xvfb.

Last modified on: Saturday, 18-Sep-2010 18:21:06 EDT
Page Count: 20664