Netra j 2.0.1 Product Notes

GO-Joe With RapidX

The Netra j 2.0.1 product contains version 2.01b1 of the GO-Joe X-hosting software. The GO-Joe client-server solution enables access to the Solaris environment and applications from a JavaStation computer.

This section supersedes the following sections in the Netra j 2.0 Administrator's Guide

Using Netra j Connectivity Software, GO-Joe With RapidX

Troubleshooting, GO-Joe

GO-Joe is an X server that provides access to all Solaris and X applications within a JavaStation environment.

After configuring the GO-Joe X server, use the Netra j Remote Windowing Tools module to specify the host name or IP address to the Netra server. See "To Reference Remote Windowing Servers".

GO-Joe consists of two modules that work together to provide X connectivity in the JavaStation environment: the X-to-RapidX converter and the GO-Joe applet. The X-to-RapidX converter (the GlobalHost ddx loadable module) is installed on a UNIX host that provides connectivity into the X environment on the network. The Java applet enables the user to access Solaris and X Window applications.

System Requirements

You can install and run GO-Joe on SPARC` systems running the Sun Solaris operating environment, version 2.5.1 or later. The adaptive RapidX protocol and the Java applet total about 250 kilobytes of memory.

Installation

The netra_install script does not install the SUNWgjvxs server software package. Use admintool or pkgadd to install this package.

Dependencies

GO-Joe requires additional Solaris software to run properly. Table 1-4 lists the Solaris dependencies.

Table 1-4 Solaris Dependencies for GO-Joe


Package ID	Description	Location
`SUNWcsr`	Core Solaris, (root)	Netra j 2.0.1 software (Solaris 2.5.1 add-on cluster), and Solaris 2.6 CD-ROM
`SUNWcsu`	Core Solaris, (usr)	Netra j 2.0.1 software (Solaris 2.5.1 add-on cluster), and Solaris 2.6 CD-ROM
`SUNWcar`	Core Architecture, (root)	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWkvm`	Core Architecture, (usr)	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWlibms`	Solaris bundled shared libm	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWtltk`	ToolTalk runtime	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWxwplt`	X Window platform software	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWolrte`	OPEN LOOK toolkits runtime environment	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWoldte`	OPEN LOOK desktop environment	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWxwdv`	X Window system kernel drivers	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWxwfnt`	X Window system fonts	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWdtcor`	Solaris desktop `/usr/dt` file system anchor	Solaris 2.5.1 or 2.6 CD-ROM
`SUNWmfrun`	Motif runtime kit	Solaris 2.5.1 or 2.6 CD-ROM

GO-Joe uses JDK(TM) 1.1 application program interfaces (APIs), including AWT 1.1 (abstract windowing toolkit) and the New Event Model. Therefore, GO-Joe requires a fully JDK 1.1-capable browser. As of this writing, HotJava Browser 1.1 for the Solaris operating environment is the only browser that supports AWT 1.1 and New Event Model features in JDK 1.1. Netscape Navigator(TM) 4.03 supports only a subset of JDK 1.1. If you prefer a Netscape browser, check the Netscape web site at http://devedge.netscape.com/software/index.html for information about a JDK 1.1 software patch that provides the following functionality:

AWT 1.1
New Event Model
JavaBeans(TM) Support
Printing Support for Applets

Note -
You must install Netscape Communicator 4.0 and Netscape's JDK 1.1 software patch before running GO-Joe.

Components and Session Overview

A GO-Joe session involves several components working together to bring X Windows to network computer desktops:

The network computer client(s)
The X-to-RapidX converter (or RapidX server)
A Web server to deliver the GO-Joe applet

The RapidX server and the web server could conceivably reside on two different machines. However, Netra j automatically configures them both on the same machine. Netra j also provides an example X session. The GO-Joe session proceeds as follows:

You enter a URL in the client system's browser or Java environment loading the HTML page containing the GO-Joe applet from the Web server.
The GO-Joe applet prompts you for a login and password to authenticate you to the RapidX server.
When you click the Start X Session button (or press Return, depending on the browser), the login and password are sent to the RapidX server at the port specified in the HTML page loaded in step 1.
The RapidX server accepts the applet's connection and passes it off to the go-login program.
The go-login program receives the user name and password specified in Step 3. If the user name and/or password are incorrect, an error is returned by the applet and it returns to Step 3.
If the user name and password are valid, the go-login program starts an X session with special arguments initiating its use of the GlobalHost loadable ddx module.
Initialization scripts check for a GO-Joe token, and if present, modify the session startup behavior as specified by the controls in the token parameter.

After these steps, the session is displayed within the GO-Joe applet and you are able to run X clients from the UNIX network.

Web Server Integration

The GO-Joe applet class files (from the SUNWgjvxv package) are installed by default into /opt/SUNWgjvxv. These files must be accessible to the Java device via the http server.

You can make these files viewable by the http server by creating a symbolic link in the web server's document root pointing to the installation directory of the GO-Joe applet class files:

# cd /var/http/demo/public
# ln -s /opt/SUNWgjvxv GO-Joe

This makes the GO-Joe class files accessible with a URL resembling the following: http://webserver/GO-Joe/.

You should modify the example xsession.html file and use it to load the GO-Joe session.

Configuration

The GO-Joe applet ships with an example startup HTML file, xsession.html. You should save this file and not modify it. Make a copy of this file and rename it to x.html, for example.

The sample x.html file contains an example startup session that exercises some of the available parameters for the applet, but this file must be customized before it can be used.

Table 1-5 Applet Parameters


Parameter	Description
width	This parameter is specified in the `APPLET` tag and determines the width of the GO-Joe frame in the HTML file. Its format is browser- specific, but it can generally be an absolute number of pixels (for example, "width=800") or a percentage of the browser window's width (for example, "width=100%").
height	This parameter is specified in the `APPLET` tag and determines the height of the GO-Joe frame in the HTML file. Its format is browser- specific, and it can generally be an absolute number of pixels (for example, "height=600") or a percentage of the browser window's height (for example, "height=90%").
server	This parameter specifies the name or IP address of the host machine that runs the X session.
port	This parameter specifies the port number that is contacted by the GO-Joe applet. Usually, this is port 491; however, it may be different if the port is being used by a service other than the `go-login` service.
token	This parameter specifies an optional "token" value to be passed into the environment of the X session. See "Advanced Configuration Options"" in this chapter for information on the token parameter.

The following is a sample xsession.html file that initiates a default session. This sample does not demonstrate all of the available parameters.

<HTML>
<HEAD><TITLE>GO-Joe Example Session</TITLE></HEAD>
<BODY>
<HR>
<APPLET ARCHIVE="gojoe.jar" CODE="gojoe.class" WIDTH="800" HEIGHT="600">
	<PARAM NAME="server" VALUE="myhost">
    <PARAM NAME="port" VALUE="491">
</APPLET>
</BODY>
</HTML>

The GlobalHost Loadable ddx Module

The GO-Joe applet communicates through a dynamically loaded Xsun device driver. This driver appears to the Xsun server to be a standard display driver, but transmits display operations to the GO-Joe applet. This is referred to as the GlobalHost loadable ddx module.

To start the Xsun server with the GlobalHost loadable ddx module, you need to reference the device files created in /devices similar to the following:

/usr/openwin/bin/goinit /usr/dt/bin/Xsession -- 
/usr/openwin/bin/Xsun :1  -dev /dev/fbs/goglobal0 -I -inetd

When the Xsun queries this device, it loads the correct module for GO-Joe.

Note that you would never type this command at the command line. It is started by a script after the go-login program has authenticated the user through inetd or started by the go-login program itself.

The `go-login` Authentication Program

The go-login program is started by inetd and receives user authentication information from the applet before starting the session. The go-login program is designed to be called directly from inetd. Some implementations of inetd software limit the number of command-line arguments that can be passed to the go-login program, making it necessary to call the go-login program from a goshim script. The goshim ensures that all of the arguments are passed to the go-login program. To use a goshim, go-login must be installed into your inetd.conf file as follows:

go-login stream tcp nowait root /usr/openwin/server/etc/goshim goshim

Adding the GO-Joe Icon to the HotJava Views Selector

Icons in the HotJava Views Selector are part of a HotJava Views group's configuration. To add the GO-Joe icon to a group's configuration, follow the procedure below. See the HotJava Views Administration online help for additional information.

Note -

You should specify the server parameters before adding an icon to HotJava Views Selector.

To Add the GO-Joe Icon to the HotJava Views Selector

Choose Network Computer Server -> HotJava Views Administration.

The HotJava Views Administration page is displayed.

Choose Client-side Configuration -> Groups and Configuration.

Select the Group to which you want to add the GO-Joe icon and click the Selector Applications button.

Select the GO-Joe entry in the Application Palette and click Add.

Click OK.

