Skip to content. | Skip to navigation

Personal tools
Log in

DIstributed Computing Environments (DICE) Team
We are a group of computer scientists and IT experts from the Department of Computer Science AGH and ACC Cyfronet AGH. We are a curiosity- and research-driven team, specializing in large-scale distributed computing, HPC, Web and Cloud technologies. We develop new methods, tools and environments and we apply these solutions in e-Science, healthcare and industrial domains.


Sections
You are here: Home Downloads GridSpace releases 2.5.0 GridSpace 2.5.x Administrator Manual

GridSpace 2.5.x Administrator Manual

This document is targeted at administrators who conduct processes of installation, deinstallation and maintenance of GridSpace2 Platform, more precisely, its version 2.5.x.

This document is organized in the following sections:

  1. Deployment Diagram
  2. Installation
  3. Configuration
  4. Testing
  5. Maintenance
  6. Deinstallation

Deployment Diagram

This section is intended to give understanding of deployment of GridSpace2 Platform as a whole. The platform is constituted by:

  • Experiment Workbench (EW) - a web application based on Java EE Platform relying on Java Servlets 2.5 specification, deployable in a web container such as Tomcat or Jetty, which supports this version of the specification. Serves as a web portal that provides users with access to all the functionality of GridSpace2.
  • Executor - a host (e.g. personal computer, supercomputer) or whole environment (e.g. cluster, grid) accessible through some gateway host, where actual computations take place. It's location may be, and likely is, remote with respect to the Experiment Workbench. Experiment Workbench can have multiple Executors configured.

Executor is assumed to be already existing and operable, made available to the community of users who are given with the accounts on it. We presume the Executor is managed autonomically and independently and it's not covered by this manual. However, some aspects induced by GridSpace2 need to be born in Executor administrator's mind.

  • The idea of GridSpace2 is to non-intrusively overlay the Executor with EW. EW is a web application that connects to the Executor through the set of secure protocols such as SSH, SCP and SFTP. The implication of such an architecture is that many user sessions to Executor are established through the proxy of EW and this should be taken into account when e.g. specifying firewall settings. E.g. policy regarding blacklisting IP from which several authentication failures occur should be relaxed.

  • It is highly recommended to deploy EW in application container with certificate installed and to allow HTTPS access only. Below, you will find Securing your Experiment Workbench section with details on how to do this.

 

The diagram below shows the deployment diagram of the GridSpace2.

                        +----------------------+
                        |      Web Browser     |
                        +----------------------+
                                    |
                                    | HTTPS
                                    |
                        +----------------------+
                        | Experiment Workbench |
                        +----------------------+
                                    |
                                    | SSH/SCP/SFTP
                                    |
                            +-------------+
                            |   Executor  |
                            +-------------+

Back to the top

Installation

Having already existing and operable EEE, installation of GridSpace2 reduces to installation of EW. The EW is provided as a web application bundle - a war file. It is deployable in the web container of a choice that supports the following:

  • Java 1.6
  • HTTP/1.1 RFC2616
  • Java Servlets API 2.5

The sample web containers that meet these requirements are:

  • Apache Tomcat from version 6.0
  • Codehaus Jetty from version 6.1

The installation actually depends on the target container, however it's always about deploying war bundle into the container.

For the sake of the example, Tomcat enables many ways for deploying as described here.

Step-by-step installation in Apache Tomcat

