LRZ Grid Portal: GSISSH Term's Guide

GSISSH-Term at LRZ

What is GSISSH-Term?

GSISSH-Term is a Java based terminal client application for accessing the Grid. It supports the use of grid certicates for authentication. Since this application is written in Java, it is supported on most platforms (e.g. Windows, MAC and Linux). It is also available as a Java webstart application.

Setting up GSISSH-Term
User Guide to gsissh to LRZ resources
Remote Visualisation at LRZ with GSISSH-Term
General Useful Links
Tips

Preparing for GSISSH-Term

Setting up Grid Certificates

Users have to place the required grid certificates (CA certificates and personal certificates) appropriately in their machine before they can access LRZ's grid. Please follow the following steps:

Ensure that your grid certificates (usercert.pem and userkey.pem) are in ".globus" folder in your home directory. For Linux/Unix user, the ".globus" folder should be in $HOME. For Windows user, the ".globus" folder should be in following directory: "C:\Documents and Settings\{username}".
Hint: Please kindly ensure that your certificate and private key are named "usercert.pem" and "userkey.pem" respectively.
LRZ provides a customised version of GSISSH-Term that automatically retrieve from the server and update the required CA certificates into the appropriate local folders. As such, users no longer need to be concerned with the set up of the CA certificates.

Note: If you choose to use other forms of grid certificates, e.g. PKCS12 (.p12), please kindly refer to the Section Other Authentication methods supported by GSISSH-Term" for additional instruction.

Setting up GSISSH-Term

LRZ supports 3 methods to set up or use GSISSH-Term. The easiest method is to initiate it as a Java webstart application. Another easy method is to use the the applet version. Finally, for advanced users, you might prefer to download and install the source so as to generate a ".sh" or ".bat" executable on your local machine.

For the first two methods, as java webstart application and applet, you will need Java Runtime Environment (JRE) 1.5 or higher installed to run the application. For the third method, you will be required to install Java Development Kit (JDK) 1.5 or higher to compile and run the application. The applet method is especially useful for first time users who are interested to try GSISSH-TERM. For regular usage, the webstart method is encouraged.

1) GSISSH-TERM as a Java webstart application
To run GSISSH-Term as a Java webstart application, you need to have Java webstart (javaws) installed on your machine. Java webstart is now included in the Java Runtime Environment (JRE) as part of your Java SE 6. You can also download an older standalone version [here]. However, the latest version is always encouraged.

To install and start GSISSH-Term via Java webstart, simply click on .

For your security, the GSISSH-Term webstart application is signed with 2 certificates. A "Warning - Security" window, similar to this one here will be displayed.

To verify that you are indeed using and downloading the version from LRZ, please click on the "More Information..." link. Depending on the version of Java you are using, the user interface may differ slightly. Another window will appear, please click on the link "Certificate Details...". Verify that the certificate information is as such:
Issuer: CN=DFN-Verein PCA Grid - G01, OU=DFN-PKI, O=DFN-Verein, C=DE
Subject: CN=Siew Hoon Leong, OU=Leibniz-Rechenzentrum, O=GridGermany, C=DE

The second certificate prompt will request for you to accept a certificate from "The Legion of the Bouncy Castle".

To verify, make sure that the certificate information is as such:
Issuer: CN=JCE Code Signing CA, OU=Java Software Code Signing, O=Sun Microsystems Inc, L=Palo Alto, ST=CA, C=US
Subject: CN=The Legion of the Bouncy Castle, OU=Java Software Code Signing, O=Sun Microsystems Inc

2) GSISSH-TERM as a web browser applet
To run GSISSH-Term from the web browser as an applet, please install Java Runtime Environment (JRE) 1.5 or higher installed. If you have multiple versions of Java on your system, the default version must be 1.5 or higher.

3) GSISSH-TERM from source
A customised version of the source catering to LRZ, IGE, PRACE and DGrid users can be downloaded here. Alternatively, you can download the original version from GSI-SSHTerm Application project on sourceforge.

$JAVA_HOME must be set to the correct Java installation directory. Please kindly note that to compile and install GSISSH-TERM from source, you have to download and use Java Standard Development Kit (JSDK) 1.5 or higher.

For Linux/Unix Users

To compile and generate the GSISSH-Term application:

cd sshtools
./make.sh

To run:

