Client Installation Guide

About this Document

hand This document is for grid users and system administrators. It covers the installation of the OSG Client Tools Package. This package is required on every host used by grid users to submit jobs, transfer data, or interact otherwise with the OSG. The Worker Node client is not a valid substitute for this package and the OSG Client cannot replace the Worker node client in the batch jobs environment on Worker Node and Compute Element.

The OSG Cient Tools Package includes:

HELP NOTE
This document does not cover the usage of the client tools. An introduction how to use the OSG can be found here. A more detailed description how to interact with a Compute Element is located here.

Conventions used in this document:

A User Command Line is illustrated by a green box that displays a prompt:

  [user@client /opt/osg-1.2.32]$

A Root Command Line is illustrated by a red box that displays the root prompt:

  [root@client /opt/osg-1.2.32]$

Lines in a file are illustrated by a yellow box that displays the desired lines in a file:

priorities=1

Engineering Considerations

The OSG Client Tools Package is required on hosts used to submit jobs to the Open Science Grid. We recommend to install the OSG Client Tools on a dedicated job submission host for large scale job submissions to production resources on the OSG. Grid users may install the package as non-root users. If the client tools are to be shared among users on the job submission host, the installation should be performed by the root user. We recommend to use a public IP address and a fully qualified domain name for shared job submission hosts. Personal clients, specially is not used to submit long running jobs with Condor-G have no special network recommendations.

System administrators installing the OSG Client Tools in a shared location that serves hosts of mixed x86_64 and i686 architectures should consider to force the installation of the version for i686 architecture.

How to get Help?

To get assistance please use this page.

Requirements

  1. verify that your operating system is supported.
  2. a Pacman? installation of version 3.28 or later.
  3. if you enable Gram WS (disabled by default) a valid grid host certificate is required.
  4. to test and use the installation a valid grid user certificate is required.

Installation Procedure

The installation procedure consists of the following steps:

  1. deactivate an existing installation. I.e start the installation with a clean environment
  2. create an empty installation directory
  3. use Pacman? to install the OSG Client Tools Package
  4. install the CA Certificates and the Certificate Revocation List
  5. configure logfile rotation and automatic updates of CA Certificates and the Certificate Revocation List
  6. Enable HTCondor to support Condor-G Job Submissions

Deactivate an existing Installation

Before you proceed with an update you must deactivate an existing installation to avoid to have leftover processes. Make sure to start the installation with a clean environment. If VDT_LOCATION is in your environment you probably need to log-out and log-in again and make sure that no setup file is sourced in your login scripts.

Note that multiple client installation on the same host are possible and do not interfere with each other if they do not compete for the same resources (e.g. update of the same certificate directory, or use cron jobs of the same user). This can be useful to allow multiple personal installations on a client host or to test a new version. Anyway each installation must be performed with a clean environment.

Create the Installation Directory

Create an empty installation directory and change into it. Make sure the directory is world readable if the installation is to be shared by grid users:

[user@client ~]$ mkdir -p /opt/osg-1.2.32
[user@client ~]$ cd /opt/osg-1.2.32

Use Pacman to install the OSG Client Tools Package

In the next step we will use the pacman command line tool to install the package from the OSG software cache. Pacman? will ask whether you want to "trust the caches and accept the license", answer yall and y to install OSG client.

