= QCG Broker Client Installation =

[[PageOutline]] 


= Requirements =
* '''PL-Grid LDAP integration'''
 
The machine where the client is to be installed has to be configured to allow users to log in to the their "plg" accounts.
* '''Packages requirements'''. 

All packages required by QCG-Broker client will be automatically installed by YUM during the installation of qcg-broker-client package.
 * '''Java (>= 1.5)'''\\
* '''The X.509 certificate and key (signed by the Polish Grid CA'''

The certificate is optional and it is needed in the case when the dedicated gridFTP service is installed for the QCG client.
* '''trusted CA certificates'''

To enable secure communication between client and QCG-Broker service set of trusted CA certificates must be copied either into the `/etc/grid-security/certificates` directory or configured for every user.


For the PL-Grid project: Install Polish Grid and PL-Grid Simple-CA certificates:

-Add appropriate YUM repositories
{{{
#!div style="font-size: 90%"
{{{#!sh
cat > /etc/yum.repos.d/plgrid.repo << EOF
[PLGRID-general]
name=PLGRID general packages repository
baseurl=http://software.plgrid.pl/packages/general/
enabled=1
metadata_expire=300
gpgcheck=0
EOF
}}}
}}}

{{{
#!div style="font-size: 90%"
{{{#!sh
cat > /etc/yum.repos.d/eugridpma.repo << EOF
[EUGRIDPMA-igtf]
name=EUGRIDPMA igtf repository
baseurl=https://dist.eugridpma.info/distribution/igtf/current
enabled=1
metadata_expire=300
gpgcheck=0

[EUGRIDPMA-fetch-crl]
name=EUGRIDPMA fetch-crl repository
baseurl=https://dist.eugridpma.info/distribution/util/fetch-crl/
enabled=1
metadata_expire=300
gpgcheck=0
EOF
}}}
}}}

-Install certificates
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install ca_PolishGrid
yum install ca_PLGRID-SimpleCA
}}}
}}}

-Install certificate revocation list fetching utility 
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install fetch-crl
}}}
}}}

-Get fresh CRLs now
{{{
#!div style="font-size: 90%"
{{{#!sh
/usr/sbin/fetch-crl 
}}}
}}}

-Install cron job for it
{{{
#!div style="font-size: 90%"
{{{#!sh
cat > /etc/cron.daily/fetch-crl.cron << EOF
#!/bin/sh 
/usr/sbin/fetch-crl
EOF
}}}
}}}

{{{
#!div style="font-size: 90%"
{{{#!sh
chmod a+x /etc/cron.daily/fetch-crl.cron
}}}
}}}

= Installation =
The packages are designed for Scientific Linux 5.x
The installation process requires root privileges.

== Software repository ==
* Install PL-Grid or/and QCG repositories:
 * Official PL-Grid repository
{{{
#!div style="font-size: 90%"
{{{#!sh
rpm -Uvh http://software.plgrid.pl/packages/repos/plgrid-repos-2010-2.noarch.rpm
}}}
}}}
 * !QosCosGrid testing repository
{{{
#!div style="font-size: 90%"
{{{#!sh
cat > /etc/yum.repos.d/qcg.repo << EOF
[qcg]
name=QosCosGrid YUM repository
baseurl=http://fury.man.poznan.pl/qcg-packages/sl/x86_64/
enabled=1
gpgcheck=0
EOF
}}}
}}}
 * !QosCosGrid developing repository (not recommended - only for testers)
{{{
#!div style="font-size: 90%"
{{{#!sh
cat > /etc/yum.repos.d/qcg.repo << EOF
[qcg-develop]
name=QosCosGrid Developer YUM repository
baseurl=http://grass1.man.poznan.pl/qcg-rpms/sl5/x86_64/
enabled=1
gpgcheck=0
EOF
}}}
}}}


== GridFTP service ==
For the user convenience QCG client is able to stage in input data accessible from the host where it is installed and also to stage out output data there. The functionality require the data to be accessible via gridFTP service. The gridFTP service can be installed on the client machine or it can be any gridFTP service having access to the data on client machine.

* install grid-ftp server using YUM Package Manager:
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install qcg-dep-gridftp-server
}}}
}}}

The grid-ftp server requires the X.509 certificate and key to be present in following locations
* ''/etc/grid-security/hostcert.pem''
* ''/etc/grid-security/hostkey.pem''

The gridFTP service has to be configured to know the range of opened ports for connections.
Please edit the /etc/xinetd.d/gsiftp file and set the GLOBUS_TCP_PORT_RANGE environment variable.

{{{
#!div style="font-size: 90%"
{{{#!sh
service gsiftp
{
        instances               = 200
        per_source              = 100
        socket_type             = stream
        wait                    = no
        user                    = root
        env                     = LD_LIBRARY_PATH=/opt/plgrid/qcg/dependencies/globus/lib
        env                     += GLOBUS_LOCATION=/opt/plgrid/qcg/dependencies/globus
        server                  = /opt/plgrid/qcg/dependencies/globus/sbin/globus-gridftp-server
        server_args             =  -i 
        log_on_success          += DURATION 
        log_on_failure          += 
        nice                    = 10
        disable                 = no 
        env                     += GLOBUS_TCP_PORT_RANGE=9000,9500
        env                     += GRIDMAP=/etc/grid-security/grid-mapfile
}

}}}
}}}

