IBM Support

Starting Rational Requirements Composer Server in headless (console-only) mode on Linux

Technote (troubleshooting)


Problem(Abstract)

When starting Rational® Requirements Composer Server in headless (console-only) mode on Linux, the action will silently fail. The Java process will need to be terminated and the appropriate action taken to fix the problem before you can successfully launch the server.

Symptom

The server appears to fail because you cannot connect to it through the Rational Requirements Composer client nor can you view the Rational Requirements Composer Web or access the Jazz® administration Web page.


Cause

The server requires a display component to catch graphic components that are being generated. This display is not accessible in a headless configuration.

Environment

Linux, Headless

Diagnosing the problem

When the server does not start, inspect the logs to determine the problem. The log is located in <RRCS_Install>/server/tomcat/logs/catalina.out.

The following entry in the log is a frequent and typical indicator of this issue:
Initializing Converter Servlet...
Exception in thread "SWT Display Thread" org.eclipse.swt.SWTError: No more handles [gtk_init_check() failed].


Resolving the problem

After you determine that the server startup has failed, the Java process must be terminated. Consult your Linux reference manual for more information about how to terminate process IDs.


To resolve this issue, install X Virtual Frame Buffer (Xvfb) on your system to capture the display. Specific installation instructions provided below for Red Hat® Enterprise Linux 5 (RHEL5) and SUSE® Linux Enterprise Server 10 (SLES10):

[Instructions for a RHEL5 terminal]
Prerequisites:
*Yellowdog Updater, Modified (YUM), http://yum.baseurl.org/
*Valid YUM RHEL repository containing package: xorg-x11-server-Xvfb
Steps:
1. Type 'yum install xorg-x11-server-Xvfb' into the command line and press Enter.
2. Type 'y' and press Enter when prompted to confirm installation of this package.
3. Type 'Xvfb :3 -screen 0 800x600x24&' into the command line and press Enter. This will start Xvfb as a background process. It is possible an error message is returned about missing font path elements or _XSERVTrans.... For this procedure, it is harmless and can be ignored.
3a (Optional). However, if there is an error message with "Couldn't open RGB_DB '/usr/share/X11/rgb' " you will need to Type 'yum install Xorg' into the command line and press Enter.
3b (Optional). Type 'y' and press Enter to confirm installation of this package.
4. Type 'export DISPLAY=localhost:3.0' into the command line and press Enter.

Steps to completion if running on Tomcat
5. Navigate to <RRCS_Install>/server/ .
6. To relaunch the server type 'DISPLAY=localhost:3.0 ./server.startup' and press Enter.

Steps to completion if running on WebSphere (WAS)
5. If WAS has been started and 'converter.war' has been deployed, you will need to stop the 'converter.war'
6. Log into the WAS administrative console
7. Navigate to the node and stop 'converter.war'
8. Set the DISPLAY variable in WebSphere:
a) Navigate to: Server > Application Server > (Server which RRC Server is installed)
b) Expand Java and Process Management, select the Process Definition > Java Virtual Machine
c) Select Custom Properties
d) Click New
e) For the Name fill in DISPLAY, for the Value fill in localhost:3.0
f) Save the new value and save everything to the Master Configuration
g) Restart Websphere and deploy 'converter.war' if it hasn't been deployed

Verify that the server has successfully started by examining the log, which is located at:
Tomcat Log:
<RRCS_Install>/server/tomcat/logs/catalina.out
WAS Log:
<WAS App Server Location>/logs/SystemOut.log
for a signature entry 'INFO: Server startup in ######ms'

Note: After successfully launching the server in headless mode, if there is unacceptable truncation of rendered diagrams or font size issues, redo step 3 while specifying a DPI parameter. For example, to set the DPI to 96, start the server like this: 'Xvfb :3 -dpi 96 -screen 0 800x600x24&'.




[Instructions for an SLES10 terminal]
Prerequisites:
*Yet another Setup Tool (YaST), http://en.opensuse.org/YaST
*Valid YaST SLES10 repository containing package: xorg-x11-Xvfb, xorg-x11
Steps:
1. Type 'yast -i xorg-x11-Xvfb xorg-x11' into the command line and press Enter.
2. Continue through the installer confirming the installation of these packages.
3. Type 'Xvfb :3 -screen 0 800x600x24&' into the command line and press Enter. This will start Xvfb as a background process. It is possible an error message is returned about missing font path elements or _XSERVTrans.... For this procedure, it is harmless and can be ignored.
3a (Optional). However, if there is an error message with "Couldn't open RGB_DB '/usr/share/X11/rgb' " you will need to Type 'yast -i Xorg' into the command line and press Enter.
3b (Optional). Type 'y' and press Enter to confirm installation of this package.
4. Type 'export DISPLAY=localhost:3.0' into the command line and press Enter.

Steps to completion if running on Tomcat
5. Navigate to <RRCS_Install>/server/ .
6. To relaunch the server type 'DISPLAY=localhost:3.0 ./server.startup' and press Enter.

Steps to completion if running on WebSphere (WAS)
5. If WAS has been started and 'converter.war' has been deployed, you will need to stop the 'converter.war'
6. Log into the WAS administrative console
7. Navigate to the node and stop 'converter.war'
8. Set the DISPLAY variable in WebSphere:
a) Navigate to: Server > Application Server > (Server which RRC Server is installed)
b) Expand Java and Process Management, select the Process Definition > Java Virtual Machine
c) Select Custom Properties
d) Click New
e) For the Name fill in DISPLAY, for the Value fill in localhost:3.0
f) Save the new value and save everything to the Master Configuration
g) Restart Websphere and deploy 'converter.war' if it hasn't been deployed

Verify that the server has successfully started by examining the log, which is located at:
Tomcat Log:
<RRCS_Install>/server/tomcat/logs/catalina.out
WAS Log:
<WAS App Server Location>/logs/SystemOut.log
for a signature entry 'INFO: Server startup in ######ms


Note: The use of port 3 is just a recommendation and may need to be changed to another value based on environment. However it is strongly advised to avoid the use of ports 1 and 2.

Note: After successfully launching the server in headless mode, if there is unacceptable truncation of rendered diagrams or font size issues, redo step 3 while specifying a DPI parameter. For example, to set the DPI to 96, start the server like this: 'Xvfb :3 -dpi 96 -screen 0 800x600x24&'.'


Additional Notes:
The XVirtual Frame Buffer procedure above (Steps 3 and 4) may need to be re-executed if the server is restarted. It is advised to include these steps in a system startup script.

Document information

More support for: Rational Requirements Composer
General Information

Software version: 2.0, 2.0.0.1, 2.0.0.2, 2.0.0.3, 2.0.0.4, 3.0.1, 3.0.1.1, 3.0.1.2, 3.0.1.3, 3.0.1.4, 3.0.1.5, 3.0.1.6

Operating system(s): Linux

Reference #: 1410023

Modified date: 20 January 2010


Translate this page: