# Grid Engine Portal

# Installation Guide

Andre.Alefeld@sun.com
Dan.Fraser@sun.com
Ron.Selva@sun.com

# Table of Contents

Introduction & Technical Acknowledgements

Solution Components Detail

> Compute Engine
> Java Servlet
> Portal Environment
> Multi-Domain Environment

Installation Procedure

> Installation Procedure Summary
> Step 1: Sun ONE Grid Engine
> Step 2: Sun ONE Portal Server
> Step 3: Grid Engine Portal Integration Package
> Step 4: Configuring Sun ONE Portal Server
> Step 5: Using Grid Engine Portal
> Step 6: Registering New Applications with Grid Engine Portal

A Tip for Developers

Appendix A: Screenshots

# Introduction & Technical Acknowledgements

The Grid Engine Portal solution enables organizations to provide flexible, secure and managed access to High Performance Computing resources. The solution is designed to be implemented in a variety of environments, from University and Research Institutes to Commercial organizations making use of HPC technologies for aerospace, automotive, manufacturing and other compute intensive applications. The solution enables these resources to be harnessed and taken to the Internet in a secure, accountable manner. We would like to especially thank those who made significant technical contributions to the Grid Engine Portal:
Frédéric Parienté for his vision and foundational implementation of the Grid Engine Portal servlet source code.

David Bunker for the practical implementation of Sun ONE Portal Server with the Grid Engine Portal code and significant documentation contributions.

Eric Sharakan for adding & documenting (single-sign-on) X-window support to Grid Engine Portal.

# Solution Components Detail

## Compute Engine

The Compute Engine layer is essentially Sun ONE Grid Engine. Sun ONE Grid Engine is a distributed resource management solution from Sun Microsystems which controls the submission and distribution of jobs to execution hosts and the administration, management and auditing of these jobs to and from processing queues. Sun ONE Grid Engine can be integrated with other applications used in the processing of compute intensive problems.

## Java Servlet

The Java Servlets used in this solution have been created by Sun Microsystems to provide an interface between Sun ONE Grid Engine and the Sun ONE Portal Server. The Java Servlets used in this guide are SunTCP and AdminTCP and are provided with legal conditions as detailed in the source code. These applications interact with Sun ONE Grid Engine's functions and Sun ONE Portal Server's APIs to produce Content Provider windows for the portal environment.

## Portal Environment

The Portal Environment is implemented using the Sun ONE Portal Server. Sun ONE Portal Server provides the capabilities of personalization, customization, security and aggregation to a Java enabled web browser. Sun ONE Portal Server can be deployed in a multi-domain scenario, utilizing varying authentication methods and role functions within each domain.

## Multi-Domain Environment

The Multi-Domain Environment enables organizations to provision specific content, manage multiple authentication and security structures and create a personalized and customizable user experience with consistent look and feel within the domains. Within domains user roles are implemented allowing varying security levels and responsibilities to be assigned to users within the portal environment. In this solution these roles are used to differentiate between administrators, support personnel and end users. The administrative controls allowed within a domain provide a level of delegated administration to users of the solution. The Sun ONE Portal Server, it's domains and the roles and users within the domain can be customized at all levels, allowing organizations to provision content and services at a certain level and have those functions "inherited" by lower level categories. For example an application could be provisioned at the portal server level and this application could then be made available to all domains, roles and users within the portal environment.

# Installation Procedure

## Installation Procedure Summary

We will assume that the computer hardware, base operating system (including latest patches) and network configuration has been completed.

Step 1: Install Sun ONE Grid Engine (and Sun ClusterTools w/ Loose Integration for MPI support).

Step 2: Install Sun ONE Portal Server.

Step 3: Install the Grid Engine Portal Integration Package.

Step 4: Adjust the configuration of Sun ONE Portal Server.

Step 5: Test the Grid Engine Portal

Step 6: Register new applications with Grid Engine Portal

## Step 1: Sun ONE Grid Engine

Download Sun ONE Grid Engine (version 5.3p2 or later) from http://www.sun.com/gridware.

Follow the installation instructions. The default queues and the default cell will work fine.

If MPI jobs will be run through the portal, download and install the latest version of the HPC ClusterTools software at http://supportforum.sun.com/clustertools.

Create a Loose Integration for HPC ClusterTools and Grid Engine. The Loose Integration package is a part of the Sun ONE Grid Engine download (version 5.3 or later) and may be found under the directory HPC_GE_Integration. Follow the directions in the README file.

## Step 2: Sun ONE Portal Server

First, download Sun ONE Portal Server, Secure Remote Access 6.0 from http://www.sun.com/software. Select Internet & Identity Management on this web page and then Sun ONE Portal Server: Secure Remote Access 6.0 in the Portal Servers section. The download file is currently named ps-sra-6.0-us.sparc-sun-solaris8.tar.gz. Once this file is downloaded, unzip and untar it into the installation directory. Log in as root, change directories to the installation directory and then execute the pssetup installation script.

