= Introduction =
This page provides step-by-step guide for site admins. It describes basic steps to install and configure GridFTP service.
For any issue concerning the guide please contact [mailto:bogdanl@man.poznan.pl Bogdan Ludwiczak].
= Globus Toolkit/GridFTP - installation =
This sections provides overview of Globus Toolkit ver. 4.x installation procedure.
Globus Toolkit is provided both in binary and source versions. It is also available as Java WS-core only or full version. For the purpose of the QosCosGrid Infrastructure the full source installation is required, as it provides the required GridFTP features and in most cases is more reliable (though more troublesome in rare cases) and robust then binary version.
Below are the steps required to compile and install Globus Toolkit with only GridFTP daemon and utilities.
'''Note:''' this is only an outline of the installation process which should be sufficient to install GridFTP service in most cases, full and detailed information regarding toolkit installation can be found in official Globus [http://www.globus.org/toolkit/docs/4.0/ documentation].
* Check if target system has all required software components:
* gcc (latest 3.4 or 4.1)
* GNU tar, sed, make
* Perl >5.6
* Create a dedicated, non-privileged user named `globus`. This user owns the installation/deployment files compile and install Globus Toolkit performs administrative tasks such as deploying/configuring services, etc.
* Create deployment directory
* make sure that user the `globus` has read and write permissions in the installation directory
'''Note:''' Following steps should be carried out by the `globus` user.
* Download and untar Globus Toolkit ver.4.2.x all-source-installer (available at the [[http://www.globus.org/toolkit/downloads/4.2.1/#source Globus Toolkit]] web site)
* change current working directory to the source directory (i.e. `~/gt4.2.x-all-source-installer`)
* set environmental variable `GLOBUS_LOCATION` to point to installation directory (e.g. `/opt/globus/gt421`)
* finally use `./configure` to set up compilation and installation option. Use at least `--prefix` option to set the deployment directory.
{{{
#!div style="font-size: 90%"
{{{#!sh
./configure --prefix=${GLOBUS_LOCATION}
}}}
}}}
'''Note:''' If you encounter an error '''configure: error: Unable to compile with SSL''', replace the above line with:
{{{
#!div style="font-size: 90%"
{{{#!sh
./configure --disable-system-openssl --prefix=${GLOBUS_LOCATION}
}}}
}}}
* Compile and install Globus Toolkit by running:
{{{
#!div style="font-size: 90%"
{{{#!sh
make gridftp
make install
}}}
}}}
If you wish to have a log file of the build, use "tee" command:
{{{
#!div style="font-size: 90%"
{{{#!sh
make gridftp 2>&1 | tee build.log
make install
}}}
}}}
* GT4 unlike other software packages is made directly to target location ($GLOBUS_LOCATION
)
* If you omit gridftp
for make
the entire Globus Toolkit will be build what can take several hours to complete.
* during make install
phase Globus configuration will be initialized
* You can also choose to build GridFTP server or client tools be specifying globus_gridftp_server
or globus-data-management-client
respectively.
The belowe steps completes Globus Toolkit/GridFTP installation. The following figure summarizes shell commands used during typical installation process:
bogdanl@cress ~ $ su -
cress ~ # useradd -m globus
cress ~ # mkdir /opt/globus
cress ~ # chown globus:users /opt/globus
cress ~ # su - globus
globus@cress ~ $ wget http://www-unix.globus.org/ftppub/gt4/4.2.1/installers/src/gt4.2.1-all-source-installer.tar.bz2
globus@cress ~ $ tar xjf gt4.2.1-all-source-installer.tar.bz2
globus@cress ~ $ cd gt4.2.1-all-source-installer
globus@cress ~ $ export GLOBUS_LOCATION=/opt/globus/gt421
globus@cress ~/gt4.2.1-all-source-installer $ ./configure --prefix=${GLOBUS_LOCATION} \
globus@cress ~/gt4.2.1-all-source-installer $ make gridftp
cd gpt && OBJECT_MODE=32 ./build_gpt
...
Your build completed successfully. Please run make install.
globus@cress ~/gt4.2.1-all-source-installer $ make install
=Globus Toolkit/GridFTP - basic configuration=
==Security==
After Globus Toolkit installation, but before starting Globus services several aspects of GSI security need to be configured:
*configure Globus (and thus GridFTP daemon) to trust a particular set of CAs (Certificate Authorities), i.e. place certificates of trusted CAs into designated directory - CA is trusted only if its CA certificate exists with the appropriate name in an appropriate directory. Moreover, for pre-ws services (including GridFTP), signing policy file must exist in the same location as CA certificate. In other words, one needs two files to trust given CA:
:* cert_hash.0
- the trusted CA certificate and
:* cert_hash.signing_policy
- the signing policy.
:Globus services and tools looks for that directory in following locations:
:* the value of $X509_CERT_DIR
environment variable if it is set and the directory exists,
:* otherwise, in $HOME/.globus/certificates
if it exists,
:* otherwise, in /etc/grid-security/certificates
if it exists,
:* otherwise, in $GLOBUS_LOCATION/share/certificates
if it exists.
{{Note}} We suggest to use /etc/grid-security/certificates
as system wide trusted CAs directory, but remember that $X509_CERT_DIR
and $HOME/.globus/certificates
have higher priority.
The "cert_hash.0", i.e. certificate of the CA, is provided by CA, usually with appropriate hash name. Hash name consists of 8 hex-digits and suffix ".0" (e. g. 8a661490.0
). Valid hash can be obtained with following command (available in $GLOBUS_LOCATION/bin/)
:
openssl x509 -hash -noout -in ca_certificate
* cert_hash.signing_policy usually is also provided by CA, but it can be constructed manually. The signing policy file has the following format:
access_id_CA X509 'CA Distinguished Name'
pos_rights globus CA:sign
cond_subjects globus '"Name Pattern1" "Name Pattern2" ...'
: to get 'CA Distinguished Name' execute:
openssl x509 -subject -noout -in cert_hash.0
* "name pattern" is a string used to match the distinguished names of certificates granted by the given CA. Usually, it is a CA name with common name replaced by wild card '*', e.g.:
"/C=PL/O=GRID/CN=Polish Grid CA" -> '"/C=PL/O=GRID/*"'
: it accepts "C=PL/O=GRID/OU=PSNC/CN=Bogdan Ludwiczak", but it rejects "O=GRID/OU=PSNC/CN=Bogdan Ludwiczak" '"*"' pattern accepts all certificates.
* Configure appropriate default values for use by the grid-cert-request command which is used to generate certificates requests. The following files have to be properly configured to enable Globus tools to generate valid certificate requests:
/etc/grid-security/globus-user-ssl.conf
- defines the distinguished name to use for a user's certificate request.
/etc/grid-security/globus-host-ssl.conf
- defines the distinguished name for a host and service certificate request.
/etc/grid-security/grid-security.conf
- is a main configuration file that contains the name and email address for the given CA.
These files are usually provided by the CA, particularly [[QosCosGrid CA]] or [http://www.man.poznan.pl/plgrid-ca/ PL-Grid] does provides these files. Typically, CA configuration files are placed in /etc/grid-security/certificates/
directory with additional extension .CA_hash_name and only appropriate symbolic links are created in /etc/grid-security/. Globus Toolkit provides grid-default-ca command which can be used to automatically create appropriate links.
== Requesting host and user X.509 certificates ==
All Globus service (including GridFTP) require a host (or service) certificate to operate. Also every user needs a user certificate do use Globus services. You can use Globus command grid-cert-request to generate
host/users certificate request which should be send to your CA to be signed. Make sure that CA configuration files and certificate are in place before generating requests. This command will create 3 files:
* an empty (file length is 0) /etc/grid-security/hostcert.pem or ~/.globus/usercert.pem,
* /etc/grid-security/hostkey.pem
or ~/.globus/userkey.pem file containig
host/user private key which must be kept secret - make sure that the unix access mode is set to 0400 or 0600 at most,
* /etc/grid-security/hostcert_request.pem
or ~/.globus/usercert_request.pem
file containing acctual request to be send to and signed by CA.
{{Note}} Before you can use grid-cert-request command you have to source Globus configuration script appropriate for your shell, i.e. $GLOBUS_LOCATION/etc/globus-user-env.csh
or $GLOBUS_LOCATION/etc/globus-user-env.sh
Send newly generated certificate request (i.e. /etc/grid-security/hostcert_request.pem
or ~/.globus/usercert_request.pem
file) to the appropriate CA and wait for the certificate which should be send in return by your CA. Save the new certificate in hostcert.pem
or usercert.pem
. Now, request file can be deleted. Host certificate and private key should be owned by root user.
Specify identity mapping information
Globus services map distinguished names (retrieved from certificates) to local identities (unix account) by means of grid-mapfile
. Mappings have the folowing form:
"Distinguished Name" local_name
(every line of the file defines one mapping) To let user in, create an account and add mapping to the site's grid-mapfile. Globus looks for the file in the following locations:
* the value of GRIDMAP
environment variable if it is set,
* otherwise, if service is run as root then grid map file is /etc/grid-security/grid-mapfile
,
* otherwise, the grid map file is $HOME/.gridmap
* otherwise, in /etc/grid-security/grid-mapfile
.
{{Note}} In the QosCosGrid project there is a possibility to generate a new user X.509 certificate in more [http://node2.qoscosgrid.man.poznan.pl:80/gridsphere/gridsphere/guest/security/r/ user-friendly way]
== Firewall configuration ==
Detailed information on GT firewall issues can be found at http://www.globus.org/toolkit/security/firewalls/. This paragraph only lists the minimum required firewall configuration and gives a short overview of the basic issues. To enable remote access to Globus Toolkit services the following TCP port should be opened for the incoming connections:
*static port: 2811 for main GridFTP daemon port
*ephemeral TCP ports: various Globus services require an arbitrary chosen TCP port range. It is controllable by environmental variable GLOBUS_TCP_PORT_RANGE for pre-ws components. Make sure it is defined in daemons environment (i.e. put it in (x)inetd configuration entries)
Figure below gives an overview of typical Globus/GridFTP communication flow It shows the meaning of the aforementioned Globus TCP port range.
[[File:Firewall_gridftp.jpg|frame|center|alt=GridFTP communication diagram|GridFTP communication diagram]]
== GridFTP Daemon ==
After successful installation of GlobusToolkit, the GridFTP daemon binary is located in: $GLOBUS_LOCATION/sbin/globus-gridftp-server
file. The daemon could be run in standalone mode, but we suggest using (x)inetd mode. To configure it this way, first add the following entry to /etc/services
file:
gsiftp 2811/tcp # GridFTP (Port 2811 is the IANA registered GridFTP port)
Next add appropriate entry to (x)inetd configuration file(s). Remember to set LD_LIBRARY_PATH
, GLOBUS_LOCATION
and GLOBUS_TCP_PORT_RANGE
in the (x)inetd entry environment, like in the xinetd example below:
service gsiftp
{
instances = 100
cps = 50 10
per_source = 50
socket_type = stream
wait = no
user = root
env = LD_LIBRARY_PATH=/opt/globus/lib
env += GLOBUS_LOCATION=/opt/globus
env += GLOBUS_TCP_PORT_RANGE=9000,9999
server = /opt/globus/sbin/globus-gridftp-server
server_args = -i -c /opt/globus/etc/gridftp.conf
log_on_success += DURATION
log_on_failure +=
nice = 10
disable = no
}
Note that the above example specifies grid-ftp configuration file (-c .../gridftp.conf in server_args line). It is not required - GridFTP daemon should work without this file. A useful example of configuration file is:
log_level ALL (or 'EERROR', 'WARN', 'INFO', 'DUMP')
log_module stdio
log_single /var/log/gridftp
it enables logging which can be helpful in resolving potential problems. Finally, restart (x)inetd to activate the GridFTP daemon:
# /etc/init.d/xinetd restart
== Users configuration ==
All Globus Toolkit commands require appropriately configured environment. Globus Toolkit provides scripts for that purpose. To configure users environment for GT command do the following:
for bash shell:
export GLOBUS_LOCATION=/opt/globus/gt421
. $GLOBUS_LOCATION/etc/globus-user-env.sh
or for csh shell:
setenv GLOBUS_LOCATION /opt/globus/gt421
source $GLOBUS_LOCATION/etc/globus-user-env.csh
Next you must obtain user certificates (as described in [[GridFTP#Requesting_host_and_user_X.509_certificates| Requesting host and user X.509 certificates]]) and then create user proxy by running command grid-proxy-init
:
$ grid-proxy-init
Your identity: /C=PL/O=GRID/O=PSNC/CN=Bogdan Ludwiczak
Enter GRID pass phrase for this identity:
Creating proxy ....................................................... Done
Your proxy is valid until: Tue Apr 29 21:02:33 2008
Next, become root and create a mapping in /etc/grid-security/grid-mapfile
. You can use your favorite text editor for that purpose and append a line similar to this one:
"/C=PL/O=GRID/O=PSNC/CN=Bogdan Ludwiczak" bogdanl
or use GT grid-mapfile-add-entry
command:
# grid-mapfile-add-entry -dn "/C=PL/O=GRID/O=PSNC/CN=Bogdan Ludwiczak" -ln bogdanl
{{Note}} "bogdanl" in examples above is a name of a local unix account.
Now you can transfer some files with globus-url-copy tool:
$ globus-url-copy gsiftp://node1.qoscosgrid.man.poznan.pl/~/file file:///tmp/file.test
$ globus-url-copy gsiftp://node1.qoscosgrid.man.poznan.pl/~/file gsiftp://node1.qoscosgrid.man.poznan.pl/~/file2
$ globus-url-copy gsiftp://node1.qoscosgrid.man.poznan.pl/~/file gsiftp://node2.qoscosgrid.man.poznan.pl/~/file2
= Quick Start =
* create 'globus' user and installation directory, make 'globus' user an owner of this directory:
bogdanl@cress ~ $ su -
cress ~ # useradd -m globus
cress ~ # mkdir /opt/globus
cress ~ # chown globus:users /opt/globus
* login as a globus
user:
cress ~ # su - globus
* download Globus Toolkit source installer and untar it:
globus@cress ~ $ wget http://www-unix.globus.org/ftppub/gt4/4.2.1/installers/src/gt4.2.1-all-source-installer.tar.bz2
globus@cress ~ $ tar xjf gt4.2.1-all-source-installer.tar.bz2
* Configure and make sources:
globus@cress ~ $ cd gt4.2.1-all-source-installer
globus@cress ~ $ export GLOBUS_LOCATION=/opt/globus/gt421
globus@cress ~/gt4.2.1-all-source-installer $ ./configure --prefix=${GLOBUS_LOCATION} \
globus@cress ~/gt4.2.1-all-source-installer $ make gridftp
cd gpt && OBJECT_MODE=32 ./build_gpt
...
Your build completed successfully. Please run make install.
globus@cress ~/gt4.2.1-all-source-installer $ make install
* Request host certificates:
* Start gridftp-server either standalone or by (x)inetd daemon
:* If you are going to use xinetd daemon add gridftp to /etc/services:
bogdanl@cress ~ $ su -
cress ~ # echo "gsiftp 2811/tcp # GridFTP" >> /etc/services
:* and create new xinetd configuration file for gridftp service
cress ~ # cat /etc/xinetd.d/gridftp
service gsiftp
{
instances = 100
cps = 50 10
per_source = 50
socket_type = stream
wait = no
user = root
env = LD_LIBRARY_PATH=/opt/globus/lib
env += GLOBUS_LOCATION=/opt/globus
env += GLOBUS_TCP_PORT_RANGE=9000,9999
server = /opt/globus/sbin/globus-gridftp-server
server_args = -i -c /opt/globus/etc/gridftp.conf
log_on_success += DURATION
log_on_failure +=
nice = 10
disable = no
}
:* restart xinetd:
cress ~ # /etc/init.d/xinetd restart
* test it:
bogdanl@cress ~ $ telnet cress 2811
Trying 150.254.149.134...
Connected to cress.man.poznan.pl.
Escape character is '^]'.
220 cress.man.poznan.pl GridFTP Server 2.3 (gcc32dbg, 1144436882-63) ready.
bogdanl@cress ~ $ export GLOBUS_LOCATION=/opt/globus/gt421
bogdanl@cress ~ $ . $GLOBUS_LOCATION/etc/globus-user-env.sh
bogdanl@cress ~ $ grid-proxy-init
bogdanl@cress ~ $ globus-url-copy gsiftp://cress/~/file \
file:///tmp/file.test
bogdanl@cress ~ $ globus-url-copy gsiftp://cress/~/file \
gsiftp://cress/~/file2