GT 4.0 GridFTP : System Administrator's Guide

1. Introduction

This guide contains advanced configuration information for system administrators working with GridFTP. It provides references to information on procedures typically performed by system administrators, including installation, configuring, deploying, and testing the installation. This guide should help you configure and run the GridFTP server in some standard configurations.

[Important]Important

This information is in addition to the basic Globus Toolkit prerequisite, overview, installation, security configuration instructions in the GT 4.0 System Administrator's Guide. Read through this guide before continuing!

2. Building and Installing

GridFTP is built and installed as part of a default GT 4.0 installation. For basic installation instructions, see the GT 4.0 System Administrator's Guide. No extra installation steps are required for this component.

2.1. Building only GridFTP and Utilities

If you wish to install GridFTP without installing the rest of the Globus Toolkit, refer to the Installing GT 4.0 section of the GT 4.0 System Administrator's Guide. Perform steps 1-3, as written (Note that you do not need Ant, a JDK, or a JDBC database to build only GridFTP). However, instead of running "make" as directed in step 4,

Run:

globus$ make gridftp

If you wish to have a log file of the build, use tee:

globus$ make gridftp 2>&1 | tee build.log

The syntax above assumes a Bourne shell. If you are using another shell, redirect stderr to stdout and then pipe it to tee.

2.2. Building only the GridFTP server

If you wish to install only the GridFTP server, refer to the Installing GT 4.0 section of the GT 4.0 System Administrator's Guide for prerequisites. Follow steps 1-3 as written. However, instead of running "make" as directed in step 4,

Run:

globus$ make gpt globus_gridftp_server

If you wish to have a log file of the build, use tee:

globus$ make gpt globus_gridftp_server 2>&1 | tee build.log

The syntax above assumes a Bourne shell. If you are using another shell, redirect stderr to stdout and then pipe it to tee.

2.3. Building only the GridFTP client

If you wish to install only the GridFTP client, refer to the Installing GT 4.0 section of the GT 4.0 System Administrator's Guide for prerequisites. Follow steps 1-3 as written. However, instead of running "make" as directed in step 4,

Run:

globus$ make globus-data-management-client

If you wish to have a log file of the build, use tee:

globus$ make globus-data-management-client 2>&1 | tee build.log

The syntax above assumes a Bourne shell. If you are using another shell, redirect stderr to stdout and then pipe it to tee.

2.4. Building only the GridFTP SDK

If you wish to install only the GridFTP SDK, refer to the Installing GT 4.0 section of the GT 4.0 System Administrator's Guide for prerequisites. Follow steps 1-3 as written. However, instead of running "make" as directed in step 4,

Run:

globus$ make globus-data-management-sdk

If you wish to have a log file of the build, use tee:

globus$ make globus-data-management-sdk 2>&1 | tee build.log

The syntax above assumes a Bourne shell. If you are using another shell, redirect stderr to stdout and then pipe it to tee.

2.5. Building a combination of GridFTP elements

If you wish to build a combination of GridFTP elements, refer to the Installing GT 4.0 section of the GT 4.0 System Administrator's Guide for prerequisites. Follow steps 1-3 as written. However, instead of running "make" as directed in step 4,

Run:

globus$ make [any combination of the above commands, each separated by a space]

For example, if you just want to install the GridFTP server and client, the command would be:

globus$ make gpt globus_gridftp_server globus-data-management-client

If you wish to have a log file of the build, use tee:

globus$ make [any combination of the above commands, each separated by a space] 2>&1 | tee build.log

The syntax above assumes a Bourne shell. If you are using another shell, redirect stderr to stdout and then pipe it to tee.

2.6. Building and Installing a static GridFTP server

If you wish to build and install a statically linked set of GridFTP binaries, refer to the Installing GT 4.0 section of the GT 4.0 System Administrator's Guide for prerequisites. Follow steps 1-2 as written. In step 3, however, you should

Run:

globus$ export GLOBUS_LOCATION=/usr/local/globus-4.0.0
globus$ ./configure --prefix=$GLOBUS_LOCATION --with-buildopts="--static" 
globus$ make gpt globus_gridftp_server

If you wish to have a log file of the build, use tee:

globus$ make gpt globus_gridftp_server 2>&1 | tee build.log

The syntax above assumes a Bourne shell. If you are using another shell, redirect stderr to stdout and then pipe it to tee.

3. Configuring

3.1. GridFTP server configuration overview

Note: Command line options and configuration file options may both be used, but the command line overrides the config file.

The configuration file for the GridFTP server is read from the following locations, in the given order. Only the first found will be loaded.

  • Path specified with the -c <configfile> command line option.
  • $GLOBUS_LOCATION/etc/gridftp.conf
  • /etc/grid-security/gridftp.conf

Options are one per line, with the format:

<option> <value>

If the value contains spaces, they should be enclosed in double-quotes ("). Flags or boolean options should only have a value of 0 or 1. Blank lines and lines beginning with # are ignored.

For example:

  port 5000
  allow_anonymous 1
  anonymous_user bob
  banner "Welcome!"

3.2. GridFTP server configuration options

The table below lists config file options, associated command line options (if available) and descriptions. Note that any boolean option can be negated on the command line by preceding the specified option with '-no-' or '-n'. example: -no-cas or -nf.

Table 1. Informational Options

help <0|1>
-h
-help

Show usage information and exit.

Default value: FALSE

longhelp <0|1>
-hh
-longhelp

Show more usage information and exit.

Default value: FALSE

version <0|1>
-v
-version

Show version information for the server and exit.

Default value: FALSE

versions <0|1>
-V
-versions

Show version information for all loaded globus libraries and exit.

Default value: FALSE

Table 2. Modes of Operation

inetd <0|1>
-i
-inetd

Run under an inetd service.

Default value: FALSE

daemon <0|1>
-s
-daemon

Run as a daemon. All connections will fork off a new process and setuid if allowed.

Default value: TRUE

detach <0|1>
-S
-detach

Run as a background daemon detached from any controlling terminals.

Default value: FALSE

exec <string>
-exec <string>

For statically compiled or non-GLOBUS_LOCATION standard binary locations, specify the full path of the server binary here. Only needed when run in daemon mode.

Default value: not set

chdir <0|1>
-chdir

Change directory when the server starts. This will change directory to the dir specified by the chdir_to option.

Default value: TRUE

chdir_to <string>
-chdir-to <string>

Directory to chdir to after starting. Will use / if not set.

Default value: not set

fork <0|1>
-f
-fork

Server will fork for each new connection. Disabling this option is only recommended when debugging. Note that non-forked servers running as 'root' will only accept a single connection and then exit.

Default value: TRUE

single <0|1>
-1
-single

Exit after a single connection.

Default value: FALSE

Table 3. Authentication, Authorization, and Security Options

auth_level <number>
-auth-level <number>

0 = Disables all authorization checks. 1 = Authorize identity only. 2 = Authorize all file/resource accesses. If not set, it uses level 2 for front ends and level 1 for data nodes.

Default value: not set

allow_from <string>
-allow-from <string>

Only allow connections from these source ip addresses. Specify a comma separated list of ip address fragments. A match is any ip address that starts with the specified fragment. Example: '192.168.1.' will match and allow a connection from 192.168.1.45. Note that if this option is used any address not specifically allowed will be denied.

Default value: not set

deny_from <string>
-deny-from <string>

Deny connections from these source ip addresses. Specify a comma separated list of ip address fragments. A match is any ip address that starts with the specified fragment. Example: '192.168.2.' will match and deny a connection from 192.168.2.45.

Default value: not set

cas <0|1>
-cas

Enable CAS authorization.

Default value: TRUE

secure_ipc <0|1>
-si
-secure-ipc

Use GSI security on the ipc channel.

Default value: TRUE

ipc_auth_mode <string>
-ia <string>
-ipc-auth-mode <string>

Set GSI authorization mode for the ipc connection. Options are: none, host, self or subject:[subject].

Default value: host

allow_anonymous <0|1>
-aa
-allow-anonymous

Allow cleartext anonymous access. If server is running as root, anonymous_user must also be set. Disables ipc security.

Default value: FALSE

anonymous_names_allowed <string>
-anonymous-names-allowed <string>

Comma separated list of names to treat as anonymous users when allowing anonymous access. If not set the default names of 'anonymous' and 'ftp' will be allowed. Use '*' to allow any username.

Default value: not set

anonymous_user <string>
-anonymous-user <string>

User to setuid to for an anonymous connection. Only applies when running as root.

Default value: not set

anonymous_group <string>
-anonymous-group <string>

Group to setgid to for an anonymous connection. If not set the default group of anonymous_user will be used.

Default value: not set

pw_file <string>
-password-file <string>

Enable cleartext access and authenticate users against this /etc/passwd formatted file.

Default value: not set

connections_max <number>
-connections-max <number>

Maximum concurrent connections allowed. Only applies when running in daemon mode. Unlimited if not set.

Default value: not set

connections_disabled <0|1>
-connections-disabled

Disable all new connections. Does not affect ongoing connections. This would have to be set in the configuration file and then the server issued a SIGHUP in order to reload the config.

Default value: FALSE

Table 4. Logging Options

log_level <string>
-d <string>
-log-level <string>

Log level. A comma separated list of levels from: 'ERROR, WARN, INFO, DUMP, ALL'. Example: error,warn,info. You may also specify a numeric level of 1-255.

Default value: ERROR

log_module <string>
-log-module <string>

globus_logging module that will be loaded. If not set the default 'stdio' module will be used, and the logfile options apply. Built-in modules are 'stdio' and 'syslog'. Log module options may be set by specifying module:opt1=val1:opt2=val2. Available options for the built-in modules are 'interval' and 'buffer', for buffer flush interval and buffer size, respectively. The default options are a 64k buffer size and a 5 second flush interval. A 0 second flush interval will disable periodic flushing, and the buffer will only flush when it is full. A value of 0 for buffer will disable buffering and all messages will be written immediately. Example: -log-module stdio:buffer=4096:interval=10

Default value: not set

log_single <string>
-l <string>
-logfile <string>

Path of a single file to log all activity to. If neither this option nor log_unique is set, logs will be written to stderr unless the execution mode is detached or inetd, in which case logging will be disabled.

Default value: not set

log_unique <string>
-L <string>
      -logdir <string>

Partial path to which 'gridftp.(pid).log' will be appended to construct the log filename. Example: -L /var/log/gridftp/ will create a separate log (/var/log/gridftp/gridftp.xxxx.log) for each process (which is normally each new client session). If neither this option nor log_single is set, logs will be written to stderr unless the execution mode is detached or inetd, in which case logging will be disabled.

Default value: not set

log_transfer <string>
-Z <string>
-log-transfer <string>

Log netlogger style info for each transfer into this file.

Default value: not set

ex: DATE=20050520163008.306532 HOST=localhost PROG=globus-gridftp-server NL.EVNT=FTP_INFO START=20050520163008.305913 USER=ftp FILE=/etc/group BUFFER=0 BLOCK=262144 NBYTES=542 VOLUME=/ STREAMS=1 STRIPES=1 DEST=[127.0.0.1] TYPE=RETR CODE=226

Time format is YYYYMMDDHHMMSS.UUUUUU (microsecs).

DATE: time the transfer completed.

START: time the transfer started.

HOST: hostname of the server.

USER: username on the host that transfered the file.

BUFFER: tcp buffer size (if 0 system defaults were used).

BLOCK: the size of the data block read from the disk and posted to the network.

NBYTES: the total number of bytes transfered.

VOLUME: the disk partition where the transfer file is stored.

STREAMS: the number of parallel TCP streams used in the transfer.

STRIPES: the number of stripes used on this end of the transfer.

DEST: the destination host.

TYPE: the transfer type, RETR is a send and STOR is a receive (ftp 959 commands).

CODE: the FTP rfc959 completion code of the transfer. 226 indicates success, 5xx or 4xx are failure codes.

log_filemode <string>
-log-filemode <string>

File access permissions of log files. Should be an octal number such as 0644 (the leading 0 is required).

Default value: not set

disable_usage_stats <0|1>
-disable-usage-stats

Disable transmission of per-transfer usage statistics. See the Usage Statistics section in the online documentation for more information.

Default value: FALSE

usage_stats_target <string>
-usage-stats-target <string>

Comma separated list of contact strings for usage statistics listeners. The format of <string> is host:port.

Default value: usage-stats.globus.org:4810

Example:

-usage-stats-target usage-stats.globus.org:4810,usage-stats.uc.teragrid.org:5920

In this example, the usage statistics will be transmitted to the default Globus target (usage-stats.globus.org:4810) and another target (usage-stats.uc.teragrid.org:5920).

Table 5. Single and Striped Remote Data Node Options

remote_nodes <string>
-r <string>
-remote-nodes <string>

Comma separated list of remote node contact strings.

Default value: not set

data_node <0|1>
-dn
-data-node

This server is a back end data node.

Default value: FALSE

stripe_blocksize <number>
-sbs <number>
-stripe-blocksize <number>

Size in bytes of sequential data that each stripe will transfer.

Default value: 1048576

stripe_layout <number>
-sl <number>
-stripe-layout <number>

Stripe layout. 1 = Partitioned, 2 = Blocked.

Default value: 2

stripe_blocksize_locked <0|1>
-stripe-blocksize-locked

Do not allow client to override stripe blocksize with the OPTS RETR command.

Default value: FALSE

stripe_layout_locked <0|1>
-stripe-layout-locked

Do not allow client to override stripe layout with the OPTS RETR command.

Default value: FALSE

Table 6. Disk Options

blocksize <number>
-bs <number>
-blocksize <number>

Size in bytes of data blocks to read from disk before posting to the network.

Default value: 262144

sync_writes <0|1>
-sync-writes

Flush disk writes before sending a restart marker. This attempts to ensure that the range specified in the restart marker has actually been committed to disk. This option will probably impact performance and may result in different behavior on different storage systems. See the man page for sync() for more information.

Default value: FALSE

Table 7. Network Options

port <number>
-p <number>
-port <number>

Port on which a front end will listen for client control channel connections or on which a data node will listen for connections from a front end. If not set a random port will be chosen and printed via the logging mechanism.

Default value: not set

control_interface <string>
-control-interface <string>

Hostname or IP address of the interface to listen for control connections on. If not set will listen on all interfaces.

Default value: not set

data_interface <string>
-data-interface <string>

Hostname or IP address of the interface to use for data connections. If not set will use the current control interface.

Default value: not set

ipc_interface <string>
-ipc-interface <string>

Hostname or IP address of the interface to use for ipc connections. If not set will listen on all interfaces.

Default value: not set

hostname <string>
-hostname <string>

Effectively sets the above control_interface, data_interface and ipc_interface options.

Default value: not set

ipc_port <number>
-ipc-port <number>

Port on which the front end will listen for data node connections.

Default value: not set

Table 8. Timeouts

control_preauth_timeout <number>
-control-preauth-timeout <number>

Time in seconds to allow a client to remain connected to the control channel without activity before authenticating.

Default value: 120 (GT 4.0.6 and prior releases had a default value of 30. Based on user experience, it has been increased to 120 in GT 4.0.7)

control_idle_timeout <number>
-control-idle-timeout <number>

Time in seconds to allow a client to remain connected to the control channel without activity.

Default value: 600

ipc_idle_timeout <number>
-ipc-idle-timeout <number>

Idle time in seconds before an unused ipc connection will close.

Default value: 600

ipc_connect_timeout <number>
-ipc-connect-timeout <number>

Time in seconds before cancelling an attempted ipc connection.

Default value: 60

Table 9. User Messages

banner <string>
-banner <string>

Message to display to the client before authentication.

Default value: not set

banner_file <string>
-banner-file <string>

File to read banner message from.

Default value: not set

banner_terse <0|1>
-banner-terse

When this is set, the minimum allowed banner message will be displayed to unauthenticated clients.

Default value: FALSE

login_msg <string>
-login-msg <string>

Message to display to the client after authentication.

Default value: not set

login_msg_file <string>
-login-msg-file <string>

File to read login message from.

Default value: not set

Table 10. Module Options

load_dsi_module <string>
-dsi <string>

Data Storage Interface module to load. File and remote modules are defined by the server. If not set the file module is loaded, unless the 'remote' option is specified, in which case the remote module is loaded. An additional configuration string can be passed to the DSI using the format [module name]:[configuration string]. The format of the configuration string is defined by the DSI being loaded.

Default value: not set

allowed_modules <string>
-allowed-modules <string>

Comma separated list of ERET/ESTO modules to allow and, optionally, specify an alias for. Example: module1,alias2:module2,module3 (module2 will be loaded when a client asks for alias2).

Default value: not set

Table 11. Other

configfile <string>
-c <string>

Path to configuration file that should be loaded. Otherwise will attempt to load $GLOBUS_LOCATION/etc/gridftp.conf and /etc/grid-security/gridftp.conf.

Default value: not set

use_home_dirs <0|1>
-use-home-dirs

Set the startup directory to the authenticated user's home dir.

Default value: TRUE

debug <0|1>
-debug

Set options that make the server easier to debug. Forces no-fork, no-chdir, and allows core dumps on bad signals instead of exiting cleanly. Not recommended for production servers. Note that non-forked servers running as root will only accept a single connection and then exit.

Default value: FALSE

3.3. Configuring the GridFTP server to run under xinetd/inetd

Note: The service name used (gsiftp in this case) should be defined in /etc/services with the desired port.

Here is a sample gridftp server xinetd config entry:

service gsiftp
{
instances               = 100
socket_type             = stream
wait                    = no
user                    = root
env                     += GLOBUS_LOCATION=(globus_location)
env                     += LD_LIBRARY_PATH=(globus_location)/lib
server                  = (globus_location)/sbin/globus-gridftp-server
server_args             = -i
log_on_success          += DURATION
nice                    = 10
disable                 = no
}

Here is a sample gridftp server inetd config entry (read as a single line):

gsiftp   stream   tcp   nowait   root   /usr/bin/env env   \
    GLOBUS_LOCATION=(globus_location)                      \
    LD_LIBRARY_PATH=(globus_location)/lib                  \ 
    (globus_location)/sbin/globus-gridftp-server -i

[Note]Note

On Mac OS X, you must set DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH in the above examples. On IRIX, you may need to set either LD_LIBRARYN32_PATH or LD_LIBRARY64_PATH. However, on OS X you could also use launchd, as shown below.

Here is a sample Mac OS X launchd config entry. Create a "/Library/LaunchDaemons/gsiftp.plist" file. An example is below. Edit it to have the right paths for your installation. Then run "sudo launchctl load /Library/LaunchDaemsons/gsiftp.plist".

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http:// www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
         <key>Debug</key>
         <true/>
         <key>EnvironmentVariables</key>
         <dict>
                 <key>DYLD_LIBRARY_PATH</key>
                 <string>/usr/local/gt4/lib</string>
                 <key>GLOBUS_LOCATION</key>
                 <string>/usr/local/gt4</string>
         </dict>
         <key>GroupName</key>
         <string>admin</string>
         <key>Label</key>
         <string>org.globus.gridftp</string>
         <key>OnDemand</key>
         <true/>
         <key>ProgramArguments</key>
         <array>
                 <string>/usr/local/gt4/sbin/globus-gridftp-server</ 
string>
                 <string>-i</string>
         </array>
         <key>ServiceDescription</key>
         <string>GridFTP</string>
         <key>Sockets</key>
         <dict>
                 <key>Listeners</key>
                 <dict>
                         <key>SockFamily</key>
                         <string>IPv4</string>
                         <key>SockPassive</key>
                         <true/>
                         <key>SockServiceName</key>
                         <string>gsiftp</string>
                         <key>SockType</key>
                         <string>stream</string>
                 </dict>
         </dict>
         <key>UserName</key>
         <string>root</string>
         <key>inetdCompatibility</key>
         <dict>
                 <key>Wait</key>
                 <false/>
         </dict>
</dict>
</plist>

3.4. Configuring GridFTP to run with the Community Authorization Service (CAS)

The Community Authorization Service (CAS) is used to administer access rights to files and directories and the GridFTP server can be configured to enforce those rights.

For more information, see How to Set Up CAS to Use with GridFTP.

4. Deploying the GridFTP Server: globus-gridftp-server

It is assumed that the toolkit installation was successful and that Globus security is properly configured. For more information, see the Installation Guide.

4.1. Running in daemon mode

The server should generally be run as root in daemon mode, though it is possible to run it as a user (see below). When run as root you will need to have a host certificate.

Run the server:

globus-gridftp-server < -s | -S > <args>

where:

-s
Runs in the foreground (this is the default mode).
-S
Detaches from the terminal and runs in the background.

The following additional steps may be required when running as a user other than root:

  • Create a ~/.gridmap file, containing the DNs of any clients you wish to allow, mapped to the current username.
  • Create a proxy with grid-proxy-init.

4.2. Running under inetd or xinetd

The -i command line option enables the server to be run under inetd or xinetd.

See Configuring GridFTP for example xinetd and inetd configuration entries.

4.3. Remote data-nodes and striped operation

The GridFTP server now supports separate front end (client control connection) and back end (data node) processes. In addition, a single front end process may connect to multiple back end data nodes.

When multiple back end data nodes are available, the server is said to be in a striped configuration, or simply, is a striped server. In this mode transfers are divided over all available data nodes, thus allowing the combined bandwidth of all data nodes to be used.

Note: The connection between the front end and data nodes is referred to as the ipc channel.

The ability to use inetd or daemon execution modes applies to both front end servers and data nodes, and the same certificate and user requirements apply.

To start the front end:

globus-gridftp-server <args> -r <host:port>[,<host:port>,...]

To start the data-node:

globus-gridftp-server -p <port> -dn

The -p <port> option used on the data-node is the port that will be used for ipc connections. This is the port that you will register with the front end server.

For example:

machineB> globus-gridftp-server -p 6000 -dn
machineC> globus-gridftp-server -p 7000 -dn
machineA> globus-gridftp-server -p 5000 -r machineB:6000,machineC:7000

The client would only connect to the front end at machineA:5000, for example, using globus-url-copy with the -stripe option:

globus-url-copy -stripe gsiftp://machineA:5000/file file:///destination
   or
globus-url-copy -stripe gsiftp://machineA:5000/file gsiftp://machineX/destination

Where machineX may be another striped server or a standard GridFTP server.

4.4. Separation of Processes

As is illustrated above, the GridFTP server can be separated into front end and data node processes. This is the architecture used to achieve a striped server, but it can also be exploited to achieve a higher level of security.

Running the server as root is often desirable because it allows the server to fork and setuid on a child processes related to an authenticated user. This allows the server to leverage the operating systems file system permissions and other security devices. However, it is not at all desirable to have a root running process listening on a port open to the world. If an attacker were to compromise the process they could obtain root level access to the machine.

To overcome this security risk the gridftp server can be run in a front end/back end manner. The front end can be run as any user, say user globus, that has very limited access to the machine. The front end is the processes open to the outside world. If it is compromised an attacker has only gained access to that limited account. The back end is run as root, but configured to only allow connections from the front end.

To start the front end:

globus-gridftp-server -p 7000 -r localhost:7001

and the back end:

globus-gridftp-server -p 7001 -dn -allow-from 127.0.0.1

5. Testing

If the globus-ftp-client-test package has been installed, our standard test suite may be run to verify functionality on your platform. Simply set up the globus environment, chdir to $GLOBUS_LOCATION/test/globus_ftp_client_test/ and run ./TESTS.pl.

6. Security Considerations

The following are points to consider relative to security:

6.1. Two ways to configure your server

We now provide two ways to configuring your server:

  • The classic installation. This is equivalent to any FTP server you would normally install. It is run as a root setuid process. Once the user is authenticated, the process does a setuid to the appropriate non-privileged user account.
  • A new split process installation. In this configuration, the server consists of two processes:

    • The control channel (the process the external user connects to) runs as a non-privileged user (typically the globus user).
    • The data channel (the process that access the file system and moves the data) runs as a root setuid program as before but is only contacted by the control channel process from a local machine. This means an external user is never connected to a root running process and thus minimizes the impact of an exploit. This does, however, require that a copy of the host cert and host key be owned by the non-privileged user. If you use this configuration, the non-privileged user should not have write permission to executables, configuration files, etc.

6.2. New authentication options

There are new authentication options available for the server in GT4.0.0:

  • Anonymous: The server now supports anonymous access. In order for this to work, a configuration switch must explicitly enable it, a list of acceptable usernames must be defined, and an account under which the anonymous user should run must be defined. If the necessary configurations are in place, and the client presents a username that is in the list of acceptable anonymous users, then the session will be accepted and the process will setuid to the anonymous user account. We do not support chroot in this version of the server.
  • Username / Password: This is standard FTP authentication. It uses a separate password file, used only by the GridFTP server, *NOT* the system password file.
[Warning]Warning

WE HIGHLY RECOMMEND YOU NOT USE THIS. YOU WILL BE SENDING YOUR PASSWORD IN CLEAR TEXT OVER THE NETWORK.

We do, however, have some user communities who run only on internal networks for testing purposes and who do not wish to deal with obtaining GSI credentials. If you are considering this, we would recommend that you look at Simple CA and set up your own testbed CA. This can be done in less than an hour and then provides you full GSI security.

6.3. Firewall requirements

If the GridFTP server is behind a firewall:

  1. Contact your network administrator to open up port 2811 (for GridFTP control channel connection) and a range of ports (for GridFTP data channel connections) for the incoming connections. If the firewall blocks the outgoing connections, open up a range of ports for outgoing connections as well.

  2. Set the environment variable GLOBUS_TCP_PORT_RANGE:

    export GLOBUS_TCP_PORT_RANGE=min,max 

    where min,max specify the port range that you have opened for the incoming connections on the firewall. This restricts the listening ports of the GridFTP server to this range. Recommended range is 1000 (e.g., 50000-51000) but it really depends on how much use you expect.

  3. If you have a firewall blocking the outgoing connections and you have opened a range of ports, set the environment variable GLOBUS_TCP_SOURCE_RANGE:

    export GLOBUS_TCP_SOURCE_RANGE=min,max 

    where min,max specify the port range that you have opened for the outgoing connections on the firewall. This restricts the outbound ports of the GridFTP server to this range. Recommended range is twice the range used for GLOBUS_TCP_PORT_RANGE, because if parallel TCP streams are used for transfers, the listening port would remain the same for each connection but the connecting port would be different for each connection.

[Note]Note

If the server is behind NAT, the --data-interface <real ip/hostname> option needs to be used on the server.

If the GridFTP client is behind a firewall:

  1. Contact your network administrator to open up a range of ports (for GridFTP data channel connections) for the incoming connections. If the firewall blocks the outgoing connections, open up a range of ports for outgoing connections as well.

  2. Set the environment variable GLOBUS_TCP_PORT_RANGE

    export GLOBUS_TCP_PORT_RANGE=min,max 

    where min,max specify the port range that you have opened for the incoming connections on the firewall. This restricts the listening ports of the GridFTP client to this range. Recommended range is 1000 (e.g., 50000-51000) but it really depends on how much use you expect.

  3. If you have a firewall blocking the outgoing connections and you have opened a range of ports, set the environment variable GLOBUS_TCP_SOURCE_RANGE:

    export GLOBUS_TCP_PORT_RANGE=min,max 

    where min,max specify the port range that you have opened for the outgoing connections on the firewall. This restricts the outbound ports of the GridFTP client to this range. Recommended range is twice the range used for GLOBUS_TCP_PORT_RANGE, because if parallel TCP streams are used for transfers, the listening port would remain the same for each connection but the connecting port would be different for each connection.

Additional information on Globus Toolkit Firewall Requirements is available here.

7. Troubleshooting

If you are having problems using the GridFTP server, try the steps listed below. If you have an error, try checking the server logs if you have access to them. By default, the server logs to stderr, unless it is running from inetd, or its execution mode is detached, in which case logging is disabled by default.

The command line options -d , -log-level, -L and -logdir can affect where logs will be written, as can the configuration file options log_single and log_unique. See the Configuration information for more information on these and other configuration options.

7.1. Establish control channel connection

Verify that you can establish a control channel connection and that the server has started successfully by telnetting to the port on which the server is running:

% telnet localhost 2811
                Trying 127.0.0.1...
                Connected to localhost.
                Escape character is '^]'.
                220 GridFTP Server mldev.mcs.anl.gov 2.0 (gcc32dbg, 1113865414-1) ready.

If you see anything other than a 220 banner such as the one above, the server has not started correctly.

Verify that there are no configuration files being unexpectedly loaded from /etc/grid-security/gridftp.conf or $GLOBUS_LOCATION/etc/gridftp.conf. If those files exist, and you did not intend for them to be used, rename them to .save, or specify -c none on the command line and try again.

If you can log into the machine where the server is, try running the server from the command line with only the -s option:

$GLOBUS_LOCATION/sbin/globus-gridftp-server -s

The server will print the port it is listening on:

Server listening at gridftp.mcs.anl.gov:57764

Now try and telnet to that port. If you still do not get the banner listed above, something is preventing the socket connection. Check firewalls, tcp-wrapper, etc.

If you now get a correct banner, add -p 2811 (you will have to disable (x)inetd on port 2811 if you are using them or you will get port already in use):

$GLOBUS_LOCATION/sbin/globus-gridftp-server -s -p 2811

Now telnet to port 2811. If this does not work, something is blocking port 2811. Check firewalls, tcp-wrapper, etc.

If this works correctly then re-enable your normal server, but remove all options but -i, -s, or -S.

Now telnet to port 2811. If this does not work, something is wrong with your service configuration. Check /etc/services and (x)inetd config, have (x)inetd restarted, etc.

If this works, begin adding options back one at a time, verifying that you can telnet to the server after each option is added. Continue this till you find the problem or get all the options you want.

At this point, you can establish a control connection. Now try running globus-url-copy.

7.2. Try running globus-url-copy

Once you've verified that you can establish a control connection, try to make a transfer using globus-url-copy.

If you are doing a client/server transfer (one of your URLs has file: in it) then try:

globus-url-copy -vb -dbg gsiftp://host.server,running.on/dev/zero file:///dev/null

This will run until you control-c the transfer. If that works, reverse the direction:

globus-url-copy -vb -dbg file:///dev/zero gsiftp://host.server.running.on/dev/null

Again, this will run until you control-c the transfer.

If you are doing a third party transfer, run this command:

globus-url-copy -vb -dbg gsiftp://host.server1.on/dev/zero gsiftp://host.server2.on/dev/null

Again, this will run until you control-c the transfer.

If the above transfers work, try your transfer again. If it fails, you likely have some sort of file permissions problem, typo in a file name, etc.

7.3. If your server starts...

If the server has started correctly, and your problem is with a security failure or gridmap lookup failure, verify that you have security configured properly here.

If the server is running and your client successfully authenticates but has a problem at some other time during the session, please ask for help on gt-user@globus.org. When you send mail or submit bugs, please always include as much of the following information as possible:

  • Specs on all hosts involved (OS, processor, RAM, etc).
  • globus-url-copy -version
  • globus-url-copy -versions
  • Output from the telnet test above.
  • The actual command line you ran with -dbg added. Don't worry if the output gets long.
  • Check that you are getting a FQDN and /etc/hosts that is sane.
  • The server configuration and setup (/etc/services entries, (x)inetd configs, etc.).
  • Any relevant lines from the server logs (not the entire log please).

8. Usage statistics collection by the Globus Alliance

The following GridFTP-specific usage statistics are sent in a UDP packet at the end of each transfer, in addition to the standard header information described in the Usage Stats section.

  • Start time of the transfer
  • End time of the transfer
  • Version string of the server
  • TCP buffer size used for the transfer
  • Block size used for the transfer
  • Total number of bytes transferred
  • Number of parallel streams used for the transfer
  • Number of stripes used for the transfer
  • Type of transfer (STOR, RETR, LIST)
  • FTP response code -- Success or failure of the transfer

[Note]Note

The client (globus-url-copy) does NOT send any data. It is the servers that send the usage statistics.

We have made a concerted effort to collect only data that is not too intrusive or private and yet still provides us with information that will help improve and gauge the usage of the GridFTP server. Nevertheless, if you wish to disable this feature for GridFTP only, see the Logging section of Section 3.2, “GridFTP server configuration options”. Note that you can disable transmission of usage statistics globally for all C components by setting "GLOBUS_USAGE_OPTOUT=1" in your environment.

Also, please see our policy statement on the collection of usage statistics.