test

Netra j 2.0 Administrator's Guide

GO-Joe With RapidX

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 convertor (the GlobalHost ddx loadable module) is installed on a UNIX host which provides connectivity into the X environment on the network. The Java applet enables the user to access Solaris/X Window applications. Figure 7-1 shows the GO-Joe architecture.

Figure 7-1 GO-Joe Architecture

Graphic

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 under 500 kilobytes of memory.

Dependancies

GO-Joe requires additional Solaris software to run properly. Table 7-1 list the Solaris dependancies.

Table 7-1 Solaris Dependancies for Go-Joe

Package ID 

Description 

Location 

SUNWcsr 

Core Solaris, (root) 

Netra j 2.0 software (Solaris 2.5.1 add-on cluster), and Solaris 2.6 CD-ROM 

SUNWcsu 

Core Solaris, (usr) 

Netra j 2.0 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 Windows 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 desktp environment 

Solaris 2.5.1 or 2.6 CD-ROM 

SUNWxwdv 

X Window system kernal 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 requires a JDK(TM) 1.1-capable browser. Currently, Netscape Communicator version 4.0 or earlier is unable to support AWT 1.1 and New Event Model features in JDK 1.1. To address this requirement, Netscape provides a JDK 1.1 software patch that provides the following functionality:

See http://developer.netscape.com/software/jdk/download.html for information.

Note -

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

Components and Session Overview

GO-Joe has many components that work together to bring X Windows to the JavaStation. An example X session is provided with the software. The GO-Joe session process is as follows:

  1. When you enter a URL in your browser or Java environment, it initiates a process that loads the HTML page containing the GO-Joe applet and named Solaris/X server with the GO-Joe server package loaded.

  2. The browser or Java environment then loads and runs the GO-Joe applet.

  3. GO-Joe prompts you for a username and password to authenticate you to the Solaris machine.

  4. When you click on the Connect button, GO-Joe connects to the server on the port specified in the HTML page loaded in step 1.

  5. The Solaris machine accepts the applet's connection and passes it off to the go-login program.

  6. The go-login program receives the username and password specified in step 3. If the username or password are incorrect, an error is returned by the applet and it returns to step 3.

  7. If the username and password are valid, go-login starts /usr/openwin/bin/openwin with special arguments initiating the GlobalHost loadable ddx module.

  8. The modified initialization scripts check for a GO-Joe token, and if present, modify the session startup behavior to start the clients specified by the token.

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

Configuration

The GO-Joe applet ships with several examples of how to use it. One example is the xsession.html file. This file contains an example startup that exercises all of the available parameters for the applet, but this file must be customized before it can be used.

Table 7-2 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 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 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 

The host machine that will be connected to run the RapidX session. This host must be configured with the go-login program and GlobalHost protocol. 

port 

The port number that will be contacted by the GO-Joe applet. In general use, this will be port 491, but it may be changed if multiple configurations of GlobalHost protocol are available on the host.

token 

A value to be passed into the environment of the X session.  

diaglevel 

If set to a value greater than zero, this parameter will cause the GO-Joe applet to log diagnostic information. This is not generally useful except in rare cases. If this parameter is set, then the diagfile parameter should also be set.

diagfile 

This parameter directs diagnostic output. The default output of diagnostic information is to the JavaOS system console. In environments where the JavaOS console is not available, this parameter can be used to redirect this output to a different location. 

Its format can specify a file to be logged into by setting it to an absolute path (for example, /tmp/gojoe-log). In environments where local disk storage is not available, it can be set in the form %<host>:<port>.

The following is a sample xsession.html file that initiates a default session. 

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

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: 

openwin -dev /dev/fbs/goglobal0

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

Note that you would never type theis command at the command line. It is started by a script after the go-login program has authenticated the user through inetd or perhaps 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, but limitations in some inetd software limit the number of command line arguments that can be passed to go-login, so it is usually called from a shim script as follows: 

#!/bin/sh
# This is /usr/openwin/server/etc/shim
# This gets around inetd implementations that only pass a limited number of
# command-line arguments onto go-login.
/usr/openwin/bin/go-login /usr/openwin/bin/openwin -dev /dev/fbs/goglobal0 -I -inetd

This script ensures that all of the arguments necessary are passed to go-login. The go-login program must be installed into inetd.conf as shown: 

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

Adding the GO-Joe Icon to the HotJava Views Selector

At installation, The Go-Joe properties are dumped into the selector.apps file located in /opt/SUNWjdt/lib/props. There are several selector.desktop files corresponding to their group located under /opt/SUNWjdt/lib/props/group/selector.desktop. You should add the GO-Joe entry to the appropriate groups selector.desktop file.

Upon installation of the GO-Joe packages, the Icon and all associated properties are added to the HotJava Views application palette automatically.

See the HotJavaViews online help for additional information.

To Add the OCS Icon to the HotJava Views Selector

  1. Choose Network Computer Server --> HotJava Views Administration.

    The HotJava Views Administration page is displayed.

  2. Choose Client-side Configuration --> Groups and Configuration.

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

  4. Choose the WebConnect entry in the Application Pallete and click Add.

  5. Click OK.

  6. Click Set Default Group to set this group as 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, simply load the HTML file with the applet embedded into your browser environment. GO-Joe will prompt you for a username and password to use for the session, and will proceed to provide the X display to your host.

This session is almost identical to that provided by the system console, with a few differences, which are illustrated below.