IMPORTANT: Do not forget to start or reload xinetd service.
{{{
#!div style="font-size: 90%"
{{{#!default
service xinetd reload
}}}
}}}

{{{
#!div style="font-size: 90%"
{{{#!default
service xinetd start
}}}
}}}



== the Grid Mapfile ==
To have access do data every authenticated user must be authorized against the `grid-mapfile`. This file can be created manually by an administrator (if the service is run in "test mode") or generated automatically based on the LDAP directory service.
=== Manually created grid mapfile (for testing purpose only) ===
{{{
#!div style="font-size: 90%"
{{{#!default
#for test purpose only add mapping for your account
echo '"MyCertDN" myaccount' >> /etc/grid-security/grid-mapfile
}}}
}}}
=== LDAP generated grid mapfile ===
* Create the ''qcg-dev'' group - this grou is allowed to read the configuration and log files.
{{{
#!div style="font-size: 90%"
{{{#!default
groupadd -r qcg-dev
}}}
}}}
 
* Install qcg grid-mapfile generator
{{{
#!div style="font-size: 90%"
{{{#!default
yum install qcg-gridmapfilegenerator
}}}
}}}

* Configure gridmapfilegenerator - remember to change 
 * url property to your local ldap replica
 * search base
 * filter expression
 * security context
{{{
#!div style="font-size: 90%"
{{{#!default
vim  /opt/plgrid/qcg/etc/qcg-comp/plggridmapfilegenerator.conf 
}}}
}}}

* Run the gridmapfile generator in order to generate gridmapfile now
{{{
#!div style="font-size: 90%"
{{{#!default
/opt/plgrid/qcg/sbin/qcg-gridmapfilegenerator.sh 
}}}
}}}

After installing and running this tool one can find three files:
 * /etc/grid-security/grid-mapfile.local - here you can put list of DN and local unix accounts name that will be merged with data acquired from local LDAP server
 * /etc/grid-security/grid-mapfile.deny - here you can put list od DN's (only DNs!) that you want to deny access to the QCG-Computing service
 * /etc/grid-security/grid-mapfile - the final gridmap file generated using the above two files and information available in local LDAP server. Do not edit this file as it is generated automatically!

This gridmapfile generator script is run every 10 minutes. Moreover its issues  `su - $USERNAME -c 'true' > /dev/null`  for every new user that do not have yet home directory (thus triggering pam_mkhomedir if installed).

== QCG-Broker client ==
=== Installation ===
* install QCG-Broker client using YUM Package Manager:
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install qcg-broker-client
}}}
}}}

The client is installed into three directories:
* ''/usr/share/qcg/qcg-broker-client'' - scripts and jars needed to run client
* ''/etc/qcg/qcg-broker-client'' - configuration file for the client
* ''/usr/bin'' - links to qcg-* commands

=== Configuration ===

Edit the file ''/etc/qcg/qcg-broker-client/qcg-broker-client.conf'' to configure the client

{{{
#!div style="font-size: 90%"
{{{#!sh
vi /etc/qcg/qcg-broker-client/qcg-broker-client.conf
}}}
}}}

The following properties has to be set:
* QCG_URL_DEFAULT - the URL of QCG-Broker service
{{{
#!div style="font-size: 90%"
{{{#!sh
export QCG_URL_DEFAULT="https://qcg-broker.man.poznan.pl:8443/qcg/services/"
}}}
}}}

* QCG_DN_DEFAULT - the Distinguished Name of the QCG-Broker service
{{{
#!div style="font-size: 90%"
{{{#!sh
export QCG_DN_DEFAULT="/C=PL/O=GRID/O=PSNC/CN=qcg-broker/qcg-broker.man.poznan.pl"
}}}
}}}

* QCG_CLIENT_LOCATION_DEFAULT - the location ot the client. This value is set during the installation procedure and 
{{{
#!div style="font-size: 90%"
{{{#!sh
export QCG_CLIENT_LOCATION_DEFAULT=/usr/share/qcg/qcg-broker-client
}}}
}}}

Optionally it is possible to configure the host and port of GridFTP service which will be used by client to staging input/output files
* GFTP_HOSTNAME - hostname of the host where the gridFTP service is installed. If the property is not set the default value is hostname of the host where the client is installed,
{{{
#!div style="font-size: 90%"
{{{#!sh
export GFTP_HOSTNAME=qcg.man.poznan.pl
}}}
}}}

* GFTP_PORT - port which the gridFTP service is listening on. If the property is not set the default value is "2811".
{{{
#!div style="font-size: 90%"
{{{#!sh
export GFTP_PORT=2811
}}}
}}}


Additionally it is possible to configure also the settings responsible for defining the policy for creation and refreshing of user's proxy.
* QCG_PROXY_DURATION_DEFAULT - default length in hours of the created proxy 
{{{
#!div style="font-size: 90%"
{{{#!sh
export QCG_PROXY_DURATION_DEFAULT=600
}}}
}}}
* QCG_PROXY_DURATION_MIN - minimal acceptable lifetime of the proxy. If the remaining lifetime of the proxy is smaller then the value, the proxy will be automatically recreated.
{{{
#!div style="font-size: 90%"
{{{#!sh
export QCG_PROXY_DURATION_MIN=480
}}}
}}}