This guide describes how to install Experiment Workbench on a linux machine, however it should be also useful for user using different platforms. It is assumed that Java (JRE or JDK), tar and wget are already installed on the system. Apache Tomcat 6.0.29 is used since it is the most recent stable distribution at the moment of writing this guide.

  1. Download binary Apache Tomcat archive, e.g.
    wget http://apache.privatejetscharter.net//tomcat/tomcat-6/v6.0.29/bin/apache-tomcat-6.0.29.tar.gz
  2. Extract the archive
    tar zxvf apache-tomcat-6.0.29.tar.gz
  3. Download EW 2.5.x war file, replacing x with the most recent bugfix version of EW
    wget http://dev-gs.cyfronet.pl/mvnrepo/cyfronet/gs2/ew/2.3.0/ew-2.5.x.war
  4. Deploy EW in Tomcat
    cp ew-2.5.x.war apache-tomcat-6.0.29/webapps/
  5. Start Tomcat container
    cd apache-tomcat-6.0.29/bin/
    ./startup.sh
  6. Open your browser on http://localhost:8080/ew-2.5.x. You should see GridSpace 2 main page.

Securing your Experiment Workbench with HTTPS

Since endusers enter theirs credentials in Experiment Workbench in order to access EEE all communication with EW should be done using HTTPS protocol. Therefore application container should have a certificate installed and be properly configured. This document will guide you how to configure HTTPS protocol for EW in Apache Tomcat 6.0. The following is based on Apache Tomcat 6.0 SSL how to.

Prepare the Certificate Keystore

Apache Tomcat can use a keystore in JKS,PKCS11 or PKCS12 format. Choose one of the following methods to create a tomcat keystore.

  1. Importing an exisitng certificate issued by CA that is untrusted by default
    openssl pkcs12 -export -in mycert.crt -inkey mykey.key -out mycert.p12 -name tomcat -CAfile myCA.crt -caname root -chain
  2. Importing an exisitng certificate issued by trusted CA
    openssl pkcs12 -export -in mycert.crt -inkey mykey.key -out mycert.p12 -name tomcat
  3. Creating new JKS keystore with a single self-signed Certificate
    keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore
  4. Creating a CSR to a CA and importing obtained certificate
    • Creating a local certificate
      keytool -genkey -alias tomcat -keyalg RSA -keystore <your_keystore_filename>
    • Creating certificate signing request
      keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <your_keystore_filename>
    • Importing chain certificate
      keytool -import -alias root -keystore <your_keystore_filename> -trustcacerts -file <filename_of_the_chain_certificate>
    • Importing obtained certificate
      keytool -import -alias tomcat -keystore <your_keystore_filename> -file <your_certificate_filename>

Checking if CA is trusted (default keystore password is changeit)

$JAVA_HOME/jre/lib/security$ keytool -list -keystore cacerts

If a CA is listed by the above command it means that CA is trusted.
Converting PKCS12 to JKS (optional)

keytool -importkeystore -destkeystore tomcat.jks -srckeystore tomcat-keystore.p12 -srcstoretype PKCS12

Configure HTTPS Connector in Tomcat

Tomcat SSL connector defined in tomcat_dir/conf/server.xml.

<Connector 
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="keystore_path" keystorePass="keystore_password"
           clientAuth="false" sslProtocol="TLS"/>

By default SSL connector is present in Tomcat distribution so you should only uncomment it and adjust keystoreFile and keystorePass attributes. HTTP access to EW webapplication should be disables by commenting HTTP connector (notice <!-- and -->).

<!--
    <Connector executor="tomcatThreadPool"
               port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" />
-->

In order to apply changes Tomcat must be restarted.

Back to the top

Configuration

EW is configured during startup by the WEB-INF/config/ew.xml file, which is shipped with default contents together with the EW bundle. After the workbench is started the configuration can be updated by using the configuration page available after clicking the Configure... link present in the top right-hand corner of the main page. Access to this page is password-protected. If the workbench is run for the first time default value of the password is given at the configuration login page.

After a successfull login a configuration session is established and a configuration page is displayed. To disable the configuration session click the Logout button. To go back to the EW's main page click the Back to main page link in the top right-hand corner of the page. The configuration page is divided into three sections, which are described below.

Password and Logout section. This section consists of the Logout button, password change form and the logo upload form. When the Logout button is clicked the configuration session is invalidated and the browser navigates back to the configuration login page. The password change form can be used to change the current configuration password. No restrictions are enforced, except for empty values, so be careful to use strong passwords.