DISPLAY Environment Variable

The $DISPLAY environment variable tells X clients where to contact your X server. Unlike most X solutions which set the $DISPLAY variable to point to your JavaStation, GO-Joe sets this variable to point to an alternate display on your host machine. For example, if your host is named "workstation" and the JavaStation is named "smile," you might expect the $DISPLAY variable to use smile:0 as its value. However, GO-Joe uses the hostname 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 will attempt to connect using a local transport. For example, instead of using TCP/IP, it will connect using a named pipe. This connection is faster than using TCP/IP for JavaStation 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 hostname of your machine. This can be included in .profile file: 

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

This translates $DISPLAY from, for example, unix:3 to workstation:3 allowing X clients on other machines to successfully contact the GlobalHost loadable ddx module on the workstation host.

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 the 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 under X.

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 pointer arrow. This effect is a visual one only, as the X application will believe that the arrow has indeed changed shape.

Advanced Configuration Options

You can configure GO-Joe to provide a varitey of functions. This flexibility can be complex, so it is not generally recommended for every user. GO-Joe provides several diagnostic tools and outputs to help diagnose problems that may arise due to misconfiguration and other difficulties. See Appendix D, Troubleshooting for problem-solving tips.

Token

The GO-Joe applet accepts a token parameter in its HTML file. If this parameter is present, the applet transmits it to the go-login program along with the username and password. The go-login program will create an environment variable containing the value $GG_TOKEN which is available for other startup scripts to process.

The format of the $GG_TOKEN variable is as follows: 

[session=<openwin[boxv  ]cde>;] [ wm=<window_manager>; [boxv  ] nowm; ] <token>

If present, the session= parameter can be used to specify whether the session will be an OpenWindows style session or a CDE style session. Tokens under the CDE session type are not supported at this time.

Alternate window managers can be specified by prefixing the token proper with wm=/path/to/window/manager;. For security, you must specify an absolute path, and no spaces are allowed (and therefore, no arguments to the window manager). You can start a session without a window manager by prefixing the token proper with nowm;. The semicolon is necessary in both cases to delimit the window manager specification from the token value. Both wm=<window_manager>; and nowm; are optional and need not be specified if the default window manager is desired.

The token value can contain any alphanumeric character, as well as the plus (+), minus (-), and underscore (_) characters. The character set of supported characters is [A-Za-z0-9+-_]. Other symbols are not recommended and are not supported.

In the standard OpenWindows distribution, the openwin script checks for the existence of a ~/.xinitrc file in the user's home directory. If this file exists, it is run by the Xinit program (which also starts the Xsun server). If this file does not exist, the system wide $OPENWINHOME/lib/Xinitrc file is run. The Xinitrc file checks for ~/.openwin-init and will run it to start the sessions initial clients if it is present. If it is not present, the Xinitrc file will run the systemwide $OPENWINHOME/lib/openwin-init file.

When the GlobalHost loadable ddx module is installed, these files are modified to support GO-Joe's token facility. In this installation, the openwin script no longer checks for the existence of ~/.xinitrc, but instead always runs the systemwide $OPENWINHOME/lib/Xinitrc file. This file has been modified to check for the token environment variable ($GG_LOGIN) set by go-login. If $GG_TOKEN is set, the systemwide Xinitrc file checks for a ~/.xgotokenrc file in the user's home directory. If this file exists, it is run, otherwise, the systemwide $OPENWINHOME/lib/Xgotokenrc file is run. These files parse the $GG_TOKEN variable to determine what window manager will be run (if any). Then, they call ~/.xgotoken-init (if it exists) or $OPENWINHOME/lib/xgotoken-init, which parses the $GG_TOKEN variable to determine what clients will be start up. If the token variable does not match any of the available tokens, control is passed to the standard ~/.openwin-init or $OPENWINHOME/lib/openwin-init.

This structure enables you to create system-wide token processing routines by modifying $OPENWINHOME/lib/xgotoken-init, while enabling users to override the settings in the ~/.xgotoken-init file. In addition, care has been taken to ensure that if the $GG_TOKEN variable is not set, the session startup will be the same as a standard OpenWindows installation.

Structure of xgotoken-init

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

case "$GG_TOKEN" in
    xterm)
	if [ "$OW_WINDOW_MANAGER" = ':' ]; then
	   toolwait=
	else
	   toolwait=toolwait
	fi
	$toolwait $OPENWINHOME/bin/xterm
        exit
	;;
    *)
	echo warning: /usr/openwin/lib/xgotoken-init: \'$GG_TOKEN\': case not found.
	echo using defaults...
	;;
esac

This section parses the $GG_TOKEN (with any prefixed wm= or nowm flags removed) and starts the appropriate clients. In this example, only one token, xterm , is defined. Any other token will return an error and use the default OpenWindows startup.

Note the handling of the $toolwait variable. In Xgotokenrc, if nowm is specified, it sets the $OW_WINDOW_MANAGER variable (in conformance to 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 an empty command.

Modify the $toolwait variable, if there is a window manager running, the toolwait program starts xterm (which will run in the background). When no window manager is running, the last client started by xgotoken-init must not run in the background, or the GlobalInit program will think that the session is over and will shut down the X server. Conditionally running toolwait solves this problem.

Diagnostics and Troubleshooting

GO-Joe provides several diagnostic tools and outputs to help diagnose problems that may arise due to misconfiguration and other difficulties. Check them whenever problems are encountered.