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.

Download GSISSH Term

(For security reasons MacOS X Safari users will have to manually start the downloaded file jws.jnlp by double clicking it.)

NewsNews/Updates

  • Version 2.2.1 was released on 18 April 2016
    • Download required CA certificates and VOMS from HTTPS servers.
    • Update signing policy for JNLP.
  • Known problems
    • Browser authentication only works on Mac OSX with Keychain Access. Firefox and IE browser authentications are broken.
    • Connection on Windows is slow. Loading of CA's truststores, crl and such is taking a long time on Windows.

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 (all EUGridPMA CA certificates) into the appropriate local folders. As such, users no longer need to be concerned with the set up of the CA certificates.

For Oracle Java 7 users with update 21 onwards, you will see the following security prompt upon launching the web start version.

Oracle Java 7 security prompt

You can select the checkbox "Do not show this again for apps from the publisher and location above" and click on "Run". If you do so, you will get rid of this warning message permanently. For security reasons, we recommend that you verify the certificate details before doing so. This is to ensure you are installing the LRZ's distribution. Details on how to do so can be found in the FAQ section.

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

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. For users with firewall issues while using the webstart or applet version, you can also download the precompiled version. Finally, for advanced users, you might prefer to download and install the source. Both the precompiled and source versions provide a ".sh" or ".bat" executable on your local machine.

For the first three methods, as java webstart application, applet and precompiled versions, you will need Java Runtime Environment (JRE) 1.7 or higher installed to run the application. For the fourth method, you will be required to install Java Development Kit (JDK) 1.7 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 as it allows you to automatically update to the latest version.

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

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

For your security, the GSISSH-Term webstart application is signed with a Oracle Java recognised commercial root CA (Deutsche Telekom Root CA2) certificate. A "Warning - Security" window, similar to this one here will be displayed.

Signature

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 "More Information". Verify that the certificate information is as such:
Issuer: CN=LRZ-CA - G01, OU=LRZ-CA, O=Leibniz-Rechenzentrum, L=Muenchen, ST=Bayern, C=DE
Subject: CN=PN: Siew Hoon Leong - CodeSigning, OU=Leibniz-Rechenzentrum, L=Muenchen, ST=Bayern, C=DE

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.7 or higher installed. If you have multiple versions of Java on your system, the default version must be 1.7 or higher.

3) GSISSH-TERM from source

A customised version of the source catering to LRZ, DGrid, IGE, PRACE and EGI users can be downloaded here.

$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.7 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):

mainWin

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:

new connection

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

For SuperMUC grid users:
Hostname (Thin Node - bypass firewall): gridmuc.lrz.de
Hostname (Thin node): supermuc.lrz.de
Hostname (Fat node): supermuc-fat.lrz.de
Port: 2222
Username: {Can be left empty}
Use default values for all others.

Please beware that neither gsiscp nor gsisftp are available on gridmuc.lrz.de. The resource can only be used to open an interactive shell to SuperMUC without any possibility to perform a file transfer to or from the supercomputer.
 
 
For linux cluster grid users:
Hostname: lxlogin1.lrz.de, lxlogin2.lrz.de, lxlogin3.lrz.de or lxlogin4.lrz.de
Port: 2222
Username: {Can be left empty}
Use default values for all others.
 
For PRACE users: (gsissh door nodes)
Site: LRZ
Hostname (Fat node): supermuc-fat.lrz.de
Hostname (Thin node): supermuc.lrz.de
Port: 2222
Username: {Can be left empty}
Use default values for all others.

Site: CINECA PLX
Hostname: gssh.plx.cineca.it
Port: 2222
Username: {Can be left empty}
Use default values for all others.

Site: SARA
Hostname: int1-bb.cartesius.surfsara.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.
For EGI users:
Site: LRZ
Hostname: lxlogin1.lrz.de, lxlogin2.lrz.de, lxlogin3.lrz.de or lxlogin4.lrz.de
Port: 2222
Username: {Can be left empty}
Use default values for all others.

Site: Others
If you are using a voms enabled resource, refer to the voms section for more information.

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

connProfileHost

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.

passphrasePrompt

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

welcomeScreen

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

exitAlert

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.

error

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:

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.

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

You will have to modify the access control of your certificate key to allow Safari and Chrome browser to use the certificate keystore in Keychain Access. To do so, start the "Keychain Access" app. Select the "Keychains:" "login" and the "Category" "Keys". Right click on your certificate key and select option "Get Info". Select "Access Control" tab of the newly opened window as shown below. You can either "Allow all applications to access this item" or add "Safari" or "Chrome" to be one of the application under "Always allow access by these applications"

MAC Access Control

To authenticate yourself by using the Certificate Store in your browser, please click on the "Use Another Method" button in the following window.

Prompt

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.

browserConfig

For Firefox/Mozilla browser (Linux & Windows)

passphrasePrompt

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)

macBrowserAlertWin

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

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

welcomeScreen

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:

myproxyProfile

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.

Authentication

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!

welcomeScreen

Useful 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 double-clicking on the file you would like to download. Downloaded file can be found in your home directory.

Note: SFTP is not supported via gridmuc.lrz.de.

Globus Online Tool

Our customised version provide a simple (drag and drop) "Globus OnlineTool" for you to manage and transfer your files via the Globus Online service (Amazon cloud based GridFTP service). You would need to have a Globus Online account and associate this account with your certificate. To manage files from your local laptop or workstation, please install Globus Connect on the appropriate local machine. Globus Connect is an easy to install client-side GridFTP server.

GlobusOnlineTool

New Terminal Session

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

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

MyProxyTool

This tool now also supports the generation and upload of voms-enabled proxy.

You can generate and upload a voms-enabled proxy locally or remotely. The "local" method uses the voms configuration (containing both EGI, IGE and any other VOs you might have added via the VO management tool) that is automatically updated from EGI portal. The "remote" method uses the voms configuration that the MyProxy server providers provide.

The "remote" method is recommended for users who have firewall issues when attempting to contact the VOMS servers. For users who have firewall issues when connect to a MyProxy server, you can use the special tunneling service available at LRZ's my proxy server. Simply use the following configuration:

Server:  myproxy.lrz.de
Port: 21

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

X11 Preferences

Using VOMS enabled GSI-SSHTerm

Our customised GSISSH-Term also supports VOMS but is turned off by default. To turn it on, select the "Enable VOMS Support" checkbox in the "Connection Profile"'s "Host" tab as shown below:

voms

Click on the "Connect" button. You will be prompted with the following alert window. Two VOMS enabled proxy format, "RFC Impersonation" and "Legacy" are currently supported. Please choose the appropriate format and select "Yes".

voms_enabled_alert

Depending on your selected authentication method, you will be prompted with a passphrase window or proceed to the following window directly.

voms-select-vo

For example, if you are from the 'aegis' vo, select "aegis" (double-click);.

voms_vo_selected

To generate a VOMS enabled proxy, click on the button "voms-proxy-init" at the bottom of the window.

For your convenience, a "VO Management Tool" is available in the menu "Tools" You can also add additional VO configuration that is not in EGI or IGE via this tool. The appropriate .lsc file and vomses line will be automatically added. Please contact your respective VO manager for the required VO information.

VO Management Tool

You should now be connected to your VOMS resource. Have fun!

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:
    Windows/Linux/Mac:
    Use GSISSH-Term: Select Tools->Keygen->Action: "Convert PEM to PKCS12"

    PEM to PKCS12 conversation

    or
    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

FAQ

Can I modify where to download the CA certificates?
Yes. Add the following line to the file {Home directory}/.sshterm/GSI-SSHTerm_EGCF_for_PRACE_EGI_LRZ.properties
sshterm.myproxy.cacert.url=http://winnetou.sara.nl/prace/certs/globuscerts.tar.gz
Note: The compressed file with the CA certificates must be in "tar.gz" or "tgz" format.

How can I check the certificate chain and verify that I am installing the LRZ's version?

Oracle Java 7 security prompt

Click on the text "More Information" in the prompt above. This will open the "More Information" alert prompt.

Oracle Java 7 security prompt - More Information

Select "View Certificate Details". You should see the following certificate details.

Oracle Java 7 security prompt - Certificate Details

At the top of the certificate chain should be a certificate with the following information:
Subject=CN=PN: Siew Hoon Leong - CodeSigning, O=Leibniz-Rechenzentrum, L=Muenchen, ST=Bayern, C=DE SHA1 Fingerprint=FB:32:58:5A:3D:3A:1A:42:62:44:A7:AA:FF:73:F9:7A:E2:90:A8:20

"DFN-Verein PCA Global - G01" certificate should have the following information:
Subject=CN=DFN-Verein PCA Global - G01, OU=DFN-PKI, O=DFN-Verein, C=DE SHA1 Fingerprint=8E:8F:B4:64:68:4B:34:7F:A2:E6:46:68:63:41:B1:F1:AE:03:6E:66

"LRZ-CA - G01" certificate should have the following information:
Subject=EMAILADDRESS=pki@lrz-muenchen.de, CN=LRZ-CA - G01, OU=LRZ-CA, O=Leibniz-Rechenzentrum, L=Muenchen, ST=Bayern, C=DE SHA1 Fingerprint=F0:28:8F:DA:C6:3A:F7:9A:31:9A:E9:72:F3:95:09:0E:A3:EF:E9:45

At the end of the chain, "Deutsche Telekom Root CA2" certificate should have the following information:
Subject=CN=Deutsche Telekom Root CA 2, OU=T-TeleSec Trust Center, O=Deutsche Telekom AG, C=DE SHA1 Fingerprint=85:A4:08:C0:9C:19:3E:5D:51:58:7D:CD:D6:13:30:FD:8C:DE:37:BF

After verifying the certificate details, you can select the checkbox "Do not show this again for apps from the publisher and location above", this alert prompt will stop showing up in the future.

now warning

Projects


The following projects/communities are using/recommending this version of GSISSH-Term:

Running

Ended

Training materials

EGI webinar: VOMS support, MyProxy Tool and Globus Online Tool in GSI-SSHTerm (23rd Oct 2013)

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