Click Set Default Group to set this group as the default.

The default is Basic.

HotJava Views Selector is now configured with the GO-Joe icon.

Running GO-Joe

To start a GO-Joe session, load the HTML file with the GO-Joe applet into your Java environment. GO-Joe prompts you for a user name and password for the session, and after authentication, provides the X display on your Java desktop.

This session is almost identical to running an X session on the system console, with a few differences, which are described below.

DISPLAY Environment Variable

The $DISPLAY environment variable tells X clients where to contact your X server. GO-Joe sets this variable to point to an alternate display on your host machine. For example, if your UNIX host is named workstation and the Java device is named java, you might expect the $DISPLAY variable to set java:0 as its value. However, GO-Joe uses the host name for its $DISPLAY variable value, in this case, workstation:1.

GO-Joe makes an additional optimization that can be somewhat confusing. In X parlance, if the $DISPLAY variable is set to unix:#, the JavaStation client attempts to connect using a local transport. For example, instead of using TCP/IP, it connects using a named pipe. This connection is faster than using TCP/IP for clients running on the same host. However, the unix:# value cannot be used if you run clients from different hosts.

Instead, use the following shell script to change the $DISPLAY variable to point to the host name of your machine. This translates $DISPLAY from unix:3, for example, to workstation:3 enabling X clients on other machines to successfully contact GO-Joe on the workstation host. This can be included in the .profile file:

DISPLAY=`/bin/uname -n``/bin/expr $DISPLAY : '[^:]*\(:.*\)'`

Using a Two-Button Mouse

X requires and assumes the availability of a three-button mouse. Most Java environments provide a two-button mouse. In an X session, the left and right mouse buttons correspond to the left and right mouse buttons under X. GO-Joe maps the simultaneous pressing of both mouse buttons into a middle mouse button press.

The Mouse Arrow

Current AWT implementations provide only limited support for specifying the shape of the mouse arrow in the Java environment. For this reason, GO-Joe currently does not change the shape of the mouse arrow.

Advanced Configuration Options

You can configure GO-Joe to provide a variety of functions. This flexibility can be complex and should only be done by advanced users or system administrators.

Token Parameter

The GO-Joe applet accepts an optional token parameter in its HTML file. If the token parameter is present, the applet transmits it to the go-login program, along with the user name and password. The go-login program creates an environment variable, $GG_TOKEN, which is available for other startup scripts to process.

The following three controls are supported by the token parameter:

Session Control [session=<openwin|cde>;]--This control is used to specify the session as either OpenWindows(TM) or CDE. If this control is not set, OpenWindows is the default desktop on Solaris version 2.5 and earlier, and CDE is the default for Solaris version 2.6 and higher. The session control is optional.

Window Manager Control [wm=</path/to/window/manager>|nowm>;]-- Alternate window managers can be specified by using this control. For security reasons, you must specify an absolute path corresponding to an executable window manager. Therefore, no arguments can be passed to the window manager. The window manager control is optional.

Note -
The X session terminates when the key client terminates. Normally the window manager is the key client and provides a menu item or button to exit the session. If you specify nowm, one of the clients started in the case specified by the Startup Control needs to become the key client. Therefore, if nowm is specified, a startup control is required.

Startup Control--The startup control must correspond with a $GG_TOKEN case in either $HOME/.gotoken-init or /usr/openwin/lib/gotoken-init.

The Solaris session startup files (OpenWindows or CDE) are initiated when the GlobalHost loadable ddx module is installed.

When starting an OpenWindows session, the token parameter is used in $OPENWINHOME/lib/gotoken-init or in $HOME/.gotoken-init. If $HOME/.gotoken-init exists, it is used before $OPENWINHOME/lib/gotoken-init. System administrators and system integrators can create system-wide token processing routines by modifying $OPENWINHOME/lib/gotoken-init, while still enabling users to override these settings in the $HOME/.gotoken-init file. In addition, if the $GG_TOKEN variable is not set, the session startup is the same as a standard OpenWindows session.

The CDE startup mechanism is somewhat different from the OpenWindows mechanism. Unlike OpenWindows, which uses a single openwin-init file, CDE stores its session initialization as a directory filled with several files. Because of this, the CDE token is used to specify a session to be started. Sessions are stored in /usr/dt/config/dtgotokens, in subdirectories that match the name of the startup control. When the session is started with the CDE token, the session directory is copied into the user's home directory, and CDE starts this session for the user.

Structure of `gotoken-init`

