Compute Engine
Java Servlet
Portal Environment
Multi-Domain Environment
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
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.
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
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.
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.
http://hostname.sub-domain.domain:port/amconsole
or, for the example being used in this document:
http://mercury.sun.com:80/amconsole
If there is an error, try restarting Sun ONE Portal Server by typing:
/etc/init.d/amserver start
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.
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.
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 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 The Grid Engine Portal is using the O'Reilly
servlet cos.jar The following default installation information
is available 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 VNC root directory >> /export/GridEnginePortal/vnc-3.3.5-sparc_solaris_2.5 You entered the following installation
information Do you want to use these parameters (y/n) [y]>> y The Grid Portal servlets will now be installed.
Do you want to edit the deployment descriptor (y/n) [n]>> n added manifest Please enter the amAdmin password >>
Follow the instructions in the installation
guide to add roles and to make the GEPTableContainer available.
|
Every user that utilizes VNC for X-Windows
applications must change his/her environment settings. VNC is called from
the servlet with a
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
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.
To create the GEPAdminRole repeat the steps above by replacing GEPUserRole with GEPAdminRole in the description. The GEPAdminRole should be assigned to user gepadm.
To use netlets the user profile must have access to Netlets.
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.
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.)
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.)