GSI-SSHTerm
From NGSWiki
| Table of contents |
|
2.1 Bug tracking |
Introduction
GSI-SSHTerm is an easy to use Java program which supports Grid authentication. As it is written in Java it runs on most platforms including Windows, Linux and Mac OS. NGS have contributed towards the development of this tool.
The GSI-SSHTerm is availiable on the NGS website as a Java Webstart application. Information is available at http://ngs-test.nesc.ed.ac.uk/tools/gsisshterm or you can directly run/install it at http://tools.ngs.ac.uk/ngstools/.
The Quick Start Guide at http://ngs-test.nesc.ed.ac.uk/tools/gsisshterm/gsi-sshterm-application-help and the FAQ at http://ngs-test.nesc.ed.ac.uk/tools/gsisshterm/faq allows you to quickly get going with the GSI-SSHTerm.
This page details the more advanced features of the GSI-SSHTerm. These features make the GSI-SSHTerm easier to use regularly or enable it to be packaged for different user communities.
Not just a Terminal...
The GSI-SSHTerm is not just a terminal emulation program. Other built-in features include port forwarding, an SFTP client for securely transfering files, a secure VNC client and a key generation program. These tools are availiable from the Tools menu. Also the GSI-SSHTerm can be configured to set up X forwarding, through the Advanced Connection dialog box or configuration files (see below).
Support
Support for the GSI-SSHTerm is availiable from the NGS helpdesk (support@grid-support.ac.uk (mailto:support@grid-support.ac.uk)). This support is for UK academics using the core terminal functionality of the GSI-SSHTerm. We will give support, on a good-will basis, to users not in the UK or using other GSI-SSHTerm functionality (the built-in SFTP and VNC clients).
See the GSI-SSHTerm FAQ: http://ngs-test.nesc.ed.ac.uk/tools/gsisshterm/faq.
Usage
The GSI-SSHTerm is downloaded and run about 600-900 times each month from the NGS pages, and is used by a number of Grids, projects and resources:
- NGS (http://www.grid-support.ac.uk/content/view/81/195/)
- TeraGrid (http://grid.ncsa.uiuc.edu/gsi-sshterm/)
- NCSA (http://grid.ncsa.uiuc.edu/gsi-sshterm/)
- NWGrid (http://www.nw-grid.ac.uk/?q=nodes/uoli/starting)
- ICEAGE Training (http://www.iceage-eu.org/gsissh/index.cfm)
- NeSC Training (http://homepages.nesc.ac.uk/~gcw/NGS/gsissh-0.82/)
- SCARF (http://hpcsg.esc.rl.ac.uk/scarf/documentation/.grsthist:access.html:456C601C:3A976:10ED:=2FC=3DUK=2FO=3DeScience=2FOU=3DCLRC=2FL=3DRAL=2FCN=3Dduncan=20tooke:.html)
- LRZ (http://www.grid.lrz.de/)
Advanced Documentation
Bug tracking
The GSI-SSHTerm bug tracking system is located on SourceForge in the GSI-SSHTerm Application project (http://sourceforge.net/projects/gsi-sshterm).
- Submit a bug report http://sourceforge.net/tracker/?func=add&group_id=179202&atid=888198
- Submit a feature request http://sourceforge.net/tracker/?func=add&group_id=179202&atid=888201
If you wish to be notified about the request's process then log-on to sourceforge before submitting bugs or feature requests. Alternatively report bugs through the NGS helpdesk (support@grid-support.ac.uk (mailto:support@grid-support.ac.uk)).
Versions
From version 0.60 onwards the GSI-SSHTerm has increased by one minor version (e.g. from 0.60 to 0.61) on each release except when there were major new features, when the minor version has gone up to the next decade (e.g. 0.62 to 0.70). From version 0.90 minor bug-fix releases are to go up with a single letter suffix (e.g. 0.90->0.90a->0.90b...), the intention being to allow minor bug-fixes to be released more regularly.
It is hoped that the 0.9x series will represent a final hardening of the code and removal of any lingering bugs to allow a 1.0 release of the GSI-SSHTerm.
User Configuration
The GSI-SSHTerm can be configured in many different ways. This section describes the files which can be used by users, the options themselves are described in later sections.
Users can over-ride the settings which are set in their GSI-SSHTerm distribution through the use of the ~/.sshterm/GSI-SSHTerm.settings file. This file contains lines like:
name=value
For example:
sshterm.auth.order=param,proxy,cert,other
Lines begining with # are ingnored.
The ~/.sshterm/GSI-SSHTerm.properties file is used by the GSI-SSHTerm to store settings between sessions, like the last host and port used and the position of windows. Users don't normally edit this file.
The GSI-SSHTerm also allows you to over-ride settings from the configuration files in the Advanced New Connection dialog box. Per-connection settings can be saved and opened through the file menu.
Basic Authentication Settings
- Authentication Order: sets the order of methods that the GSI-SSHTerm tries to load your certificate.
- Name: sshterm.auth.order
- Default: sshterm.auth.order=param,proxy,cert,other
- Options:
- param - proxy included in <PARAM> tag on applet's webpage
- proxy - grid proxy stored on disk
- cert - usercert.pem/userkey.pem
- other - dialog box with MyProxy, PKCS12 and Browser options
- browser - certificate from web browser
- krb - Kerberos enabled MyProxy server (must be enabled - see below)
- Notes: GSI-SSHTerm will cycle through these options, it will not try any other ones that are not in the list.
- Default MyProxy server: Set the default MyProxy server.
- Name: sshterm.myproxy.defaults.hostname
- Default: sshterm.myproxy.defaults.hostname=myproxy.grid-support.ac.uk
- MyProxy port: Set the default port to connect to MyProxy servers on.
- Name: sshterm.myproxy.defaults.port
- Default:sshterm.myproxy.defaults.port=7512
- MyProxy username: Set the default username to use with MyProxy.
- Name: sshterm.myproxy.defaults.username
- Default: sshterm.myproxy.defaults.username=<value of user.name>
- Notes: This defaults to the username of the user. Don't set this in default.properties files.
- Default PKCS12 filename: Set the filename that appears in the PKCS12 Filename field of the Grid Authentication dialog box.
- Name: sshterm.pkcs12.defaults.file
- Default: sshterm.pkcs12.defaults.file=<No defualt value>
- Notes: Don't set this in default.properties files.
- Browser Profile to choose: Instruct the GSI-SSHTerm to always choose a certain browser (profile).
- Name: sshterm.browser.profile
- Default: sshterm.browser.profile=<No defualt value>
- Notes: If there is only one profile it will always be chosen. Don't set this in default.properties files.
- Browser DN to choose: Instruct the GSI-SSHTerm to always choose a certain DN when loading certificates from a browser.
- Name: sshterm.browser.dn
- Default: sshterm.browser.dn=<No defualt value>
- Notes: If there is only one DN it will always be chosen. Don't set this in default.properties files.
- Proxy type: Sets the type of proxy that will be generated by the GSI-SSHTerm.
- Name: sshterm.proxyType
- Default: sshterm.proxyType=prerfc
- Options:
- rfc - RFC compilent (GT4) proxy
- prerfc - Pre-RFC (GT3) proxy
- legacy - Legacy (GT2) proxy
- Proxy Liftime: Set the lifetime of proxies generated by the GSI-SSHTerm.
- Name: sshterm.proxyLength=
- Default: sshterm.proxyLength=12
- Notes: This can take any value between 1 and 240 hours.
- Delegation type: Set the type of delegation of your proxy that is performed once a connection has been made.
- Name: sssherm.delegationType
- Default: sssherm.delegationType=full
- Options:
- full - Full proxy delegation
- limited - Limitted proxy delegation
- none - No proxy delegation
- Proxy saving: this setting sets whether proxies created from Grid credentials are saved into the defualt proxy location for future use.
- Name: sshterm.proxy.save
- Default: sshterm.proxy.save=false
- Default connection ports: Sets the port that is used in the quick connection dialog box, and the first ever port value in the advanced connection dialog box.
- Name: sshterm.simple.connection.port
- Default: sshterm.simple.connection.port=2222
Single Sign On
The GSI-SSHTerm has the ability to request proxy certificates transparently from a kerberos-enabled MyProxy server. These settings here (except sshterm.krb5myproxy.username) would normally be set in a special site-SSO version of the GSI-SSHTerm.
- Enable/Disable Kerberos-enabled MyProxy support:
- Name: sshterm.krb5myproxy.enabled
- Default: sshterm.krb5myproxy.enabled=false
- Kerberos-enabled MyProxy server hostname:
- Name: sshterm.krb5myproxy.hostname
- Default: sshterm.krb5myproxy.hostname=myproxy-sso.grid-support.ac.uk
- Kerberos-enabled MyProxy server port (not configurable in GUI):
- Name: sshterm.krb5myproxy.port
- Default: sshterm.krb5myproxy.port=7513
- Kerberos KDC:
- Name: sshterm.krb5myproxy.kdc
- Default: sshterm.krb5myproxy.kdc=<value of $USERDNSDOMAIN>
- Notes: $USERDNSDOMAIN is only set in Windows. In UNIX it is expected that client machines will have a correct kerberos setup /etc/krb5.conf -- settings here will be picked up.
- Kerberos Realm:
- Name: sshterm.krb5myproxy.realm
- Default: sshterm.krb5myproxy.realm=<value of $USERDNSDOMAIN>
- Notes: $USERDNSDOMAIN is only set in Windows. In UNIX it is expected that client machines will have a correct kerberos setup /etc/krb5.conf -- settings here will be picked up.
- Kerberos Username:
- Name: sshterm.krb5myproxy.username
- Default: sshterm.krb5myproxy.username=<value of user.name>
Other settings
- Enable/Disable X Forwaring:
- Name: sshterm.xForwarding
- Default: sshterm.xForwarding=true
Re-distributing the GSI-SSHTerm
Obtaining the Source
The source for the GSI-SSHTerm is availiable from the GSI-SSHTerm Application project (http://sourceforge.net/projects/gsi-sshterm) on sourceforge. It is recomended that you download the current release (http://sourceforge.net/project/showfiles.php?group_id=179202) as a tar.gz file. There is also public CVS access (http://gsi-sshterm.cvs.sourceforge.net/gsi-sshterm/) if you wish to see the current development version.
Configuring Distributions
The GSI-SSHTerm provides the ability to configure a distribution with default settings for all users. This section looks at the build.properties and default.properties files, but further information on compiling in general can be found in the Compiling section.
build.properties
The build.properties file sets three options for the build process. It is a standard Java properties file, located in the main sshtools directory of the GSI-SSHTerm source distribution.
- build.site this sets the reported build location in the About box.
- default.properties.file sets the name of the file in sshtools/res/common which should be used as the default.properties file. This file is explained in the next section.
- version.suffix sets a version suffix to allow different configurations to be flagged.
"default.properties"
At compile-time the file sshtools/res/common/${default.properties} (where ${default.properties} is the file indicated in the buil.properties file is included in in the distribution. This sets the global options for the GSI-SSHTerm for the community. Users can over-ride these options using the files mentioned above and also in the Advanced Connection dialog box itself.
Two examples are configurations are given, one normal and one with kerberos SSO support enabled, in the source distribution these correspond to the default.properties and default.properties.kerberos properties files in sshtools/res/common.
Certificates
The GSI-SSHTerm automatically creates a ~/.globus/certificates directory for the user, copying the UK e-Sciece CA's root certificates and signing policy files. This enables the terminal to be used without any pre-setup (except Java). If you wish to distribute a copy of the GSI-SSHTerm with a different set of certificates then please change the contents of the "sshtools/res/certificates/" directory. You will then have to re-compile from source (see next section).
Compiling
The source for the GSI-SSHTerm is availiable from sourceforge http://sourceforge.net/projects/gsi-sshterm. If you want to distribute a copy with different settings (as described above) or with different certificates then you will need to compile the terminal from source.
In all cases you must set your $JAVA_HOME correctly to the installation directory of your Java installation. Your Java installation must be Java SDK 1.5 or greater.
The GSI-SSHTerm is compiled through the use of the "make" script, in the sshtools directory run:
- Linux
cd sshtools ./make.sh
- Windows
cd sshtools make.bat
this will create the GSI-SSHTerm application in "sshtools/release/GSI-SSHTerm-<version>" and this can be run using the following:
- Linux
cd sshtools/release/GSI-SSHTerm-<version>/bin ./sshterm.sh
- Windows:
cd sshtools/release/GSI-SSHTerm-<version>/bin sshterm.bat
Applet
To additionally compile the applet version and associated web pages use the command (the webpages are highly customised for the NGS webserver and will need editing before the webpages are useful):
- Linux:
cd sshtools ./make.sh all
- Windows XP:
cd sshtools make.bat all
To compile in other Windows environments change the os="Windows XP" entry at about line 207 of build.xml, to the OS name returned by the os.name Java property on your machine.
This requires you to setup the file password.properties in the base directory of the sshtools source, it should contain the following lines:
- keystore=/home/xxx/.keystore
- keystore.alias=theSigningCertificateKeyAlias
- keystore.pass=aLongPrivateKeyPassphrase
Note that it is suggested that the certificate and private key (in a java keystore) that is pointed to by the password.properties file is issued by a certification authority that the user is likely to already trust and has a subject name that describes you or your organisation. Please be careful about the security of the Java keystore and the password.properties file. This certificate should explicitly have "Object Signing" set in the X509v3 extensions.
This will compile the applet version and webpages to release/applet. To distribute the applet to a website upload all the files in the directory "sshtools/release/applet". Then open the index.html file in a browser.
Java Webstart
The following is example Java webstart files for the applet, you will need to edit them for your deployment. jws.jnlp is the main file that should be linked to.
jws.jnlp
<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+" codebase="http://www.grid-support.ac.uk/files/gsissh-new/" href="jws.jnlp">
<information>
<title>GSI-SSHTerm</title>
<vendor>Science and Technology Facilities Council</vendor>
<description>Java-based GSI-SSHTerm
</description>
<description kind="short">GSI-SSHTerm</description>
<description kind="tooltip">GSI-SSHTerm</description>
<homepage href="http://www.grid-support.ac.uk/content/view/81/62" />
<icon href="largessh.gif" />
<offline-allowed />
<shortcut oneline="false">
<desktop />
</shortcut>
</information>
<offline-allowed />
<security>
<all-permissions />
</security>
<resources>
<j2se version="1.5+" />
<jar href="SSHTerm-1.0.0.jar" />
<jar href="j2ssh-common-0.2.7.jar" />
<jar href="j2ssh-core-0.2.7.jar" />
<jar href="SecureTunneling.jar" />
<jar href="ShiFT.jar" />
<jar href="SSHVnc.jar" />
<jar href="cog-jglobus.jar" />
<jar href="commons-logging.jar" />
<jar href="cryptix32-signed.jar" />
<jar href="cryptix-asn1-signed.jar" />
<jar href="cryptix-signed.jar" />
<jar href="filedrop.jar" />
<jar href="jlirc-unix-soc.jar" />
<jar href="libbrowser.jar" />
<jar href="log4j-1.2.6.jar" />
<jar href="openssh-pk-1.1.0.jar" />
<jar href="puretls-signed.jar" />
<jar href="putty-pk-1.1.0.jar" />
<extension name="jce" href="jce.jnlp" />
</resources>
<application-desc main-class="com.sshtools.sshterm.SshTerm" />
</jnlp>
jce.jnlp
<?xml version="1.0" encoding="utf-8"?> <jnlp spec="1.0+" codebase="http://www.grid-support.ac.uk/files/gsissh/" href="jce.jnlp"> <information> <title>JCE JDK 1.3</title> <vendor>BouncyCastle</vendor> <offline-allowed /> </information> <offline-allowed /> <security> <all-permissions /> </security> <resources> <jar href="jce-jdk13-135.jar" /> </resources> <component-desc /> </jnlp>
Useful Libraries
Some of the libraries that have been developed as part of the GSI-SSHTerm project are availiable seperately:
- libbrowser : libraries to access Grid credentials stored in the user's browser.
- cog-jglobus - SSO extensions : a version of the cog-jglobus.jar library which includes SASL/Kerberos MyProxy support.
Please see GSI-SSHTermLibraries.