Please note that this version of the portal server software has the following hardware and software requirements:

Hardware
1 450 MHz UltraSparc II cpu or better
512 MB of Random Access Memory (RAM)
1 GB of swap space
1 GB of disk space

Software
A user distribution of either the Solaris 8 or Solaris 9 operating system.

Solaris 8 requires the following patches:
109326-03 (or later)
108434-03 (or later)
108827-15 (or later)

Since the exact questions that are asked when installing Sun ONE Portal Server vary with the type and version of installation, the following is only a general guide. During the installation of the various components, certain questions are asked repetitively. Most demo users can take all the defaults except for hostname, sub-domain name, domain name, IP address, organization name and passphrase. Before starting the installation process, check to ensure that none of the ports that you will specify is being actively used by another software component. You can do this by executing the command: netstat -na | grep port#. If a port is already being used, select another one in its place.

For the purposes of this installation guide, it will be assumed that all of the Sun ONE Portal Server components will be installed on a server with a fully qualified name of mercury.sun.com, having an IP address of 129.146.60.220.

What follows is a description of how to install the Directory Server, the Portal Server and the Gateway components of Sun ONE Portal Server individually. It is also possible (and perhaps simpler) to install all of these components at once by selecting option 4 in the installation script.

Using the pssetup script, first accept the licensing agreement by answering yes to the Do you accept? question. Then install the Directory Server (option 5). The script may list the default settings that it will use. Review these parameters and determine whether they are appropriate for this installation. If any of them need to be specifically defined, then answer no to the Use these settings? question. Following is an example dialog that will follow if you answer no or if a list of default settings was not proposed by the Portal Server installation script:

`What is the Directory Server base directory? /usr/ldap`
`What is the hostname of this server? mercury`
`What is the sub-domain name for mercury? .`
`What is the domain name for mercury? sun.com`
`What port should be used to access the Directory Server? 389`
`What is the Directory Server Administration port? 8900`
`What is the root suffix of the directory tree? o=isp`
`What is the directory manager? cn=Directory Manager`
`What is the organization name? GridEnginePortal`
`What is the passphrase for this server? ********`
`Again? ********`

The settings you just supplied will then be listed. Answer yes to Use these settings?. The Directory Server will then be installed.

Now you can install the Portal Server (option 4 in the pssetup script). Once again, check the default settings that may be listed by the script and decide whether to accept them or to specify new settings. If you answer no to the Use these settings? question, or if no settings were proposed by the script, the following example dialog will occur. Note that for the question on JDK below, the recommended version of JDK is 1.31.1_04. Using other versions may result in instability or lowered performance. The dialog for this portion of the installation is as follows:

`Do you want to use an existing JDK? n`
`What is the installation base directory? /opt`
`What is the hostname of this server? mercury`
`What is the sub-domain name for mercury? .`
`What is the domain name for mercury? sun.com`
`What is the ip address of mercury.sun.com? 129.146.60.220`
`Run SSL on mercury? n`
`What port should be used to access the Portal Server? 80`
`What is the organization name? GridEnginePortal`
`Use an existing Directory Server? y`
`Use the local Directory Server? y`
`What is the Directory Server administration port? 8900`
`What is the Directory Server base directory on mercury? /usr/ldap`
`What is the root suffix of the directory tree? o=isp`
`What is the directory manager? cn=Directory Manager`
`What is the Web Server administrator? admin`
`What is the Web Server Administration port? 8088`
`What is the passphrase for this server? ********`
`Again? ********`
`What is the deployment URI? /portal`
`Install the sample portal? y`
`What is the hostname of the gateway? mercury`
`What is the sub-domain name for mercury? .`
`What is the domain name for mercury? sun.com`
`What is the ip address of mercury.sun.com? 129.146.60.220`
`Will gateway be running SSL? y`
`What port will gateway listen on? 443`
`Will the gateway be using a web proxy? n`
`What is the name of the gateway profile? default`

The settings you just supplied will then be listed. Answer yes to Use these settings?. If you answered no to the question regarding JDK, a new JDK will then be installed. Then the Identity Server, the Portal Server and Secure Remote Access support will be installed. This process can take 25 to 30 minutes.

Now, the Gateway can be installed (option 1 in the pssetup script). Once again, check the default settings that may be listed by the script and decide whether to accept them or to specify new settings. If you answer no to the Use these settings? question, or if no settings were proposed by the script, the following example dialog will occur:

`What is the gateway base directory? /opt`
`What is the hostname of the gateway? mercury`
`What is the sub-domain name for mercury? .`
`What is the domain name for mercury? sun.com`
`What is the ip address of mercury.sun.com? 129.146.60.220`
`Will gateway be running SSL? y`
`What port will gateway listen on? 443`
`What is the name of this gateway profile? default`
`Do you want to create a self-signed certificate? y`
`What is the name of your organization? ORGNAME`
`What is the name of your division? DIVNAME`
`What is the name of your city or locality? CITYNAME`
`What is the name of your state or province? STATENAME`
`What is the two-letter country code? US`
`What is the password for Certificate Database? ********`
`Again? ********`
`What is the deployment URI? /portal`
`Start the gateway after installation? y`

The settings you just supplied will then be listed. Answer yes to Use these settings?. Once the installation has completed, you can exit from the pssetup script.

You should check the installation log file for any errors that might have occurred. This can be done by viewing the setup.log file in the directory: /var/sadm/install/logs/pssetup-<pid>, where <pid> is the process id under which the pssetup command was executed. If any errors occurred, reconcile them before continuing. You can also check the setup.log file in both /usr/ldap/setup and /opt/SUNWam/servers/setup for installation errors.

If, for any reason, you want to de-install Sun ONE Portal Server, follow this procedure:

1. Stop the portal server and gateway by executing: /etc/init.d/amserver stop and /etc/init.d/gateway stop.

2. Execute pssetup and de-install all components.

3. Exit pssetup.

4. Ensure that the following directories have been removed (assuming that /opt is the base directory):
/opt/SUNWam, /opt/SUNWps, /etc/opt/SUNWam, /etc/opt/SUNWps, /var/opt/SUNWam,
/var/opt/SUNWps.

5. Ensure that all ports that were being used are no longer active, using: netstat -na | grep port#.

(Experience has shown that the LDAP port (389) is often still active. If this is the case, first ensure that
the /usr/ldap directory has been removed. Then execute: ps -eaf | grep slapd to find any processes that
may be waiting for connection to port 389. Kill any such processes.)

You can then re-install Sun ONE Portal Server following the steps outlined previously.

Once all components are installed you can test for a successful installation by typing:

`http://hostname.sub-domain.domain:port/amconsole`

or, for the example being used in this document:

`http://mercury.sun.com:80/amconsole`

You will be prompted to enter a UserID and password. For the UserID, supply amadmin. For the password, supply the passphrase that was specified during the installation process. Then click on the Submit button. The Directory Server Access Management Edition (DSAME) console screen will appear. DSAME is also known as the Sun One Identity Server. The DSAME console is divided into three sections: the Location pane, the Navigation pane and the Data pane. The Location pane runs along the top of the console, the Navigation pane is the left portion of the console and the Data pane is the right portion of the console. Additional information regarding the layout and options available with the console can be found in the Sun ONE Portal Server Administrator's Guide.

If there is an error, try restarting Sun ONE Portal Server by typing:

`/etc/init.d/amserver start`

Then try opening the page again. If there is still an error, make sure the proxies are turned off in the Browser, and try again. If there is still no success, refer to the Sun ONE Portal Server documentation.

Sun ONE Portal Server allows for a variety of authentication methods, including LDAP, Unix, Safeword, RADIUS, etc. For the purposes of this installation guide, Unix authentication is all that is required. To configure Sun ONE Portal Server for Unix authentication, perform the following steps from the DSAME console window:

1. From the Navigation pane, click on the organization name (GridEnginePortal).

2. In the pull-down menu of the Navigation pane on the ensuing screen, select Services.

3. The Navigation pane now contains a list of DSAME Configuration Authentication options, including Core, LDAP and Membership. Click on the arrow to the right of Core.

4. The Data pane will be refreshed to show an Authentication menu with a list of authentication methods. Select only Unix from this list (de-select any others that had been previously selected).

5. Still in the Data pane, just below the Authentication menu, check the box entitled Dynamic User Profile Creation.

6. Scroll back to the top of the Data pane and click Save.

7. Click on logout at the top right of the overall console window.

8. From a terminal window, logged in as root, restart the portal server and gateway via: /etc/init.d/amserver start and /etc/init.d/gateway start.

You should now be able to login to the portal server via the gateway as follows:

`https://mercury.sun.com`

Normal users will access the portal server and Grid Engine Portal using the gateway.

For the purposes of this guide, it will be assumed that you have logged in successfully using two different user ids: gepuser (typical user) and gepadm (administrative user). This will be important when Roles are assigned later in this document.

## Step 3: Grid Engine Portal Integration Package.

The following files will need to be downloaded before you start the Grid Engine Portal installation process. For the purposes of this installation guide, it will be assumed that all of these files will be downoaded into the /tmp directory.

First, download the Grid Engine Portal installation package here. The download file is named geportal.tar.gz. As an alternative, authorized users of the Grid Engine Open Source Project can login to CVS and checkout the latest files in gridengine/gep/glue. Further hints can be found below. From this directory, the geportal.tar.gz file can be generated as follows:

`make distclean`
`make dist`

Next, after carefully reading the license conditions, download the O'Reilly Servlet package - cos-27May2002.zip - (or later version) at http://www.servlets.com/cos.