cd sshtools/release/GSI-SSHTerm-{version}/bin
./sshterm.sh

For Windows Users

To compile and generate the GSISSH-Term application:

cd sshtools
./make.bat

To run:

cd sshtools/release/GSI-SSHTerm-{version}/bin
./sshterm.bat

User Guide

The following window will be shown when GSISSH-Term is initiated (either via Java webstart or as a desktop application):

To create a new connection, select "File" -> "New Connection" or the shortcut icon "Create a New Connection" (first icon from the left). The following window will be displayed:

To configure a new connection, select the "Advanced" button. In the "Host" tab, please input the following information:

For SuperMIG grid users: Hostname: supzero.lrz.de Port: 2222 Username: {Can be left empty} Use default values for all others.

For linux cluster grid users: Hostname: lxgt2.lrz-muenchen.de Port: 2222 Username: {Can be left empty} Use default values for all others.

For PRACE users: (gsissh door nodes) Site: LRZ Hostname: supzero.lrz.de Port: 2222 Username: {Can be left empty} Use default values for all others. Site: CINECA Hostname: grid.sp6.cineca.it Port: 2222 Username: {Can be left empty} Use default values for all others.	Site: SARA Hostname: huygens.sara.nl Port: 2222 Username: {Can be left empty} Use default values for all others. Site: RZG Hostname: vip001i.rzg.mpg.de Port: 2222 Username: {Can be left empty} Use default values for all others.

Note: For PRACE user, you will need to register your static ip. Please contact grid-admin@lists.lrz.de

Now select the "Connect" button. You will be prompted to enter your "Grid Certificate Passphrase". Enter the passphrase of your grid certificate and click "Ok" or just hit the "Enter" key of your keyboard.

You are now log in to LRZ's grid. Welcome!

When you exit from GSISSH-Term, you will be prompted as follows.:

Please note that if you have a SLCS certificate, your SLCS certificate will be permanently deleted if you select "Yes". You would have to regenerate a new SLCS certificate if you want to use GSISSH-Term again. For all other users, you will be prompted your certificate passphrase when you use GSISSH-Term again. Deleting your proxy certificate is a good way to reduce the risk of your account from being compromised, in particular when using a shared network/file system environment.

If you face any problems, please contact grid-admin@lists.lrz.de

Other Authentication methods supported by GSISSH-Term:

If you choose to use a PKCS12 (.p12) keys, Browser or MyProxy authentication method, you might see the following/similar error message window.

In this case, you need to install two additional jar files named local_policy.jar and US_export_policy.jar, from Sun (watch out: files with identical names but different content are already present on your local computer!). A copy of these files, providing a subset of the supported functionalities (only supporting up to 512 bit security, but not 1024 bit encryption), is already included in your local JDK and JRE. However, the complete version is not provided directly due to import control restrictions. To use a PKCS12 file, the complete version is necessary. Please kindly download the following two files and replace your local copies of these files with the new ones provided by the following links:

[Java(TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 5.0] for JDK/JRE 1.5
[Java(TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6] for JDK/JRE 1.6
[Java (TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7] for JDK/JRE 1.7

Extract the two jar files and copy them to

{JRE_installed_directory}/lib/security if JRE is installed
{JDK_installed_directory}/jre/lib/security if JDK is installed

Authentication using Browser Certificate Store

Certificates imported in browsers, Safari & Chrome (Mac with Keychain Access), Firefox/Mozilla (Linux & Windows) and Internet Explorer (Windows), are supported by GSISSH-Term. To authenticate yourself by using the Certificate Store in your browser, please click on the "Use Another Method" button in the following window

or you can set the authentication method to "Browser" by selecting the "GSI Defaults" tab of the "Connection Profile" window. For the "Authentication Order", please select "Browser" to use. Only browsers that are supported and installed on your system will be displayed. Now, select the "Connect" button.

For Firefox/Mozilla browser (Linux & Windows)

Please enter the "master password" of your Mozilla/firefox and not the passphrase of your grid certificates in the above window.

For Safari and Chrome browser (Mac only-> via Keychain access)

Select either "Allow" or "Always Allow" based on your personal preference.

You are now log in to LRZ's grid. Welcome!

MyProxy server

LRZ provides a MyProxy server for users to store their grid credential. The users can retrieve their respective proxy credentials from the MyProxy server without worrying about managing their private keys and certificates. MyProxy server can be used to delegate credentials to services (e.g. gsissh) on their behalf. For more information, please refer to http://grid.ncsa.uiuc.edu/myproxy/

Before you can use MyProxy server, you have to store a copy of your credential in the server. Please refer to the following page MyProxy for instructions on how to store your grid credential at LRZ's MyProxy server. Note that MyProxy server is open to all for use.

GSISSH-Term provides authentication via MyProxy server. To logon to LRZ using myproxy server:

Select the "GSI Defaults" tab of the "Connection Profile" window. Please refer to the instruction on how to get to the "Connection Profile" window. For the "Authentication Order", please select "Other Methods" to use. In the "Authentication Defaults" section, please configure for "MyProxy" as follows:

UserName: {Your username at LRZ}
Host: myproxy.lrz.de
Port: 7512

Click on the "Connect" button. The following window will be shown.

In the "Retrieve Credentials from MyProxy" section, please enter your MyProxy passphrase. Click the "use MyProxy" button.

You are now logged in to LRZ's grid. Welcome!

Userful Tools in GSISSH-Term

File Transfer via GSISSH-Term

GSISSH-Term provides a SFTP client for secure file transfer. Select "Tools"->"SFTP Session". A new window containing the "SFTP Session" will be shown. Upload or download files by selecting the "File-> Upload Files" or "File->Download".

MyProxy Tool

Our customised version provide a simple MyProxy Tool for you to upload, check and remove your credential to/from a myProxy server. You can launch MyProxy Tool by selecting "Tools"->"MyProxy Tool".

New Terminal Session

You are also allowed to start a "Terminal Session" via GSISSH-Term by selecting "Tools"->"Terminal Session".

XForwarding

GSISSH-Term by default enables XForwarding. If you are using GSISSH-Term from a Unix/Linux machine, you should be able to initialise applications like Totalview at LRZ without changing any configurations. If you are using a Windows machine, you have to install a XServer to enable XForwarding. We recommend the open source licensed XMing. A free copy can be downloaded at the following link [here]. Install the package "Xming" and start this application before GSISSH-Term.

For MAC OS X users who experience difficulties with XForwarding, please start the "X11 Preferences" window and set the options as follows.:

General Useful links

Tips

To check Java version: In your terminal window or MS-DOS window, please type the following command.
java -version
To create ".globus" folder in Windows, simply use the following command in MS-DOS window.
md .globus
or
mkdir .globus

For your security, it is encouraged that you modify the access rights of your .globus directory and certificates as follows.:
Unix/Linux:
chmod 700 ~/.globus
chmod 400 ~/.globus/*.pem

Please use only printable ASCII characters for your certificate(keystore) passphrase. If you have used unprintable characters, please kindly change your passphrase and replace your userkey.pem with the following commands on a Unix/Linux/Mac machine:
mv userkey.pem userkey.pem.old
openssl rsa -in userkey.pem.old -des3 -out userkey.pem

To convert your "userkey.pem" and "usercert.pem" to PKCS12 format, use the following command on a Unix/Linux/Mac machine:
openssl pkcs12 -export -in usercert.pem -inkey userkey.pem -out usercred.p12

To convert your PKCS12 keystore (e.g. usercred.p12) to PEM format, use the following commands on a Unix/Linux/Mac machine:
openssl pkcs12 -in usercred.p12 -out usercert.pem -clcerts -nokeys
openssl pkcs12 -in usercred.p12 -out userkey.pem -nocerts

To convert your PEM encrypted private key (e.g. usercert.key) to pre Openssl 1.0.x compatible format, use the following commands on a Unix/Linux/Mac machine:
mv userkey.pem userkey.pem.old
openssl rsa -in userkey.pem.old -des3 -out userkey.pem

If you notice strange characters while using the delete and/or backspace keys on some machines, e.g. IBM AIX OS, in your shell, you can set your $HOME/.inputrc as such:
"\e[3~": delete-char # this is actually equivalent to "\C-?": delete-char # VT "\e[1~": beginning-of-line "\e[4~": end-of-line # kvt "\e[H":beginning-of-line "\e[F":end-of-line # rxvt and konsole (i.e. the KDE-app...) "\e[7~":beginning-of-line "\e[8~":end-of-line More information is available at the following site

If you face any problems, please contact grid-admin@lists.lrz.de