Multi-Org Elements

The X Server Requirement

Bottom Line: On Unix, Oracle9iAS Release2 requires a running X Server for image generation needs. In addition, the configuration needs to be setup to allow 9iAS access to the X Server. The use of XVFB for headless servers is also discussed.

Hint: Oracle Support Note 181244.1 may contain more recent or more detailed information about using XVFB or VNC with Oracle software. Be sure to consult that document for other helpful information.

On UNIX, graphics support is typically provided by the X Window System, a graphics system which is developed by a consortium of UNIX vendors, currently known as X.Org. The X Window System is a networked graphics system. Graphics requests are made by client applications, known as X clients, to a server process, known as an X server. The X client and X server can be running on the same machine or on different machines. In either case, communication between the X client and server is performed using a network protocol known as the X Protocol.

9iAS uses the standard Java graphics library, AWT, to perform all graphics operations. The current production version of AWT (J2SE v1.3) requires access to an X server. This requirement means that in order to generate images from a 9iAS-based application on UNIX, an X server must be available, and the location of the X server must be communicated to AWT. Fortunately, these requirements will soon disappear. The next version of AWT (J2SE v1.4, currently in beta) removes the X server dependency through a feature known as "headless" Java. In the meantime, setting up X server access is an essential part of 9iAS deployment.

If X server access is not configured correctly, 9iAS can run but cannot generate any new images. If the X server can not be accessed, 9iAS logs an error message to the servlet engine's error log. In addition, the inability to generate images can cause certain components to cease to function normally. 9iAS components which require image generation include:

· Enterprise Manager Web Site

· Oracle Portal

· Oracle Discoverer

· Oracle Reports

· Oracle Delegated Administrative Service (DAS)

· UIX-based applications

· BI Beans-based applications

X Server Configuration Basics

Although the X Window System is a standard component of most UNIX platforms, quite often some configuration work is needed to set up X server access. The X server must be started, AWT must be informed of the location of the X server, and the X server must be configured to allow access to the AWT-based application. Failure to perform any of these steps correctly can result in the error message described above, as well as missing images, or images replaced with alternate content. This section describes how to enable image generation in environments which support the X Window System.

Hardware Requirements

The standard X server software which ships with most UNIX platforms imposes some hardware requirements on the hosting machine. The X server requires access to a hardware frame buffer. Also, a keyboard is required by default (although there may be some way to work around this requirement). In general, if the UNIX box includes a monitor and a keyboard, the X server should run with no problems. However, a frame buffer and keyboard may not be installed in some machines in middle-tier, data-center environments. In this case, the X server can not be started, and alternate solutions, such as using a remote X server, XVFB, or VNC must be explored.

Starting the X Server

The most common way to start the X server process is to log in to the console of the UNIX machine. Most UNIX platforms boot into the X Display Manager, a small authentication application which displays a login screen. Once the user logs in, the X server is started as a process that is owned by the console user. In the typical default configuration, the console user "owns" the X server - no other users are allowed to access the X server. As discussed later, these default settings can be overridden to allow wider access to the X server.

In cases where system administration is performed remotely (for example, by using telnet from a remote machine), the owner of the console may be required to start the X server on behalf of the remote administrator. To determine whether the X server is already running, look for a process name which starts with X. For example, on Solaris, the X server process is called Xsun.

Once the X server is running, it is extremely important to avoid stopping the X server while any client applications are connected. If the X server is stopped, a signal is sent to any connected clients. In response to this notification, AWT causes the virtual machine (VM) to abort.

This problem is exacerbated by the fact that once AWT connects to the X server, the connection is maintained by AWT for the life time of the VM. So, once any image is generated, an X server connection is established and kept alive until the servlet engine is stopped. Since the X Display Manager shuts down the X server when the console user logs out, this means that the administrator must remain logged in to the X server host machine for as long as the application is running. The console can be locked for security reasons (for example, using a tool such as xlock), but the console user must not end the X server session by logging out.