Finally, download the VNC shareware software at http://www.realvnc.com. Go to the download page at this site and select version 3.3.5. Then select the Solaris 2.5 (SPARC) package option and proceed to download, choosing the gzipped tar file vnc-3.3.5-sparc_solaris_2.5.tar.gz. Return to the original download page and select older versions and other platforms. From the ensuing page, under Other packages, select Java sources (30K) and proceed to download, choosing the gzipped tar file vnc-3.3.3r2_javasrc.tgz.

Now you are ready to install Grid Engine Portal. The Grid Engine Portal distribution comes with an install.defaults file that contains values for several parameters that are needed for the Grid Engine Portal installation. The parameter values in this file should be changed (by editing the file) to reflect the actual values for the current installation or the values can be changed during the question and answer dialog that occurs during the installation process. The parameters defined in the file are (the values inside the parentheses reflect the values suggested in this installation guide):

IPS - the Sun ONE Portal Server root directory (/opt)
IPS_DOMAIN - the Grid Engine Portal domain (GridEnginePortal)
IWS_HOST_INSTANCE - the Sun ONE Web Server host instance (https-mercury.sun.com)
IWS_HOST_VS - the Sun ONE Web Server host virtual server (https-mercury.sun.com)
VNC_ROOT - the VNC root directory (/export/GridEnginePortal/vnc-3.3.5_sparc_solaris_2.5)
APP_HOME - the home directory for Grid Engine Portal applications (/export/GridEnginePortal/apps)

Following is an example installation session.

Become root and create the SGP_ROOT installation directory.
`# mkdir -p /export/GridEnginePortal`

Note: /export/GridEnginePortal must be an NFS shared file system across all Sun ONE Grid Engine nodes.

`# chmod 755 /export/GridEnginePortal`
`# SGE_ROOT=<where Sun ONE Grid Engine has been installed>`
`# SGE_CELL=<Sun ONE Grid Engine sge_cell if not default cell>`
`# COMMD_PORT=<Sun ONE Grid Engine commd port>`
`# export SGE_ROOT SGE_CELL COMMD_PORT`
`# cd /export/GridEnginePortal`
`# gzip -dc /tmp/geportal.tar.gz | tar xvf -`

A utility known as infotext is required by the Grid Engine Portal installation script. The infotext binaries are supplied with Sun ONE Grid Engine 5.3p2. If you are installing Grid Engine Portal on a system that has an earlier release of Sun ONE Grid Engine, the infotext binaries may not be included and the Grid Engine Portal installation will fail. Check the SGE_ROOT/utilbin directory for the presence of the infotext binaries in both the solaris and solaris64 subdirectories. If they are not there, please install them before attempting to install Grid Engine Portal.

`# cd /tmp`
`# unzip cos-27May2002.zip lib/cos.jar`
`# cd /export/GridEnginePortal`
`# gzip -dc /tmp/vnc-3.3.5-sparc_solaris_2.5.tar.gz | tar xvf -`
`# cd vnc-3.3.5-sparc_solaris_2.5`
`# gzip -dc /tmp/vnc-3.3.3r2_javasrc.tgz | tar xvf -`
`# cd ..`
`# vnc_patches/applyVncPatches`

Note: You will be asked by the install script below to supply the following parameters:

O'Reilly servlet path - use /tmp/lib/cos.jar assuming you followed the exact steps above

Vnc root directory - use /export/GridEnginePortal/vnc-3.3.5-sparc_solaris_2.5 assuming you followed the exact steps above

Grid Engine Portal domain - for consistency with the nomenclature in this guide, use GridEnginePortal

`You can adapt the necessary parameters for your setup also in the file install.defaults instead of entering the information one by one.`

`# ./install -gp`
`Installing Grid Portal servlets`
`-------------------------------`
`We will ask for`
`- the O'Reilly servlet location`
`- the SunONE Portal Server root directory`
`- the Vnc root directory (optional)`
`- the Grid Engine Portal domain`
`- the S1WS host instance`
`- the S1WS host virtual server`

`The Grid Engine Portal is using the O'Reilly servlet cos.jar`
`The version we used for testing is available as`
`http://www.servlets.com/cos/cos-27May2002.zip`
`Please read the license conditions carefully and download`
`this file. Then proceed by unzipping it, e.g. like this`
`% cd /tmp`
`% unzip cos-27May2002.zip lib/cos.jar`
`This path must be entered here, e.g. /tmp/lib/cos.jar`

`The following default installation information is available`
`O'Reilly servlet: /cod_home/andre/OPENSOURCE/gridengine-private/gp/lib/cos.jar`
`Grid Engine Portal root: /export/GridEnginePortal`
`Application home: /gridware/Tools/GridPortal/apps`
`S1PS install dir: /opt`
`Grid Engine Portal domain: Germany.Sun.COM`
`S1WS host instance: https-es-ergb01-01.Germany.Sun.COM`
`S1WS host vs: https-es-ergb01-01.Germany.Sun.COM`
`VNC root directory: /gridware/Tools/GridPortal/vnc-3.3.5-sparc_solaris_2.5`

