Changes between Initial Version and Version 1 of client-installation-guide

Timestamp:

08/23/13 14:08:54 (12 years ago)

Author:

piontek

Comment:

--

client-installation-guide

@@ +1 @@
+= QCG-Client Installation Guide =
+
+[[PageOutline]] 
+
+'''The QCG-Client is the command-line java based client to the QCG-Broker service.'''
+
+
+= Requirements =
+== Mandatory ==
+* '''configured set of trusted CAs'''
+* '''software packages''' 
+ * Installation from RPM - all packages required by the QCG-Client will be automatically installed by YUM during the installation of qcg-broker-client package.
+ * Installation from sources - The following list of packages is required to build, deploy and run the qcg-broker client:
+  * java 1.6
+  * ant
+  * ant-nodeps
+  * xml-commons-apis
+== Optional ==
+* '''PL-Grid LDAP integration (PL-Grid only)''' - the machine where the client is to be installed has to be configured to allow users to log in to the their "plg*" accounts. 
+* '''GridFTP server''' - the GridFTP server providing access to user's data for staging them in/out. It can be installed on the client machine (see the "Optional steps" section) or be any other instance of server having access to the data (e.g. if UI `/home` directory is shared with the QCG-Computing machine then installing gridFTP server on the UI is optional). 
+
+= Preparation of the environment =
+
+== Disabling IPv6 ==
+[http://apps.man.poznan.pl/trac/qcg/wiki/disable%20IPv6 Disable IPv6 if you really do not need it]
+
+== Certificate authorities ==
+To allow proper mutual authentication between client and service set of Certificate Authorities [CA] certificates has to be installed.
+To install CA certificates please follow the instruction: [[https://www.qoscosgrid.org/trac/qcg/wiki/CA%20certificates | CA certificates installation]]
+
+
+
+= QCG-Client Installation =
+
+== Installation ==
+
+=== Installation from RPM (recommended) ===
+
+* configure your system with [[http://www.qoscosgrid.org/trac/qcg/wiki/Software%20repositories | QCG Software Repositories]] 
+* install QCG-Client using YUM Package Manager (as root):
+{{{
+#!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 the client
+* ''/etc/qcg/qcg-broker-client'' - configuration file for the client
+* ''/usr/bin'' - links to qcg-* commands
+
+=== Installation from sources ===
+
+* download qcg-broker sources from the SVN repository
+{{{
+svn co https://apps.man.poznan.pl/svn/qcg-broker/branches/3.0 .
+}}}
+
+* build the code
+{{{
+ant client-rebuild
+}}}
+
+* deploy the client to the target directory, setting the variable client.deploy.dir to the target location
+{{{
+ant -Dclient.deploy.dir=/home/piontek/qcg-client -f build.deploy.xml deploy-client
+}}}
+== Configuration ==
+The client looks for the global configuration first in the ''/etc/qcg/qcg-broker-client/qcg-broker-client.conf'' file and then for the ''~/.qcg/qcg.conf'' one which overwrites global settings.
+
+'''IMPORTANT: ''' We strongly advice to configure the RPM installation with global file.
+
+* To configure the client please create/edit 
+ * either the ''/etc/qcg/qcg-broker-client/qcg-broker-client.conf'' file (common for all users)
+ * or the ''~/.qcg/qcg.conf'' file (with individual settings for every user)
+
+{{{
+#!div style="font-size: 90%"
+{{{#!sh
+vi /etc/qcg/qcg-broker-client/qcg-broker-client.conf
+}}}
+}}}
+
+The following properties have to be set:
+* QCG_URL_DEFAULT - the URL of QCG-Broker service
+* QCG_DN_DEFAULT - the Distinguished Name of the QCG-Broker service
+* QCG_CLIENT_LOCATION_DEFAULT - the location of the client. If the value was set during the installation procedure there is no need to modify it.
+
+Optionally it is possible to configure the host and port of the GridFTP server which will be used by client for staging input/output files
+* GFTP_HOSTNAME - hostname of the host where the GridFTP server is installed. If the property is not set the default value is hostname of the host where the client is installed,
+* GFTP_PORT - port which the GridFTP server is listening on. If the property is not set the default value is "2811".
+
+GridFTP server and interactive jobs require some set of ports to be opened for incoming connections. The client takes this range of opened ports from the GLOBUS_TCP_PORT_RANGE environment variable.
+* GLOBUS_TCP_PORT_RANGE - range of opened ports
+
+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 proxy created by QCG-Client,
+* QCG_PROXY_DURATION_MIN - minimal acceptable lifetime of the proxy. If the remaining lifetime of the proxy is smaller then the given value, the proxy is automatically recreated.
+
+QCG-Client supports connecting to running jobs with interactive console (''qcg-connect'' command). The functionality needs one property to be set.
+* QCG_CONNECT_TIMEOUT - timeout for the connection from the job to the client.
+
+
+The example of the configuration file can be seen below:
+{{{
+#!div style="font-size: 90%"
+{{{#!sh
+export QCG_CLIENT_LOCATION_DEFAULT=/usr/share/qcg/qcg-broker-client
+
+export QCG_URL_DEFAULT="https://qcg-broker.man.poznan.pl:8443/qcg/services/"
+export QCG_DN_DEFAULT="/C=PL/O=GRID/O=PSNC/CN=qcg-broker/qcg-broker.man.poznan.pl"
+
+export GFTP_HOSTNAME=qcg.man.poznan.pl
+export GFTP_PORT=2811
+
+export GLOBUS_TCP_PORT_RANGE=9000,9500
+
+export QCG_PROXY_DURATION_DEFAULT=600
+export QCG_PROXY_DURATION_MIN=480
+
+export QCG_CONNECT_TIMEOUT=60
+}}}
+}}}
+
+'''IMPORTANT (PL-Grid only):'''
+To configure the client to contact the official, production instance of the QCG-Broker service deployed on PL-Grid infrastructure please use the following values:
+{{{
+#!div style="font-size: 110%"
+{{{#!sh
+export QCG_URL_DEFAULT="https://qcg-broker.man.poznan.pl:8443/qcg/services/"
+export QCG_DN_DEFAULT="/C=PL/O=GRID/O=PSNC/CN=qcg-broker/qcg-broker.man.poznan.pl"
+}}}
+}}}
+
+== Site configuration ==
+* Configure the site to display "the message of the day" for QCG-Client.
+ The path to the motd file is ''/usr/share/qcg/qcg-broker-client/doc/motd''.
+* Configure the site for "nightly yum updates" to automatically install new versions of the client.
+
+
+= Optional Components Installation =
+The optional steps consider installation and configuration of the GridFTP server as well installation and configuration of the !GridMapFileGenerator tool (PLGrid Only) being responsible for periodic creation of grid-map-file used by the server for authorization and mapping users to physical accounts.
+
+The steps are for the case when there is no other GridFTP server providing access to user's data on the client machine and the dedicated instance of the server has to be installed.
+
+'''IMPORTANT:''' In most cases it should be possible to configure QCG-client to use the GridFTP server installed on the QCG-Computing site. Such configuration is recommended as it reduces number of software components that have to be maintained. 
+
+== GridFTP server ==
+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 requires the data to be accessible via GridFTP server. The GridFTP server can be installed on the client machine or it can be any GridFTP server having access to the data on client machine. The simplest and the most popular solution is to mount the same shared network file system on both machines. The mount point must be exact the same. Paths to data have to be exactly the same on both machines.
+
+To install and configure the gridFTP server please follow the [[http://apps.man.poznan.pl/trac/qcg/wiki/gridftp%20server | guide]]
+
+
+== Grid Mapfile ==
+To have access do data every authenticated user must be authorized by GridFTP server against the `grid-mapfile`. This file can be created manually by an administrator or generated automatically based on the LDAP directory service.
+
+=== Manually created grid mapfile ===
+{{{
+#!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 (PL-Grid only)===
+To install and configure the gridmap-file-generator tool please follow the [[http://apps.man.poznan.pl/trac/qcg/wiki/gridmap-file-generator | guide]]
+
+= Verification of installation =
+
+* Copy user's certificate (''usercert.pem'') and key (''userkey.pem'') files to the ''.globus'' directory
+* Invoke the command returning description of the QCG-Broker service
+{{{
+#!div style="font-size: 90%"
+{{{#!default
+qcg-client description
+}}}
+}}}
+
+The information about the service version should be displayed
+{{{
+#!div style="font-size: 90%"
+{{{#!default
+QCG-Broker Service ...
+}}}
+}}}
+ 
+'''IMPORTANT:''' For more details concerning usage of the QCG-Client please visit:
+* [[http://www.qoscosgrid.org/trac/qcg-broker/wiki/client_user_guide | the QCG-Client User Guide ]]
+* [[https://docs.plgrid.pl/qcg | QCG-Client Podręcznik Użytkownika (Polish only)]].
+
+= License =
+For license details please visit the [http://www.qoscosgrid.org/trac/qcg/wiki/license QCG License] page.