Note: It may be possible to configure the machine hosting the X server to start the X server without requiring a console login. Or alternatively, the XVFB pseudo-X server can be used independently of the X Display Manager. In any case, it is critical to avoid stopping the X server once a connection has been established by AWT.

Setting the DISPLAY Environment Variable

Once the X server is started, the next step in the configuration process is to specify the location of the X server via the DISPLAY environment variable. All X client applications use the information specified by the DISPLAY environment variable to determine how to locate and connect to the X server. The DISPLAY environment variable specifies three pieces of information:

The machine name. This is the name (or IP address) of the machine on which the X server is running. If the machine name is not specified, the local machine is used as the default.

The server number. This number specifies the X server instance to use. In some environments, multiple X servers may be running on a single machine. In most environments, however, only a single X server can be supported. In this case, the server number should be set to 0 (zero).

The screen number. Each X server instance is capable of supporting multiple logical screens. By default, screen 0 (zero) is used.

These three pieces of information are combined into a single value of the following form:

<machine name>:<server number>.<screen number>

When the X server is running on the same machine as the X client, the simplest way to set DISPLAY is to let both the machine name and the screen number default. In this case, the DISPLAY must minimally be set to :0, to indicate that screen zero on server zero on the local machine should be used for all X connections. This is sometimes specified as :0.0, although explicitly specifying the screen number is unnecessary.

Normally, the DISPLAY environment variable can be specified in a login script or shell script. However, in some servlet environments, the DISPLAY environment variable must be specified within servlet engine-specific configuration files. For example, when running OC4J-based applications inside of 9iAS Release 2, the DISPLAY environment variable must be specified in the environment section of the OC4J instance's section of the $ORACLE_HOME/opmn/conf/opmn.xml file.

Hint: besides updating opmn.xml, you can use the following sequence of commands to get the opmn.xml changes to be picked up:

$ORACLE_HOME/dcm/bin/dcmctl updateConfig -v

$ORACLE_HOME/dcm/bin/dcmctl shutdown -force -v

$ORACLE_HOME/dcm/bin/dcmctl start -v