Logo section. The logo upload form can be used to upload a deployment specific logo. Current logo is displayed.

Configuration tabs. This section can be used to view the current configuration of EW and to update it during runtime. The tabs displays contents of EW configuration files, which can be updated and saved at runtime by clicking the Update button. Another way to update the configuration file is to upload the file by using the configuration upload form and by clicking the Upload button. The contents of the configuration text area will be updated automatically with the uploaded contents. If you are granted direct access to EW web application files you can as well edit the files directly. They are placed in WEB-INF/config folder. Below you'll find the example contents of all the configuration files.

Tab Experiment Workbench, file WEB-INF/config/experimentWorkbench.xml:


<experimentWorkbench configurationVersion="1.0" maintenance="false">

<!-- The page title to appear in web browser -->
<pageTitle>[fill in]</pageTitle>

<!-- name of a project/organization/person this installation is dedicated to -->
<target>[fill in]</target>

<!-- short descirption of a target -->
<targetDescription>[fill in]</targetDescription>

<!-- link to the site of a target -->
<targetLink>[fill in]</targetLink>

<!-- link to the issue tracker where users can report problems -->
<issueTrackerUrl>[fill in]</issueTrackerUrl>

<!-- Google Analytics ID to track web site traffic, or leave empty to disable tracing -->
<googleAnalyticsID>[fill in]</googleAnalyticsID>

<!-- Put here YouTube movie embed code, or leave empty to disable it -->
<targetMovieEmbedCode>[fill in]</targetMovieEmbedCode>

<!-- Self-check mechanism configuration -->
<selfCheck>
<!-- DN of certificate of party allowed to run self-check test -->
<authorizedDn>[fill in]</authorizedDn>
<!-- ... and another one -->
<authorizedDn>[fill in]</authorizedDn>
<!-- Executor to be used to perform self-check (must be SSH-executor configured in gridspace.xml file)-->
<testHost>[fill in]</testHost>
<!-- SSH port of test executor -->
<testHostPort>[fill in]</testHostPort>
<!-- Account to be used in tests -->
<testUserName>[fill in]</testUserName>
<!-- Password to be used when loggin in to test executor -->
<testPassword>[fill in]</testPassword>
<!-- Password to authorize running self-check -->
<testAccessPassword>[fill in]</testAccessPassword>
</selfCheck>

<!-- Folder where to store information about released experiments -->
<collageExperimentStoragePath>.gs2/releases</collageExperimentStoragePath>

<!-- Specifies whether it's allowed to create private experiment releases  -->
<allowPrivateReleasing>true</allowPrivateReleasing>
<!-- Specifies whether it's allowed to create experiment releases in user's main group scope -->
<allowMainGroupReleasing>true</allowMainGroupReleasing>
<!-- Specifies whether it's allowed to create public releases -->
<allowPublicReleasing>true</allowPublicReleasing>
<!-- Specifies what DOI publisher id to be used when releasing experiments -->
<defaultDoiPublisherId>0000</defaultDoiPublisherId>
<!-- File that stores mapping between user ids and DOI publisher ids -->
<doiMappingFileName>.gs2/dois.properties</doiMappingFileName>
<!-- Folder where openers are stored -->
<openersDirectory>.gs2/openers</openersDirectory>
<!-- The maximum allowed size of asset to be displayed in released experiment -->
<maximumAssetSize>3145728</maximumAssetSize><!-- 3MB -->
<!-- The example experiment release -->
<exampleExperimentRelease doi="10.0000/1336658335205" />

<!-- Specifies mapping between file extensions and MIME types -->
<overrideMimeMappings>
<entry><key>dot</key><value>text/plain</value></entry>
</overrideMimeMappings>

</experimentWorkbench>

Tab Executors, file WEB-INF/config/gridSpace.xml:

<?xml version="1.0" encoding="UTF-8"?>

