test

Netra j 3.0 Administrator's Guide

GO-Joe

The GO-Joe client-server solution enables access to Solaris/X environments from an NC.

GO-Joe comes in two packages. The GO-Joe host software, which you install, and the GO-Joe client software, which the Netra j 3.0 installation installs automatically.

The GO-Joe host software (SUNWgjvxs) is provided on the Netra j 3.0 CD in the /Misc directory to be installed on the Solaris 2.5.1 or Solaris 2.6 server of your choice. The host software sits on top of the X/CDE software on the server, taking advantage of the extended features already built into the Solaris/X server (for example, Display PostScript).

The client portion of the GO-Joe package (SUNWgjvxv) is installed with the other Netra j packages. This is the GO-Joe Java applet enabling the user to access Solaris and X applications via your GO-Joe host server. It is setup under the web server document root (system default port 80) of the Netra j server in the GO-Joe directory. In order to set up the HTML/applet file provided with this package, you must enter the name of the server where the GO-Joe host software is installed. See "To Reference Remote Windowing Servers".

Figure 4-1 GO-Joe Architecture

Graphic

Legend:

  1. Remote X applications

  2. Netra j / web server houses the GO-Joe applet

  3. Solaris/X server with GO-Joe host software

  4. NCs run the GO-Joe applet

System Requirements

You can install and run GO-Joe host software on SPARC` systems running the Sun Solaris operating environment, version 2.5.1 or 2.6.

Note -

The netra_install script does not install the SUNWgjvxs host software package. Use admintool or pkgadd to install this package on the Solaris 2.5.1 or 2.6 server of your choice.

Dependencies

GO-Joe host software requires additional Solaris software to run properly. The following table lists the Solaris dependencies.

Table 4-1 Solaris Dependencies for GO-Joe

Package ID 

Description 

Location 

SUNWcsr

Core Solaris, (root) 

Netra j 3.0 software (Solaris 2.5.1 add-on cluster) and Solaris 2.6 CD 

SUNWcsu

Core Solaris, (usr) 

Netra j 3.0 software (Solaris 2.5.1 add-on cluster) and Solaris 2.6 CD 

SUNWcar

Core architecture, (root) 

Solaris 2.5.1 or 2.6 CD 

SUNWkvm

Core architecture, (usr) 

Solaris 2.5.1 or 2.6 CD 

SUNWlibms

Solaris bundled shared libm 

Solaris 2.5.1 or 2.6 CD 

SUNWtltk

ToolTalk runtime 

Solaris 2.5.1 or 2.6 CD 

SUNWxwplt

X Window platform software 

Solaris 2.5.1 or 2.6 CD 

SUNWolrte

OPEN LOOK toolkits runtime environment 

Solaris 2.5.1 or 2.6 CD 

SUNWoldte

OPEN LOOK desktop environment 

Solaris 2.5.1 or 2.6 CD 

SUNWxwdv

X Window system kernel drivers 

Solaris 2.5.1 or 2.6 CD 

SUNWxwfnt

X Window system fonts 

Solaris 2.5.1 or 2.6 CD 

SUNWdtcor

Solaris desktop /usr/dt file system anchor

Solaris 2.5.1 or 2.6 CD 

SUNWmfrun

Motif runtime kit 

Solaris 2.5.1 or 2.6 CD 

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 browser that is fully compliant with the JDK1.1 technology.

Components and Session Overview

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

The GO-Joe session proceeds as follows:

  1. Enter a URL in the client system's browser or Java environment, which loads the HTML page containing the GO-Joe applet from the Web server.

  2. The GO-Joe applet prompts you for a login and password to authenticate you to the GO-Joe host server.

  3. When you click the Start X Session button (or press Return, depending on the browser), the login and password are sent to the GO-Joe host server (default port is 491 set up automatically) at the port specified in the HTML page loaded in step 1.

  4. The GO-Joe host server accepts the applet's connection and passes it off to the go-login program.

  5. 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.

  6. If the user name and password are valid, the go-login program starts an X session.

  7. 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 network.

Advanced Configuration Options

The GO-Joe applet ships with an example startup HTML file, xsession.html. This file is used by Netra j administration and should not be modified manually. To make advanced configurations, copy the xsession.html file to another file (for example, x.html) and use it for modifications.

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 4-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 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 can be different if the port is being used by a service other than the go-login service on the GO-Joe host server.

token 

This parameter specifies an optional "token" value to be passed into the environment of the X session. See "Token Parameter" for information on the token parameter.

The following is a sample x.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

Note -

You should specify the server parameters before adding an icon to 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 "To Add an Application Icon to the HotJava Views Selector". See the HotJava Views Administration online help for additional information.

Note -

To access the HotJava Views Administration module, use the HotJava Browser provided with the Netra j software. The path to the HotJava Browser is /opt/SUNWnhjb/bin/hotjava.

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.

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.

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
	fi
	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 (/usr/dt/config/dtgotokens) 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

  1. Run a CDE session and start the appropriate clients and applications.

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

Remote Windowing Procedures

Configure the Netra j server by using the Netra j Network Computer Application Management module to reference remote windowing servers.

To Reference Remote Windowing Servers
Note -

Remote windowing servers must be accessible to the Netra j server.

  1. From the Main Administration page, under "Network Computer Administration," click Network Computer Application Management.

    The Network Computer Application Management page is displayed.

  2. Under "Netra Client Application Administration," select one of the following:

    • To reference a Citrix Windows NT server, click Citrix.

    • To reference a GO-Joe X server, click GO-Joe.

  3. Complete the form using the information in the following table.

    Table 4-3 Remote Windowing Information

    Item 

    Description 

    Citrix Server Host Name or IP Address 

    The host name or IP address of the server running Windows NT. 

    Go-Joe Server Host Name or IP Address 

    The host name or IP address of the server running GlobalHost module.  

    Go-Joe Port Number 

    The port number in which the GO-Joe host server (X server) is running. The default port is 491 and should not be changed unless the port is already being used by another service.