[user@client /opt/osg-1.2.32]$ pacman -get http://software.grid.iu.edu/osg-1.2:client
Do you want to add [http://software.grid.iu.edu/osg-1.2] to [trusted.caches]? (y/n/yall): yall
...

[user@client /opt/osg-1.2.32]$ pacman -get http://software.grid.iu.edu/osg-1.2:client
Do you want to add [http://software.grid.iu.edu/osg-1.2] to [trusted.caches]? (y/n/yall): yall

Beginning VDT prerequisite checking script vdt-common/vdt-prereq-check...       

All prerequisite checks are satisfied.
                                                             
========== IMPORTANT ==========
Most of the software installed by the VDT *will not work* until you install
certificates.  To complete your CA certificate installation, see the notes
in the post-install/README file.

INFO: The Globus-Base-Info-Client package is not supported on this platform
The VDT version 2.0.0 has been installed.
The OSG Client package OSG version 1.2.10 has been installed.

The installation logfile can be found in /opt/osg-1.2.32/vdt-install.log. To complete the installation update your environment and run the post installation script:

[user@client /opt/osg-1.2.32]$ source setup.sh
[user@client /opt/osg-1.2.32]$ vdt-post-install 
Starting...
Done.

Further information about the installation process and what software has been installed can be found here.

Update the Environment

Depending on your shell update your environment by sourcing /opt/osg-1.2.32/setup.sh or /opt/osg-1.2.32/setup.csh:

[root@client /opt/osg-1.2.32]$ . /opt/osg-1.2.32/setup.sh

Depending on your preference you might want to optionally include the setup script in your system or user profile.

on

Some more information and different installation options are described in the advanced section below.

Configure Logfile Rotation and Automatic Updates

To keep your CA Certificates and the Certificate Revocation List current we will add an entry to cron requesting periodic updates. We also recommend to setup logfile rotation using vdt-control at the command line:

[user@client /opt/osg-1.2.32]$ vdt-control --enable fetch-crl vdt-update-certs vdt-rotate-logs 
running 'vdt-register-service --name fetch-crl --enable'... ok
running 'vdt-register-service --name vdt-update-certs --enable'... ok
running 'vdt-register-service --name vdt-rotate-logs --enable'... ok

HELP NOTE
vdt-control --enable will only register the services requested to be run by cron. To actually run the services and create the necessary entries in crontab, the services still have to be activated.

Enable Condor to support Condor-G Job Submissions

Large scale production job submissions require a capable scheduler submitting jobs to grid resources and monitoring their status. Enabling support for HTCondor on the submission host is all that is required to create a local grid queue on your submission host:

[root@client /opt/osg-1.2.32]$ vdt-control --enable condor
running 'vdt-register-service --name condor --enable'... ok

HELP NOTE
This will copy the condor script to /etc/init.d and requires root privileges. Please follow these instructions if you are a non-root user!

Advanced Configuration Options

Completing the steps outlined above will install a fully functional OSG Client. The following section discusses optional and advanced configuration options.

CA Certificates and CRL

on on

Firewall Considerations

The Globus Toolkit and HTCondor require the client host to allow inbound and outbound network connections. This section describes what additional configuration steps have to be taken if the client host is located behind a firewall. For a more detailed description on firewalls consult this document.

Public IP Address and DNS

If you use the the client host as Condor-G submit host for long running jobs, it needs to be reached by remote resources. The easier option is to use a public IP address and not be be located within a private network. For other options check below. To make sure that the client host uses a public IP address and is assigned a fully qualified domain name, use:

[user@client /opt/osg-1.2.32]$ hostname -f
client.opensciencegrid.org
[user@client /opt/osg-1.2.32]$ nslookup client.opensciencegrid.org
Server:		131.215.125.1
Address:	131.215.125.1#53

Name:           client.opensciencegrid.org
Address:        131.215.114.49

If the client host is not assigned a fully qualified domain name, you can assign the public IP address to the GLOBUS_HOSTNAME environment variable:

[user@client /opt/osg-1.2.32]$ echo "export GLOBUS_HOSTNAME=131.215.114.49" >> /opt/osg-1.2.32/vdt/etc/vdt-local-setup.sh 
[user@client /opt/osg-1.2.32]$ source setup.sh

HELP NOTE
It is possible to use a client host that is located inside a private network using Network Address Translation. In this case the gatekeeper must be configured to forward incoming connections to the client host. The $GLOBUS_HOSTNAME environment variable must be set to the gatekeeper address. This procedure is currently not documented.

Globus Port Range

GRAM can be configured to only use a specified range of TCP ports on the client host for inbound ($GLOBUS_TCP_SOURCE_RANGE) and outbound ($GLOBUS_TCP_PORTRANGE) connections.

[user@client /opt/osg-1.2.32]$ echo "export GLOBUS_TCP_PORT_RANGE=20000,22499" >> /opt/osg-1.2.32/vdt/etc/vdt-local-setup.sh 
[user@client /opt/osg-1.2.32]$ echo "export GLOBUS_TCP_SOURCE_RANGE=22500,25000" >> /opt/osg-1.2.32/vdt/etc/vdt-local-setup.sh
[user@client /opt/osg-1.2.32]$ source setup.sh

Condor Port Range

HTCondor will only use a specified range of TCP ports for inbound and outbound connections on the client host that is configured in $CONDOR_CONFIG:

[user@client /opt/osg-1.2.32]$ echo $CONDOR_CONFIG 
/opt/osg-1.2.32/condor/etc/condor_config

Please un-comment and adjust the definitions for LOWPORT and HIGHPORT in $CONDOR_CONFIG:

[user@client /opt/osg-1.2.32]$ cat $CONDOR_CONFIG | grep \= | grep LOWPORT
#LOWPORT = 9600
[user@client /opt/osg-1.2.32]$ cat $CONDOR_CONFIG | grep \= | grep HIGHPORT
#HIGHPORT = 9700 

Restart Condor as the root user in order for the settings to take effect:

[root@client /opt/osg-1.2.32]$ /etc/init.d/condor stop
Shutting down Condor
Sent "Kill-Daemon" command for "master" to local master
[root@client /opt/osg-1.2.32]$ /etc/init.d/condor start
Starting up Condor

HELP NOTE
Please follow these instructions to restart Condor if you are a non-root user!

Sharing the Installation between 32Bit and 64Bit Clients

hand This section is for System Administrators that require the OSG Client Package to be setup in a shared location and which will be used by hosts with different architectures, 32 and 64 bit. In this case and if the host used for the installation is 64Bit host, then a 32Bit installation has to be forced using a command line option to Pacman?.

HELP NOTE
This procedure requires the installation of 32Bit Compatibility Libraries on all 64Bit clients!

To force the installation of the 32Bit OSG Client Package simply provide the -pretend-arch i686 command line option to the pacman command:

[user@client /opt/osg-1.2.32]$ pacman -pretend-arch i686 -get http://software.grid.iu.edu/osg-1.2:client
Do you want to add [http://software.grid.iu.edu/osg-1.2] to [trusted.caches]? (y/n/yall): yall
...

[user@client /opt/osg-1.2.32]$ pacman -pretend-arch i686 -get http://software.grid.iu.edu/osg-1.2:client
Do you want to add [http://software.grid.iu.edu/osg-1.2] to [trusted.caches]? (y/n/yall): yall
Beginning VDT prerequisite checking script vdt-common/vdt-prereq-check...       
All prerequisite checks are satisfied.

========== IMPORTANT ==========
Most of the software installed by the VDT *will not work* until you install
certificates.  To complete your CA certificate installation, see the notes
in the post-install/README file.
                                                                              
The VDT version 2.0.0 has been installed.    
The OSG Client package OSG version 1.2.10 has been installed.

and continue to follow the instructions.

Activate and Deactivate Services

About VDT Services

The Virtual Data Toolkit provides three types of services:

  1. cron services that will be started periodically by the cron daemon
  2. init services that will be started and stopped by the init daemon
  3. xinet services that will be started upon internet connection attempts by the extended internet daemon

Only cron services may be setup by unprivileged users. All other services require root privileges.

List Registered Services

To see a list of services registered by the Virtual Data Toolkit use vdt-control:

[user@client /opt/osg-1.2.32]$ vdt-control --list

Service Activation

Use vdt-control to activate registered services. This will:

  • add entries to crontab for cron services
  • add control scripts to /etc/init.d for init services
  • start new init services
  • configure the xinet daemon for xinet services

Unprivileged users must provide the --non-root argument to vdt-control to install cron services. All other services require root privileges.

[root@client /opt/osg-1.2.32]$ vdt-control --on <Service Name>

vdt-control will fail to activate any service that is already provided by the operating system. In this case you may force the activation of the new service provided by the Virtual Data Toolkit:

[root@client /opt/osg-1.2.32]$ vdt-control --force --on <Service Name>

Another reason for vdt-control to fail to activate a service may be that the service was previously installed by another installation of the Virtual Data Toolkit which has not been deactivated yet. In this case you must force the deactivation of the existing service before you continue to install the new service:

[root@client /opt/osg-1.2.32]$ vdt-control --force --off <Service Name>
[root@client /opt/osg-1.2.32]$ vdt-control --on <Service Name>

Service Deactivation

Use vdt-control to deactivate registered services. This will:

  • remove entries from crontab for cron services
  • stop init services
  • remove control scripts from /etc/init.d for init services
  • re-configure the xinet daemon for xinet services

Unprivileged users must provide the --non-root argument to vdt-control to uninstall cron services. All other services require root privileges.

[root@client /opt/osg-1.2.32]$ vdt-control --off <Service Name>

vdt-control may fail to deactivate all services due to hanging processes. In this case expect the process table and kill hanging processes manually.

Manually Start and Stop Condor

A non-root user doesn't have the permissions to add HTCondor to the init daemon. In this case Condor needs to be started and stopped manually by the user.

Start Condor by using the condor_master command:

[user@client /opt/osg-1.2.32]$ condor_master

Stop Condor by using the condor_off command:

[user@client /opt/osg-1.2.32]$ condor_off -master
Sent "Kill-Daemon" command for "master" to local master

Setup the Client

As all the software installed via Pacman, OSG-Client creates a self contained installation and each time you want to use the software included in OSG-Client you must source the setup file. There is one setup file for each major Unix shell, e.g. for sh and bash:

[user@client /opt/osg-1.2.32]$ source /opt/osg-1.2.32/setup.sh

Test the Client

This document does not cover the usage of the client tools. An introduction how to use the OSG can be found here. A more detailed description how to interact with a Compute Element is located here.

To simply test the functionality of your installation:

Troubleshooting

You may use the vdt-version command to display information about all software packages that have been installed:

[user@client /opt/osg-1.2.32]$ vdt-version

You have installed a subset of VDT version 2.0.0p17:

Software                                                 Status              
--------                                                 ------              
Bandwidth Test Controller 1.3                            OK                  
vdt-ca-manage 1.2                                        OK                  
vdt-update-certs 2.5                                     OK                  
CGSI-gSOAP 1.2.1.2                                       OK                  
Condor/Condor-G 7.2.5                                    OK                  
cURL 7.18.2                                              OK                  
Fetch CRL 2.6.6                                          OK                  
Grid File Access Library (GFAL) 1.11.9-1                 OK                  
Globus Toolkit, pre web-services, client 4.0.8           OK                  
Globus Toolkit, web-services, client 4.0.8               OK                  
GPT 3.2-4.0.8p1                                          OK                  
GSI-Enabled OpenSSH 5.1                                  OK                  
Java 5 SDK 1.5.0_22                                      OK                  
lcg-info 1.11.4-1                                        OK                  
lcg-infosites 2.6-2                                      OK                  
LCG Utils 1.7.6-1                                        OK                  
LCG File Catalog Client 1.7.2-4                          OK                  
Logrotate 3.7                                            OK                  
MyProxy Client 5.1                                       OK                  
Network Diagnostic Tool 3.5.0                            OK                  
Network Path and Application Diagnosis Client 1.5.5      OK                  
OSG Discovery Tools 1.0.4                                OK                  
One-Way Active Measurement Protocol (One-Way Ping) 3.1   OK                  
Pegasus 2.4.1                                            OK                  
PPDG Cert Scripts 2.7                                    OK                  
PyGlobus URL Copy 1.1.2.11                               OK                  
SRM Fermi Client 1.9.5-3                                 OK                  
SRM Berkeley Client 2.2.1.3.12                           OK                  
UberFTP 2.4                                              OK                  
VOMS Client 1.8.8-2p1                                    OK                  
Wget 1.12                                                OK                  


Status legend:
OK: Software is up to date with the latest release in VDT version 2.0.0
- : Not enough information to determine if updates are available.
Type 'man vdt-version' for more information.

The installation logfile is located in /opt/osg-1.2.32/vdt-install.log. Please review the file for obvious error message and provide the content for further debugging.

Comments

PM2RPM?_TASK = CLIENT RobertEngel 28 Aug 2011 - 05:55

Topic revision: r101 - 07 Feb 2017 - 18:53:25 - BrianBockelman
Hello, TWikiGuest
Register

Introduction

Clients

Central OSG Services

Additional Information

Community
linkedin-favicon_v3.icoLinkedIn
FaceBook_32x32.png Facebook
campfire-logo.jpgChat?
 
TWIKI.NET

TWiki | Report Bugs | Privacy Policy

This site is powered by the TWiki collaboration platformCopyright by the contributing authors. All material on this collaboration platform is the property of the contributing authors..