<gridSpace configurationVersion="1.0">

<interpreter id="bash" name="Bash" arguments="--noprofile --norc"
manualUrl="http://www.gnu.org/software/bash/manual/bashref.html"
executionType="INTERACTIVE">
<prompt value="$ " />
<prompt value="&gt; " />
<envVar name="PS1" value="$ " />
</interpreter>

<executorFactory id="SSH-localhost" name="SSH@localhost" loginType="USERNAME_PASSWORD"
accountRequestUrl=""
executorClass="cyfronet.gs2.sshexecutor.SSHExecutor">
<description>This is just for testing purposes.</description>
<property name="portNumber" value="22" />
<property name="hostName" value="localhost" />
<executable interpreter="bash" cmd="/bin/bash" />
</executorFactory>

</gridSpace>

Tab Provenance, file WEB-INF/config/provenance.xml:

<?xml version="1.0" encoding="UTF-8"?>

<provenance>
<svnRepositoryUrl>[fill in]</svnRepositoryUrl>
<svnRepositoryPassword>[fill in]</svnRepositoryPassword>
<fileServerName>[fill in]</fileServerName>
<fileServerUsername>[fill in]</fileServerUsername>
<fileServerPassword>[fill in]</fileServerPassword>
<fileServerUrl>[fill in]</fileServerUrl>
<sparqlEndpoint>[fill in]</sparqlEndpoint>
</provenance>

Tab Trust store, file WEB-INF/config/keystore.jks - this is used to manage EW's truststore. It allows for certificate browsing, uploading and deleting. Current truststore certificates are listed as a vertical list with basic information for each of the imported certificate. To delete a particular certifiate click the Delete link next to it. To upload a new certificate provide the alias and the certificate file in the certificate upload form and click the Upload certificate button.

Tab DOI, file as specified in experimentWorkbench.xml file - enables management of a mapping between user ids and DOI published ids.

Back to the top

Testing

In order to test the new configuration start Tomcat and use the following python code by replacing given placeholders with valid values:

# -*- coding: utf-8 -*-

import httplib, urllib

params = {}
headers = {'Content-Type' : 'application/x-www-form-urlencoded'}

# From the below listed option choose one and comment the other ones:

# a) in the case of HTTPS-secured Experiment Workbench instance with password-based instead of certificate-based client authentication
c = httplib.HTTPSConnection('{host}', {port})
params['experimentWorkbenchPassword'] = '{workbench_passwd}'

# b) in the case of HTTPS-secured Experiment Workbench instance
c = httplib.HTTPSConnection('{host}', {port}, '{path-to-user-key-pem-file}', '{path-to-user-cert-pem-file}')

# c) in the case of GSI/HTTPS-secured Experiment Workbench instance
# e.g. c = httplib.HTTPSConnection('gs2.yourorganization.org', 8443, '/tmp/x501up_u501', '/tmp/x501up_u501')
c = httplib.HTTPSConnection('{host}', {port}, '{path-to-user-proxy-pem-file}', '{path-to-user-proxy-pem-file}')

c.request('POST', '/test', urllib.urlencode(params), headers)
r = c.getresponse()
print(r.status)
d = r.read()
print(d)

This takes some time (up to about minute) for performing tests on given EW instance and prints test summary reports including failures (if any occured).

Back to the top

Maintenance

After the successfully installation of EW some things may happen that involve administrator's intervention, namely:

  • Configuration update - from time to time, as the Executor characteristic changes (e.g. new software is installed, host address changes). Then, administrator needs to change configuration as described in Configuration section.
  • Restart - sometimes, due to some circumstances, it is suggested to restart EW. In such case the administrator needs to reload the EW web application within the container.

Back to the top

Deinstallation

Deinstallation of GridSpace2 is confined to undeploying of EW from the web container.

Back to the top

NOTE! This web site uses cookies and similar technologies (if you do not change the browser settings, you agree to this).

cyfronet agh