`Do you want to use these parameters (y/n) [y]>> n`

`Please enter the O'Reilly servlet path >> /tmp/lib/cos.jar`
`Please enter the Application home path >> /export/GridEnginePortal/apps`
`Please enter the S1PS install directory ( /opt ) >> /opt`
`Please enter the Grid Engine Portal domain ( sun.com ) >> GridEnginePortal`
`Please enter the S1WS host instance ( https-mercury.sun.com ) >> https-mercury.sun.com`
`Please enter the S1WS virtual server ( https-mercury.sun.com ) >> https-mercury.sun.com`
`Do you want to use VNC (y/n) [n]>> y`

`Please enter the VNC root directory >> /export/GridEnginePortal/vnc-3.3.5-sparc_solaris_2.5`

`You entered the following installation information`
`O'Reilly servlet: /tmp/lib/cos.jar`
`Grid Portal root: /export/GridEnginePortal`
`Application home: /export/GridEnginePortal/apps`
`S1PS install dir: /opt`
`Grid Portal domain: GridEnginePortal`
`S1WS host instance: https-mercury.sun.com`
`S1WS host vs: https-mercury.sun.com`
`VNC root directory: /export/GridEnginePortal/vnc-3.3.5-sparc_solaris_2.5`

`Do you want to use these parameters (y/n) [y]>> y`

`The Grid Portal servlets will now be installed.`
`Do you want to proceed (y/n) [y]>> y`

`Do you want to edit the deployment descriptor (y/n) [n]>> n`

`added manifest`
`adding: WEB-INF/(in = 0) (out= 0)(stored 0%)`
`adding: WEB-INF/lib/(in = 0) (out= 0)(stored 0%)`
`adding: WEB-INF/lib/gep.jar(in = 30881) (out= 30249)(deflated 2%)`
`adding: WEB-INF/lib/cos.jar(in = 48585) (out= 43739)(deflated 9%)`
`adding: WEB-INF/web.xml.template(in = 3089) (out= 461)(deflated 85%)`
`adding: WEB-INF/web.xml(in = 3166) (out= 464)(deflated 85%)`
`Deleting web application`
`Loading new configuration`
`Invalid URI specified with -u option.`
`The directory /export/GridEnginePortal/deploy does not exist. Creating it.`
`Deploying web application`
`Loading new configuration`
`Web application deploy successful`
`Do you want to install the GEPTableContainer (y/n) [n]>> y`

`Please enter the amAdmin password >>`
`Adding the channels. This may take some seconds. SUCCESS!`

`Follow the instructions in the installation guide to add roles and to make the GEPTableContainer available.`
`The installation is now complete.`

Every user that utilizes VNC for X-Windows applications must change his/her environment settings. VNC is called from the servlet with a

`su - <user> -c vncserver`
command and inherits the environment of the user. Add the following to the user's environment (.cshrc or .profile or similar):
`setenv SGP_ROOT /export/GridEnginePortal`
`setenv VNC_ROOT $SGP_ROOT/vnc-3.3.5-sparc_solaris_2.5`
or
`export SGP_ROOT=/export/GridEnginePortal`
`export VNC_ROOT=$SGP_ROOT/vnc-3.3.5-sparc_solaris_2.5`

Finally, set the PATH variable as follows:

`SGP_PATH=/export/GridEnginePortal`
`PATH=$PATH:$SGP_ROOT/vnc-3.3.5-sparc_solaris_2.5:/usr/openwin/bin`
`export PATH SGP_PATH`