Hint: when starting the EM Web Site, be sure to set the DISPLAY variable in your shell environment.For example, in the bourne shell you can do: DISPLAY=localhost:1 export DISPLAY Hint: you may also need to update the DISPLAY setting in the $ORACLE_HOME/bin/reports.sh file If the DISPLAY environment variable is not explicitly set in the proper servlet engine configuration file, it is likely that attempts to connect to the X server will fail and image generation will be disabled and/or errors will be reported. Hint: With Oracle9iAS Release 2, the error messages indicating invalid X server configuration may be written to a variety of locations. The showLogs interactive log file viewer available at http://technet.oracle.com/products/ias/ias_utilities.html#logviewer might be useful to help navigate thru the log file locations. Likely places to check for OC4J-based error messages are the log files in $ORACLE_HOME/opmn/logs. Another place to check is the $ORACLE_HOME/j2ee/*/application-deployments/*/*/application.log files. Since the X Window System is designed for network-based operation, the X server can be run on a different machine from the X client. This ability can be useful for "headless" middle-tier environments, where some middle-tier machines do not have the necessary hardware to run an X server locally. In this case, the X server can be run on some other machine which can support an X server. The remote X server can be accessed by an X client simply by specifying the machine name via the DISPLAY environment variable. Note, however, that using a single remote X server as the DISPLAY for many machines within a headless middle-tier environment can be somewhat risky. As mentioned above, if the X server is stopped for any reason, any connected processes are aborted. Testing the Connection After the DISPLAY is set, the next step in the configuration process is to verify that the X server can be accessed by an X client. The easiest way to verify X server access is to run one of the many X client applications, such as xterm or xclock, that are shipped with the X Window System. (On Solaris, these tools are located in the /usr/openwin/bin directory.) If the DISPLAY environment variable is set correctly, an application like xterm or xclock should run with no error messages. If the DISPLAY is set to the local machine, the application should become visible on the console. If the DISPLAY is not set, or is set incorrectly, an error message such as "Can't open display: ..." should be printed. If the DISPLAY is set correctly but the client does not have permission to access the X server, a more explicit error message is displayed, for example: Xlib: connection to "..." refused by server Xlib: Client is not authorized to connect to Server Xt error: Can't open display: ... Access control problems can be resolved using one of two X Window System security mechanisms xhost or xauth. Since X server access can be controlled on a per-user basis, when testing X server access from the command line it is important to test using the same user ID that is used to run the servlet engine. Web server and servlet engine processes are often run under a special user ID, such as apache or oracle. Before testing X server access from a servlet engine environment, it is important to verify that the appropriate user does indeed have access to the X server. The easiest way to test this is to log in using the user ID that is used to run the servlet engine and to test X server access from the command line by running one of the standard X client applications. Typically, if the console owner is a different user than the servlet engine process owner, some access control configuration (via xhost or xauth) is necessary, since by default only the console owner has access to the X server. Testing the Connection in a Servlet Environment Once X server access has been verified by running some X client application from the command line, X server access from the servlet engine should be tested. Writing a servlet or Java Server Page (JSP) which tests the X server access is easy, as a single AWT call is sufficient to force AWT to establish the X server connection. The following servlet calls java.awtGraphicsEnvironment.getLocalGraphicsEnvironment(), which forces AWT to connect to the X server: import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; public class TestServlet extends HttpServlet { public void service( HttpServletRequest request, HttpServletResponse response ) throws ServletException, IOException { // This code will force AWT to connect to the X server java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(); // Set the content type response.setContentType("text/html"); // Get the writer PrintWriter out = response.getWriter(); // Send some content out.println("<html><body><h1>Hello, world!</h1></body></html>"); } } The following JSP accomplishes the same result: <% java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(); %> <html> <body> <h1>Hello, world!</h1> </body> </html> Before attempting to test the X server connection from within a servlet engine, be sure that the DISPLAY environment variable is set in the appropriate servlet engine configuration file. If the X server connection is established, getLocalGraphicsEnvironment() returns successfully and a message is sent back to the browser. If the X server connection can not be established, one of several error messages may occur. If the DISPLAY environment variable is not set at all, AWT sometimes reports a NoClassDefFoundError: java.lang.NoClassDefFoundError: sun/awt/X11GraphicsEnvironment at java.lang.Class.forName0(Native Method) at java.lang.Class.forName0(Compiled Code) at java.lang.Class.forName(Compiled Code) at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:63) at TestServlet.service(TestServlet.java:16) Unfortunately, this error message is somewhat misleading. This message does not actually reflect a class loading problem. The error can be avoiding by setting the DISP0in;margin-bottom:5.0pt; margin-left:0in;mso-pagination:none;mso-layout-grid-align:none;text-autospace: none'>Another common error message occurs when the DISPLAY is specified but the specified X server can not be accessed: Can't connect to X11 window server using ':0' as the value of the DISPLAY variable. at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method) at <UNLOADED Method> at java.lang.Class.forName0(Native Method) at java.lang.Class.forName(Class.java:124) at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:63) at TestServlet.service(TestServlet.java:16) If the X server can be accessed using a command line tool such as xterm, but cannot be accessed by the same user when running within a servlet engine, the problem is likely due to xauth configuration problems discussed below. Granting Access with Xhost The X Window System provides two built-in security mechanisms. The xhost tool is used to control machine-level security. The xauth tool is used to control user-level security. For most configurations, using xhost to grant X server access from a specific machine is sufficient. When the X server is first started, access is typically restricted to the local machine - and only to the console user. Other users, such as an administrator that logs on to the local machine (for example, via telnet), or even other user IDs used by the console owner (such as apache or oracle) do not have access to the X server by default. The simplest way to grant access to the X server is to use xhost to grant access to every user on the local machine. For example, if an administrator logs in to the X server console using an administration user ID, but wants to run the servlet engine on the same machine using a different user ID, then all users on the same machine can be granted access with the following command: xhost + <machine name> In the above command, the <machine name> is the name of the local machine which is running both the X server and the servlet engine. After executing this command, all users that are logged into this machine (whether via the console, telnet, remote login, etc...) will have access to the X server. The xhost tool can also be used to grant access to all users on a remote machine. For example, if the servlet engine is running on a machine called mtier and the X server is running on a machine called xserv, the console user on the xserv machine would need to run the following command to grant access to the servlet engine running on mtier: xhost + mtier Xhost can also be used to disable all access control through the command xhost +. Running this command grants access to all users on all machines on the network. However, disabling access control in this way is inherently less secure and as such should be avoiding in favor of per-machine access. Granting Access with Xauth Although xhost + <local machine name> is by far the easiest way to grant X server access, it does grant somewhat wider access than is actually necessary, since xhost grants machine-level access. The xauth tool can be used to grant access to specific users. For example, xauth can be used to grant access to the specific user ID that is used to run the servlet engine, without providing access to all other users on the same machine. The xauth security mechanism uses a secret "cookie" that is used to identify authorized users. When the X server is started, the cookie is determined and is written to an .Xauthority file in the console user's home directory. Only users which know the cookie can access the X server. By default, this means that only the console user can access the X server. Actually, in some circumstances, access may be denied to the console user even if the .Xauthority file contains the current cookie. When running in some servlet engines, the user's .Xauthority file can not always be located, in which case even the X server owner cannot access the X server from within the servlet engine. For example, when running Jserv in automatic mode, access to the X server is denied even to the console user. To avoid this problem, the .Xauthority file must be explicitly identified using the XAUTHORITY environment variable. If access to the X server is denied even though Jserv is run by the console user, adding the following line to jserv.properties should enable access: wrapper.env=XAUTHORITY=~/.Xauthority To grant access to a user other than the X server owner, the xauth tool must be used to create a .Xauthority file for the other user. For example, assuming that the user administrator is logged into the console and the user apache is used to run the servlet engine on the same machine, the following steps can be performed to grant access to apache: As the user administrator, run the xauth tool (xauth). At the xauth> prompt, type list to list all of the cookies. Find the cookie for the local machine. It should look something like: machine name:0 MIT-MAGIC-COOKIE-1 34285439adcas098q2w3098qf3209412 This is the the xuath cookie for the X server running at <machine name>:0. As the user apache, run xauth. At the xauth> prompt, add the cookie with the add command: xauth> add machine name:0 MIT-MAGIC-COOKIE-1 34285439adcas098q2w3098qf3209412 To make sure that the cookie was added, use list to list all cookies. Save the changes and exit the xauth tool by typing exit. As a result of this process, an .Xauthority file should be created in the home directory of the user apache with the current xuath cookie. The apache user should now be able to access the X server. Note: the xauth cookie is typically changed each time the X server is started. As such, this process must be repeated any time the X server is restarted and should probably be automated using UNIX shell scripts. A similar process can be used to grant access to specific users on remote machines. More information about how to grant xuath access to remote users and how to automate this process can be found in the xauth man page and on the Web. Enabling Image Generation with XVFB Not all machines can meet the hardware requirements needed to run an X server. It is not uncommon for middle-tier machines hosted in data centers to lack a frame buffer or a keyboard. In this case, the X server cannot be run locally on each middle-tier machine. Instead, the X server can be run remotely on a machine which does meet the hardware requirements. However, configuring many "headless" machines to share a single remote X server can be a risky configuration, as any problems with the shared X server can affect all machines. An alternative to the remote X server solution is to run a pseudo-X server such as the X Virtual Frame Buffer, or XVFB. Actually, XVFB is an X server. That is, XVFB processes X Window System requests and sends responses using the same network protocol as the standard X server. The main difference between XVFB and the standard X server software is that XVFB use an in-memory virtual frame buffer instead of a hardware frame buffer. As such, XVFB can be run on almost any UNIX machine, including "headless" middle-tier machines which lack a hardware frame buffer and keyboard. Hint: The following link may be useful background for those new to XVFB: http://www.itworld.com/AppDev/1461/UIR000330xvfb/ Hint: The following link may be useful for those administrators worried about security and XVFB: http://searchsecurity.techtarget.com/ateQuestionNResponse/0,289625,sid14_cid461759_tax285454,00.html Note: Another alternative is VNC. More information about VNC can be found at http://www.uk.research.att.com/vnc/ The advantage of running XVFB on each headless middle-tier machine instead of using a single shared X server is that XVFB failures only affect applications running on local machine. Obtaining XVFB XVFB is a standard component of the X Window System which is developed and distributed by X.Org. X.Org distributes the X Window System in source code form to X.Org members, including most UNIX vendors. The UNIX vendors are responsible for building and distributing platform-specific X Window System binaries. These binaries are in turn shipped by the vendors with the platform-specific operating system distributions. However, not all UNIX vendors distribute XVFB binaries. Some UNIX vendors, such as Compaq and various Linux vendors, include XVFB as a standard operating system component. Other UNIX vendors, such as HP, provide an XVFB binary via a corporate Web site. Other UNIX vendors, such as Sun, do not distribute XVFB binaries at all. On platforms where an XVFB binary is not provided by the UNIX vendor, the XVFB binary must be built from the X.Org source code. Hint: XVFB binaries for Solaris can be download from http://otn.oracle.com/products/ias/ias_utilities.html#xvfb Running XVFB The following command line can be used to launch XVFB: Xvfb :1 -screen 0 1x1x24 The XVFB binary must be run as root or must have the suid bit set. The :1 argument indicates that the XVFB binary runs as server number 1 (the standard X server typically runs as server number 0). The -screen argument indicates that a single screen of size 1x1 with 24-bit pixel depth should be used. Note, since all images are generated off screen, the 1x1 screen size is sufficient for image generation purposes. Since XVFB must remain running for the lifetime of the application, perhaps the best approach is to automatically launch XVFB during the machine's boot process. XVFB can then remain running as a background process until the machine is shut down. Once the XVFB executable is running, client applications can connect to XVFB by setting the DISPLAY environment variable to :1. The :1 setting indicates that server number 1 (the XVFB server) on the local machine should be used for all X graphics operations. When running in Jserv, the DISPLAY environment variable should be set in jserv.properties, for example: wrapper.env=DISPLAY=:1 Known XVFB Issues Error Opening Security Policy File When XVFB is launched, the following error message may be displayed: error opening security policy file /usr/openwin/lib/X11/xserver/SecurityPolicy To avoid this message, the location of the SecurityPolicy file can be specified explicitly when XVFB is launched using the -sp argument. On Solaris, the SecurityPolicy is located in /usr/openwin/server/etc/SecurityPolicy. As such, the following command line can be used to ensure that XVFB reads the SecurityPolicy file: Xvfb :1 -screen 0 1x1x24 -sp /usr/openwin/server/etc/SecurityPolicy Note, however, that by default XVFB only allows access to local clients, even if the SecurityPolicy file is not found. Font Configuration XVFB must be able to locate the "fixed" font in order to run. By default, the XVFB binary looks for fonts in the /usr/openwin/lib/X11/fonts/misc/ font directory. If this directory does not exist, or if the "fixed" font is not installed, XVFB will fail with the error "could not open default font 'fixed'." The "fixed" font is a standard part of the X Window System distribution. If the "fixed" font is not installed on the target machine, it must be installed, either by copying the "fixed" font from another Solaris machine, or by obtaining the "fixed" font from X.org. If the "fixed" font is installed in some location other than /usr/openwin/lib/X11/fonts/misc/, the font path used by XVFB can be modified to point to the location using the -fp command line argument. Note: The bulk of this material comes from the "Chapter 20: X Server Configuration for Image Generation" topic of the UIX Developer's Guide. This manual can be found as part of the Oracle JDeveloper Online Help. This material has been edited to take a 9iAS-generic viewpoint.