This document is a work-in-progress and applies to this development release. The latest drafts of docs can be found in the Development Documentation directory. You are strongly encouraged to file bugs for both the development documentation and software on our Bugzilla page. We appreciate your participation.
GT 3.9.5 GridFTP : System Administrator's Guide
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.
This information is in addition to the basic installation instructions in
the GT 3.9.5 System Administrator's Guide.
Building and Installing
GridFTP is built and installed as part of
a default GT 3.9.5 installation. For basic installation instructions, see the
GT 3.9.5 System Administrator's Guide.
No extra installation steps are required for this component.
Configuring
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 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 allowed 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 begining with # are ignored.
For example:
port 5000
allow_anonymous 1
anonymous_user bob
banner "Welcome!"
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.
| Informational Options |
|
|
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 |
| Modes of Operation |
|
|
Run under an inetd service. Default value: FALSE |
|
|
Run as a daemon. All connections will fork off a new process and setuid if allowed. Default value: TRUE |
|
|
Run as a background daemon detached from any controlling terminals. Default value: FALSE |
exec <string> |
-exec <string> |
|
For staticly 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 |
|
|
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 |
|
|
Server will fork for each new connection. Disabling this option is only recommended when debugging. Default value: TRUE |
|
|
Exit after a single connection Default value: FALSE |
| 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 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 seperated 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 seperated 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 |
|
|
Enable CAS authorization. Default value: TRUE |
secure_ipc <0|1> |
-si
-secure-ipc |
|
Use GSI security on 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: 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 seperated 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 unset, 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 be set in the configuration file and then the server issued a SIGHUP in order to reload that config. Default value: FALSE |
| Logging Options |
log_level <string> |
-d <string>
-log-level <string> |
|
Log level. A comma seperated 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, logfile options apply. 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 or 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 seperate log ( /var/log/gridftp/gridftp.xxxx.log ) for each process (which is normally each new client session). If neither this option or 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 |
log_filemode <number> |
-log-filemode <number> |
|
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 seperated list of contact strings for usage statistics listeners. Default value: not set |
| Single and Striped Remote Data Node Options |
remote_nodes <string> |
-r <string>
-remote-nodes <string> |
|
Comma seperated list of remote node contact strings. Default value: not set |
data_node <0|1> |
-dn
-data-node |
|
This server is a backend 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 |
| 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 manpage for sync() for more information. Default value: FALSE |
| Network Options |
port <number> |
-p <number>
-port <number> |
|
Port on which a frontend will listend for client control channel connections, or on which a data node will listen for connections from a frontend. 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 frontend will listen for data node connections. Default value: not set |
| 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 |
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 |
| 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 |
| Module Options |
load_dsi_module <string> |
-dsi <string> |
|
Data Storage Interface module to load. file and remote modules are defined by the server. Defaults to file unless the 'remote' option is specified, in which case the remote DSI is loaded. Default value: file |
allowed_modules <string> |
-allowed-modules <string> |
|
Comma seperated 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 |
| 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 users home dir. Default value: TRUE |
|
|
Sets options that make server easier to debug. Not recommended for production servers. Default value: FALSE |
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
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. Also be sure to
reference the GridFTP
configuration and command line options.
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 proxy:
grid-proxy-init
Running under inetd or xinetd
The -i command line option enables the server to be run under inetd or xinetd.
See the Configuration and
command line options section for example xinetd and inetd configuration
entries.
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.
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
Please also see the
Call for Community Testing.
Security Considerations
[describe security considerations relevant for
this component]
Troubleshooting
If you are having problems using the GridFTP server, you should try these steps:
Verify that the server has started successfully. The easiest way to do this is to
telnet 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 localhost.localdomain 0.11 (gcc32dbg, 1098910702-1) ready.
If you see anything other than a 220 banner such as that, then the server has not started correctly.
Verify that you have the options you expect. Try no other options besides -s, -i, or -p (the server defaults
should be fine in most cases). Verify that there are no configuration files being unexpectedly loaded
from /etc/grid-security/gridftp.conf or $GLOBUS_LOCATION/etc/gridftp.conf. If all else fails and
you still cannot pass this test, seek help on discuss@globus.org
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 succesfully authenticates, but has a problem
at some other time during the session, please ask for help on discuss@globus.org
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
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 the
GridFTP
configuration and command line 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.