The gotoken-init is based on the standard openwin-init file, with the addition of the following section:

	if [ "$OW_WINDOW_MANAGER" = ':' ]; then
	   toolwait=
	else
	   toolwait=toolwait
	if
	unset OW_WINDOW_MANAGER
	case "$GG_TOKEN" in
    xterm)
		$toolwait $OPENWINHOME/bin/xterm
	;;
    *)
        	echo >&2 "$OPENWINHOME/lib/gotoken-init: error:
\'$GG_TOKEN\': case not found."]
	echo >&2 "    Using defaults."
	. $OPENWINHOME/lib/openwin-init
	;;
esac

This section parses the $GG_TOKEN (with any session or window manager controls removed) and starts the appropriate client or clients. In the example, only one startup control, xterm, is defined. Any other token returns an error and use the default OpenWindows startup.

If nowm is specified, the $toolwait variable sets the $OW_WINDOW_MANAGER variable (in conformance with the standard OpenWindows method of specifying an alternate window manager) to the colon. This results in no window manager being executed when the shell interprets the colon as a null command.

If you modify the $toolwait variable when there is a window manager running, the $toolwait program is invoked to start xterm (which runs in the background). When no window manager is running, the last client started by gotoken-init must not run in the background, or the GlobalInit program thinks that the session is over and shuts down the X server. Conditionally running the toolwait program solves this problem.

Structure of `dtgotokens` Directory

The dtgotokens directory contains subdirectory names that match the possible values for the startup control in $GG_TOKEN. Each subdirectory contains the files necessary to start a CDE session with the X applications that are appropriate. The example directory, xterm, starts a single xterm window.

To create additional tokens, first run a CDE session and start the appropriate clients and applications. Second, exit the CDE session. The session is saved in ~/.dt/ sessions. Copy the session files into the dtgotokens directory using a command similar to the following:

# cp -R ~/.dt/sessions /usr/dt/config/dtgotokens/sampletoken

The -R argument is used to copy recursively (including subdirectories). You do not have to create the sampletoken directory before executing this command.

GO-Joe Diagnostics and Troubleshooting

GO-Joe provides diagnostic tools and outputs to help diagnose problems that may arise due to misconfiguration and other difficulties. Check these if you encounter any problems.

JavaOS Console Output

On devices that provide it, the JavaOS console output (see "Troubleshooting") can be highly informative if the applet terminates prematurely. When viewing this output, look for all exceptions that may be listed. Exceptions may occur that cause further exceptions as the program continues to execute, and it is usually the original exception that indicates the true cause of the problem. In addition, the GO-Joe applet prints messages to the status bar, but not all Java environments show this status (or they may overwrite it with their own status messages). These messages are also sent to the Java console, so they may be visible in the console log when they are not visible on the status line.

The `/tmp/Xerr:n` Error File

The GlobalHost loadable ddx module redirects the standard error output for the session to a file called /tmp/Xerr:n, where n represents the display number of the session. This file contains diagnostic messages from the GlobalInit program, from the ddx loadable module itself, and from the X clients that run throughout the session.

Common Problems

The GO-Joe product has been designed to be easy to configure and use, yet is somewhat complex in operation. Some of the more common problems encountered are described here.

HTML References

If the GO-Joe applet fails to load entirely, check the HTML file you are loading and verify that the APPLET tag is correctly formed. Check the codebase path and the path and file name to the applet file itself. Finally, investigate the log files for your HTTP server (usually called access_log and error_log) to see if the applet is being successfully transmitted to the Java environment. It may help to exit your browser or Java environment and restart it to clear any cached files that may be interfering with the applet's execution.

Java Security Manager Exceptions

All Java environments implement a security manager that determines what operations may be dangerous for an applet to perform and can enable or restrict these actions as it sees fit. The biggest restriction that most Security Managers implement with respect to GO-Joe is that an applet is allowed to connect only to the host that served that applet. If you have such a Security Manager, your GO-Joe applet is only able to connect to the go-login program running on the server that the applet was loaded from. In addition, the diagfile functionality of GO-Joe is similarly restricted.

The JavaStation produces a message as follows:

Sunw.hotjava.applet.AppletSecurityException: checkconnect.networknone
at sunw.hotjava.security.CommonSecurity.checkconnect()
at java.net.InetAddress.getAllByName)()

Remote Windowing Procedures

Configure the Netra j server by using the Netra j Remote Windowing Tools module to reference remote windowing servers.

To Reference Remote Windowing Servers