Please note: This documentation is for OSG 1.2. While we still provide critical security updates for OSG Software 1.2, we recommend you use OSG Software 3 for any new or updated installations. We are considering May 31, 2013 as possible OSG 1.2 End of Life (EOL).

ReleaseDocumentation
ClientInstallationGuide
Reviewed Passed
by
Test Passed
by
Released
by MarcoMambelli

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.

Install the OSG CA Certificate Authority Package

These are short instructions providing a self contained installation of the OSG distribution of Certificate Authorities certificates. Certificates identify users and servers. Certificate Authorities issue certificates to their members. By installing these certificates you establish a chain of trust with each of the certificate authorities and trust the users, the servers and the services certified by those authorities. The Certificate Revocation List is used to inform you about individual certificates that have been revoked.

ALERT! WARNING!
This is important security matter and we recommend you to read the full documentation to understand the implications and to learn about available options.

Local Installation of the CA Certificates

This local installation of the Certificate Authority Package is preferably be used by grid users without root privileges or if the CA certificates will not be shared by other VDT installations on the same host.

[user@client /opt/osg-1.2.32]$ vdt-ca-manage setupca --location local --url osg
Setting CA Certificates for VDT installation at '/opt/osg-1.2.32'

Setup completed successfully.

After a successful installation the certificates will be installed in ($VDT_LOCATION/globus/share/certificates, /opt/osg-1.2.32/globus/share/certificates in this example).

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

Install a Certificate Authority Package

Before you proceed to install a Certificate Authority Package you should decide which of the available packages to install. Choose according to the resource group you chose earlier during the resource registration process with the OSG Information Management System:

HELP NOTE
If in doubt, please consult the policies of your home institution and get in contact with the Security Team. You may inspect and remove CA Certificates after the installation process completed!

Next decide at what location to install the Certificate Authority Package:

  1. on the local file system beneath the current installation directory /opt/osg-1.2.32
  2. on the root file system in a system directory /etc/grid-security/certificates
  3. in a custom directory that can also be shared

The instructions below illustrate each method using the Certificate Authority Package used on the Open Science Grid. Choose a package by changing the --url argument provided to vdt-ca-manage.

Local Installation of the CA Certificates

This local installation of the Certificate Authority Package is preferably be used by grid users without root privileges or if the CA certificates will not be shared by other VDT installations on the same host.

[user@client /opt/osg-1.2.32]$ vdt-ca-manage setupca --location local --url osg
Setting CA Certificates for VDT installation at '/opt/osg-1.2.32'

Setup completed successfully.

After a successful installation the certificates will be installed in ($VDT_LOCATION/globus/share/certificates, /opt/osg-1.2.32/globus/share/certificates in this example).

Root Installation

This root installation of the Certificate Authority Package is preferably be used if the CA certificates will be shared by several VDT installations on the same host. This installation requires always root privileges because the CA Package is installed in a system directory.

[root@client /opt/osg-1.2.32]$ vdt-ca-manage setupca --location root --url osg
Setting CA Certificates for VDT installation at '/opt/osg-1.2.32'

Setup completed successfully.

After a successful installation the certificates will be installed in /etc/grid-security/certificates.

Custom Installation

This custom installation of the Certificate Authority Package is preferably be used if the CA certificates will be shared by several VDT installations on different hosts.

[user@client /opt/osg-1.2.32]$ vdt-ca-manage setupca --location /mnt/nfs --url osg
Setting CA Certificates for VDT installation at '/opt/osg-1.2.32'

Setup completed successfully.

After a successful installation the certificates will be installed in /mnt/nfs/certificates.

Provide and Install a custom CA Package

If a custom Certificate Authority certificates package was made available on a web server, it can be used to be installed using the --url option on the command line to vdt-ca-manage:

[user@client /opt/osg-1.2.32]$ vdt-ca-manage setupca --location /mnt/nfs --url <url to custom CA Package>
Setting CA Certificates for VDT installation at '/opt/osg-1.2.32'

Setup completed successfully.

After a successful installation the certificates provided at the provided --url location will be installed in /mnt/nfs/certificates.

Use an existing CA Installation

It is often practical to reuse an existing Certificate Authority Installation instead of creating a new installation. It is preferably be used when another VDT installation is managing the CA Installation. This installation can be on the same host or a different host who is providing the certificates on a shared file system.

See these instructions to install the CA Certificates in a shared location before you proceed.

[user@client /opt/osg-1.2.32]$ vdt-ca-manage setupca --location /mnt/nfs/certificates --no-update
Setting CA Certificates for VDT installation at '/opt/osg-1.2.32'

Setup completed successfully.

hand The command line option --location points to the existing installation. The command creates a softlink from /opt/osg-1.2.32/globus/TRUSTED_CA to the existing installation /mnt/nfs/certificates.

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: r94 - 22 Mar 2012 - 22:19:23 - RobQ
Hello, TWikiGuest
Register

Introduction

Installation and Update Tools

Clients

Compute Element

Storage Element

Other Site Services

VO Management

Software and Caches

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..