[For debugging purposes, the output logs from the VNC software are stored in this user's directory under the hidden directory ".vnc".]

Test the gethomedir script :

`# $SGP_ROOT/bin/gethomedir $SGP_ROOT username`

This should return the following output:

`/export/GridEnginePortal/workspace/username`

## Step 4: Configuring Sun ONE Portal Server

The additional container channel GEPTableContainer is added to the organization GridEnginePortal Display Profile by the installation script.

To make the Grid Engine Portal channels available to the user the following steps have to be performed. See also the Screenshots in the appendix.

#### Create the GEPUserRole

1. Login as amadmin to http://mercury.sun.com:80/amconsole as described earlier.
2. Select the organization name (GridEnginePortal) in the Navigation (left) pane.
3. Select Roles in the pull-down menu that appears in the ensuing Navigation pane.
4. Click New, and on the Data (right) pane, Create Role appears. Enter the name GEPUserRole, enter a description and leave the rest untouched. Finally, press Create, and in the Navigation (left) pane, the new role appears.
5. Click on the link for the new role; choose Users in the GEPUserRole panel and click Add. In the Data (right) pane a Search form appears. Press Search at the bottom right of the Data pane and add the user that will access Grid Engine Portal user channels by checking the box to the left of one of the default users. Then press Submit. . The selected user is added in the Navigation (left) panel. Make sure that you have selected the correct default user - you want to have created a user role for gepuser. You can see the user name that was assigned by clicking on the right arrow next to default and then checking the Data (right) pane, which will display the user name. If you chose the wrong default user, you will see the gepadm user name displayed instead of the gepuser name. If this happens, Remove the user and start again. (See the SunONE Portal Server documentation for additional information how to add users to roles and to setup users for the default organization)
6. Click the arrow next to the default user in the Navigation (left) pane and enable Netlet in the Data (right) pane by checking the box next to Netlet under Services (if you plan to use Xvnc). Save your settings.
7. In the GEPUserRole Navigation pane, choose Services and click on the arrow next to Portal Server Configuration -> Desktop. Continue on the right (Data pane) to add the GEPTableContainer to the default Desktop Container. If there is no template available already you might have
   to press Create in the right pane.
8. In the Data (right) pane, select Channel and Container Management in the Dynamic section.
9. Select JSPTabContainer in the Container Channels list in the Data pane.
10. In the Channel Management section of the Data pane, select GEPTableContainer in the Existing Channels list.
11. In the Data pane, click Add to place GEPTableContainer in the Available And Visible list.
12. Click Save in the Channel Management section of the Data pane and then logout in the upper right corner of the overall display.

#### Create the GEPAdminRole

> To create the GEPAdminRole repeat the steps above by replacing GEPUserRole with GEPAdminRole in the description. The GEPAdminRole should be assigned to user gepadm.

#### Customize the channels that are displayed for GEPUserRole:

1. Login as amadmin to http://mercury.sun.com:80/amconsole as described earlier.
2. Select the organization name (GridEnginePortal) in the Navigation (left) pane.
3. Select Roles in the pull-down menu that appears in the ensuing Navigation pane.
4. Click GEPUserRole.
5. In the GEPUserRole panel choose Services and click on the arrow next to Portal Server Configuration -> Desktop.
Continue in the Data (right) pane to add the GEPTableContainer to the default Desktop Container.
6. In the Data (right) pane, select Channel and Container Management in the Dynamic section.
7. Select GEPTableContainer in the Container Channels list in the Data pane.
8. Check the *Admin* channels and Delete them from the list of channels and then logout from the console.

Now, when a user logs in via the gateway (https://mercury.sun.com), a new Tab will appear at the top of the portal display page entitled GEPTableContainer. By clicking on this Tab, the portal display will be refreshed to show all of the Grid Engine Portal channels (Job List, Application List, Project List, etc). The name of the Tab can be changed to something more reasonable and understandable by performing this procedure:

1. Login as amadmin to http://mercury.sun.com:80/amconsole as described earlier.
2. Select the organization name (GridEnginePortal) in the Navigation (left) pane.
3. Select Services in the pull-down menu that appears in the ensuing Navigaion pane.
4. After the Navigation pane has been refreshed, click on the right arrow next to Desktop under Portal Server Configuration.
5. In the Data (right) pane, select Channel and Container Management in the Dynamic section.
6. Click on Edit to the right of JSPTabContainer under the Container Channels list of the Data pane.
7. Click on Edit to the right of TabProperties in the Properties section of the Data pane.
8. In the Data pane, click Add in the Properties section, choose Collection from the Type pull-down menu and enter GEPTableContainer in the Name box. Then click Add.
9. Click Edit to the right of GEPTableContainer in the Properties section of the Data pane.
10. Click Add under Properties in the Data pane and then type in the following entries (after finishing each entry, click Add at the bottom of the section, then click Add under Properties to go to the next entry).
`Type: string Name: title Value: Grid Engine Portal`
`Type: boolean Name: removable Value: true`
`Type: boolean Name: renamable Value: true`
`Type: boolean Name: predefined Value: true`
`Type: string Name: desc Value: Grid Engine Portal Tab`
11. Click Save under Properties in the Data pane.
12. Click Save at the top of the Data pane.
13. Click logout at the top right corner of the portal page.

Now when a user logs in to the gateway, the Grid Engine Portal Tab will appear. The user can also change the name to one of his own choosing by selecting Tab at the top of the display.

#### Setup Netlets

1. Login as amadmin to http://mercury.sun.com:80/amconsole as described earlier.
2. Select the organization name (GridEnginePortal) in the Navigation (left) pane.
3. Select Services in the pull-down menu that appears in the ensuing Navigation pane.
4. Click the arrow under SRAP Configuration -> Netlet.
5. In the Data (right) pane, press Add under the Dynamic section.
6. For Rule Name enter: Xvnc:1
For Encryption Algotithms select Other.
For URL enter: /portal.vnc
For Download Applet check the box and enter: 5801:mercury.sun.com:5801
For Extend Session check the box
For Port - Host - Port remove any entry that is already in the list, then for Client Port, enter 5901, for Target Host(s), enter mercury.sun.com and for Target Port(s), enter 5901. Then click Add to List.
7. Press Save to save these settings
8. Repeat the steps 1 to 7 by replacing 5801 with 580n and 5901 with 590n, where n is 2, 3, ...n, and then logout as before.

To use netlets the user profile must have access to Netlets.

## Step 5: Using Grid Engine Portal

Access Sun ONE Portal Server via the link https://mercury.sun.com/. When you login, a small Netlet window will pop up. This window hosts the netlet applet, which is required for tunneling the Xvnc protocol through the portal. Heed the warning in the window about not closing it. You will also find a netlet channel on your desktop, with a note saying No netlet targets configured (unless you have configured other, non Xvnc netlet targets). This comment is not entirely accurate; targets are configured for Xvnc, but they do not show up in the Netlet channel. Do not remove this channel from your desktop. Also, the Netlet window does not dismiss itself when you logout. You must manually dismiss it, or netlet functions will not work the next time you login.

In the portal server, the Project List, Job List, and Application List channels should be visible. If logged in as root or as an administrative user there will be Admin Application List and Job Accounting channels. (If these channels display errors, check for incorrect paths and make sure Grid Engine is accessible from the portal. Also it is sometimes helpful to view the source behind the channels, which can be accomplished by right clicking on the mouse and selecting the View Source option.)

Users can select which channels they wish to have visible by checking on the Content switch. The order in which channels are displayed can be set by the Layout switch.

The Job List channel should contain the message You have no running jobs. This message shows that contact with Sun ONE Grid Engine has been established (qstat has executed successfully). (A Java error in this window could indicate a problem communicating with Sun ONE Grid Engine. Go back and verify that Sun ONE Grid Engine and Sun ONE Portal Server were installed correctly. Try logging in directly as the user, executing the Sun ONE Grid Engine settings script (settings.sh), and running qstat.

The Project List contains a list of projects for the current user. Projects are stored in the suntcp subdirectory of the /export/GridEnginePortal/workspace/username directory. A list of projects is kept in the file .suntcp-list in the user's home directory. An example file might look like:

Fasta_project Fasta Genome
Blast_project Blast Genome
Qmon_project qmon
P1002129493410 New Project name

where the first entry on each line corresponds to a specific directory that was created by Grid Engine Portal in the user's workspace and the second string (separated by a tab) corresponds to the name of the project that is used in the Project List channel. If there are no Projects, then you can add a project by clicking on the Create new project link. (Note: Use of any other character than a Tab to delineate the entries will result in a variety of strange errors. If you edit these files by hand, be sure that your editor is not inserting multiple spaces in place of tabs.)

Finally the Application List channel should contain a list of applications that was installed in the Application directory (/export/GridEnginePortal/apps) during the installation process. If there are no applications, make sure the application files were installed correctly in the applications directory.

Before attempting to run any jobs, ensure that the permissions are set correctly for the /export/GridEnginePortal/apps directory
by executing the command: chmod +r /export/GridEnginePortal/apps/*/*.

Now you are ready to run a job. Click the Submit new job link in the Job List channel. Select the Fasta Genome project. Use the default values for Algorithm, and Query file. Select the first database in the list. Click submit. (If this project is not available, create a project for the Sleeper Demo application. Then submit this job. The input argument is simply the number of seconds you want the processor to sleep). When the screen refreshes, the job should appear. Click on the job for detailed information from Sun ONE Grid Engine. Make sure the job is executing. If it is waiting for a queue, for example, Sun ONE Grid Engine may not be properly configured.

If an error is detected, you can attempt to debug it by executing the job by hand. First, you will need to go to the /export/GridEnginePortal/workspace/username/suntcp directory of the user that logged into the portal. This directory should contain a list of projects. Look at the .suntcp-list file to determine which project directory you just used, then go to the appropriate project directory.

Two files that should be in this directory are .suntcp-su and .suntcp-qsub. The Grid Engine Portal executes the .suntcp-su script, which in turn executes the .suntcp-qsub script. Try executing these by hand. Any errors detected should indicate possible errors in the Sun ONE Grid Engine, Sun ONE Portal Server or Grid Engine Portal setup. Common errors include incorrect permission settings on the application or queue problems with Sun ONE Grid Engine.

Next try submitting a job that uses an X-windows interface. Go to the Qmon subdirectory of the applications directory. Create a qmon project if there is not already one. Then submit this project as a new job.

[Note: The Sun ONE Portal Server netlet which tunnels the X11 Grid Engine Portal connection between client and server is sensitive to your browser's proxy settings. In addition, it cannot understand so-called PAC (proxy auto-config) files (yet). This means the netlet will use whatever settings are under your Netscape Manual ProxyConfiguration settings, even if you're configured to use the Automatic Configuration. So either make sure the settings under the Manual configuration are reasonable, or select Direct connection to the internet, whichever is appropriate for your configuration.]

When submitting a job that utilizes X11, the first time you do so after logging in, a new X server is launched for you, and an applet window is displayed in your browser. This applet is essentially your X display. Your job should appear in this window shortly. You can leave this window open for the duration of your portal session, and any new applications utilizing X will appear in this window.

Alternatively, you can explicitly start the X session by clicking the Launch Xvnc server bookmark, which you'll find in the Bookmarks channel of your desktop. Once the X session has begun, other jobs launched which utilize X will use the existing session.

There is absolutely no X state kept on the applet side. If the applet crashes, or you inadvertently close the window, you can restart the applet one of two ways: via the Launch Xvnc server bookmark in your Bookmarks channel, or by attempting to launch another X-based application. Either way, Grid Engine Portal notices you already have a session active, and provides you a link to just restart the viewer applet. Click that link, and you should find the X display exactly as you left it.

The X session automatically terminates when you logout of the portal. In addition, a Kill Xvnc server bookmark is provided for you if you want to do so manually. While killing the Xvnc server seems to kill any jobs running under it, it is not recommended to rely on this behavior. It's better to make sure your X-based jobs are no longer running before killing the X session explicitly or logging out.

## Step 6: Registering New Applications with Grid Engine Portal

Registering applications with Grid Engine Portal involves editing two files and (if desired) creating a form. (Note: Use only characters a-z 0-9, space, tab, and underscore in the Grid Engine Portal files. Characters such as quotation marks or apostrophes can cause errors.)

Edit the .suntcp-list file in the applications directory specified above. This file contains lines, each with two entries of the form directory (tab) Application Description. Add a new line with the directory that the application will execute from, then a tab character, then a description that will show up in the Portal. Create the directory and place the executable there. The executable can be a script, a link, or an actual binary. Make sure any relevant data files are accessible from this directory. (Note: Use of any other character than a Tab to delineate the entries will result in a variety of strange errors. If you edit thse files by hand, make sure that your editor is not inserting multiple spaces in place of Tabs.)

Create a .suntcp-app file in the directory just created. For examples, look at the equivalent file in other application directories. This file contains the following lines:

Line 1- An application description (version etc.)
Line 2- The name of the executable
Line 3- yes/mpi/no Whether or not the application runs SMP/MPI/ or Sequential
Line 4- yes/no Whether the application uses an X-windows interface
Line 5- yes/no Whether the application uses a form
Line 6- List of users who have access to the application (optional)

(Note: If no user access list is being defined, Line 6 must be a blank line.)

Line 7- Additional lines can be inserted directly into the script that is submitted to Sun ONE Grid Engine. Useful examples can be Sun ONE Grid Engine commands (e.g. #$ -q qname) or environment variables (e.g. export Option=2). Place each command on a separate line.

Create an HTML/JavaScript form if Line 5 contains yes. This file must be named .suntcp-form. Example forms for use as templates can be found in the existing application directories. Forms are responsible for creating the execution line arguments. (Technical note: the form.elements[0] element is reserved to make sure the form returns to the proper location. Do not modify the lines of code that use this element. Begin modifying the [1] element.)

# A Tip for Developers

The source code for the Grid Engine Portal can be retrieved via CVS from the Grid Engine open source site.
This involves the following steps:

- Register as a sunsource.net member
- Join the Grid Engine project as Observer
- Setup the cvs environment for Grid Engine
  with ssh tunneling (inside SWAN a SOCKS enabled ssh version has to be used)
  % ssh -f -x -L 2401:localhost:2401 tunnel@cvs.gridengine.sunsource.net echo hallo
  password: tunnel
  % setenv CVSROOT :pserver:<yourusername from registration>@localhost:/cvs
  without ssh tunneling
  % setenv CVSROOT :pserver:<yourusername from registration>@cvs.gridengine.sunsource.net:/cvs
  this applies to both versions
  % cvs login enter <yourusername from registration> as username and your corresponding web password
  % cvs co gridengine/gep if you only need the Grid Engine Portal sources
  % cvs co gridengine if you want to get the complete Grid Engine source distribution
  additional information explaining the concepts and command of cvs can be found under www.cvshome.org
- To build the distribution package it might be necessary to adjust the paths in gridengine/gep/glue/Makefile to your site
  % make distclean removes everything
  % make rebuilds any changed classes
  % make dist creates a new installable geportal.tar.gz package
- The same steps apply for the iPS3 version in the corresponding iPS3 subdirectory

# Appendix A - Screen shots

Admin login, make sure you are using the complete hostnames you entered during the portal server installation.
Enable Unix login in the portal server.
Enabling netlet support for the user
Entering the netlet rules for VNC