Description

The ftp task implements a basic FTP client that can send, receive,
list, delete files, and create directories. See below for descriptions and examples of how
to perform each task.

Note: This task depends on external libraries not included in the Apache Ant distribution.
See Library Dependencies for more information.
Get the latest version of this library, for the best support in Ant

The ftp task attempts to determine what file system is in place on the FTP server.
Supported server types are Unix, NT, OS2, VMS, and OS400. In addition, NT and OS400 servers
which have been configured to display the directory in Unix style are also supported correctly.
Otherwise, the system will default to Unix standards.
remotedir must be specified in the exact syntax required by the ftp
server. If the usual Unix conventions are not supported by the server,
separator can be used to set the file separator that should be used
instead.

See the section on directory based
tasks, on how the inclusion/exclusion of files works, and how to
write patterns.

This task does not currently use the proxy information set by the
<setproxy> task, and cannot go through
a firewall via socks.

Warning: there have been problems reported concerning the ftp get with the newer attribute.
Problems might be due to format of ls -l differing from what is expected by commons-net,
for instance due to specificities of language used by the ftp server in the directory listing.
If you encounter such a problem, please send an email including a sample directory listing
coming from your ftp server (ls -l on the ftp prompt).

If you can connect but not upload or download, try setting the passive
attribute to true to use the existing (open) channel, instead of having the server
try to set up a new connection.

selects passive-mode ("yes") transfers, for
better through-firewall connectivity, at the price
of performance.
Defaults to "no"

No

verbose

displays information on each file transferred if set
to "yes". Defaults to "no".

No

depends

transfers only new or changed files if set to
"yes". Defaults to "no".

No

newer

a synonym for depends.
see timediffauto and timediffmillis

No

timediffauto

set to "true"
to make ant calculate the time difference between client and server.requires write access in the remote directory
Since ant 1.6

No

timestampGranularity

Specify either MINUTE, NONE,
(or you may specify "" which is equivalent to not specifying a value,
useful for property-file driven scripts). Allows override of the typical situation
in PUT and GET where local filesystem timestamps are HH:mm:ss
and the typical FTP server's timestamps are HH:mm. This can throw
off uptodate calculations. However, the default values should suffice for most
applications.
Since ant 1.7

No. Only applies in "puts" and "gets" where the
default values are MINUTE for PUT and NONE for GET.
(It is not as necessary in GET because we have the preservelastmodified option.)

timediffmillis

Deprecated. Number of milliseconds to add to the time on
the remote machine to get the time on the local machine. The timestampGranularity
attribute (for which the default values should suffice in most situations), and the
serverTimeZoneConfig option, should make this unnecessary.
serverTimeZoneConfig does the math for you and also knows about
Daylight Savings Time.
Since ant 1.6

No

separator

sets the file separator used on the ftp server.
Defaults to "/".

No

umask

sets the default file permissions for new files,
unix only.

No

chmod

sets or changes file permissions for new or existing files,
unix only. If used with a put action, chmod will be issued for each file.

No

listing

the file to write results of the "list" action.
Required for the "list" action, ignored otherwise.

No

ignoreNoncriticalErrors

flag which permits the task to ignore some non-fatal error
codes sent by some servers during directory creation: wu-ftp in particular.
Default: false

No

skipFailedTransfers

flag which enables unsuccessful file put, delete
and get operations to be skipped with a warning and the
remainder of the files still transferred. Default: false

No

preservelastmodified

Give the copied files the same last modified
time as the original source files (applies to getting files only).
(Note: Ignored on Java 1.1)

No; defaults to false.

retriesAllowed

Set the number of retries allowed on an file-transfer operation.
If a number > 0 specified, each file transfer can fail up to that
many times before the operation is failed. If -1 or "forever" specified, the
operation will keep trying until it succeeds.

No; defaults to 0

siteCommand

Set the server-specific SITE command to execute if
the action attribute has been specified as "site".

No

initialSiteCommand

Set a server-specific SITE command to execute immediately
after login.

No

enableRemoteVerification

Whether data connection should be verified to
connect to the same host as the control connection. This is a
security measure that is enabled by default, but it may be useful
to disable it in certain firewall scenarios.
since Ant 1.8.0

If none of these is specified, the default mechanism of letting the system
auto-detect the server OS type based on the FTP SYST command and assuming
standard formatting for that OS type will be used.

To aid in property-file-based development where a build script is configured
with property files, for any of these attributes, a value of ""
is equivalent to not specifying it.

Please understand that these options are incompatible with the autodetection
scheme. If any of these options is specified, (other than with a value of
"" ) a system type must be chosen and if systemTypeKey is not
specified, UNIX will be assumed. The philosophy behind this is that these
options are for setting non-standard formats, and a build-script author who
knows what system he is dealing with will know what options to need to be
set. Otherwise, these options should be left alone and the default
autodetection scheme can be used and will work in the majority of cases.

systemTypeKey

Specifies the type of system in use on the server.
Supported values are "UNIX", "VMS", "WINDOWS", "OS/2", "OS/400",
"MVS". If not specified, (or specified as "") and if
no other xxxConfig attributes are specified, the autodetection mechanism
based on the FTP SYST command will be used.
Since ant 1.7

No, but if any of the following xxxConfig
attributes is specified, UNIX will be assumed, even if ""
is specified here.

serverTimeZoneConfig

Specify as a Java
TimeZone identifier, (e.g. GMT, America/Chicago or
Asia/Jakarta) the timezone used by the server for timestamps. This
enables timestamp dependency checking even when the server is in a different
time zone from the client. Time Zones know, also, about daylight savings time,
and do not require you to calculate milliseconds of difference. If not specified,
(or specified as ""), the time zone of the client is assumed.
Since ant 1.7

No

defaultDateFormatConfig

Specify in Java
SimpleDateFormat notation, (e.g.
yyyy-MM-dd), the date format generally used by the FTP server
to parse dates. In some cases this will be the only date format used.
In others, (unix for example) this will be used for dates
older than a year old. (See recentDateFormatConfig). If not specified,
(or specified as ""), the default date format for the system
type indicated by the systemTypeKey attribute will be used.
Since ant 1.7

No.

recentDateFormatConfig

Specify in Java
SimpleDateFormat notation,
(e.g. MMM dd hh:mm) the date format used by the FTP server
to parse dates less than a year old. If not specified (or specified as
""), and if the system type indicated by the system key uses
a recent date format, its standard format will be used.
Since ant 1.7

No

serverLanguageCodeConfig

a
two-letter ISO-639 language code used to specify the
language used by the server to format month names. This only needs to be
specified when the server uses non-numeric abbreviations for months in its
date listings in a language other than English. This appears to be
becoming rarer and rarer, as commonly distributed ftp servers seem
increasingly to use English or all-numeric formats.
Languages supported are:

en - English

fr - French

de - German

it - Italian

es - Spanish

pt - Portuguese

da - Danish

sv - Swedish

no - Norwegian

nl - Dutch

ro - Romanian

sq - Albanian

sh - Serbo-croatian

sk - Slovak

sl - Slovenian

If you require a language other than the above, see also the
shortMonthNamesConfig attribute.
Since ant 1.7

No

shortMonthNamesConfig

specify the month abbreviations used on the server in file
timestamp dates as a pipe-delimited string for each month. For example,
a set of month names used by a hypothetical
Icelandic FTP server might conceivably be specified as
"jan|feb|mar|apr|maí|jún|júl|ágú|sep|okt|nóv|des".
This attribute exists primarily to support languages not supported by
the serverLanguageCode attribute.
Since ant 1.7

No

Note about remotedir attribute

Action

meaning of remotedir

use of nested fileset
(s)

send/put

base directory to
which the files are sent

they are used normally and
evaluated on the local machine

recv/get

base directory from
which the files are retrieved

the remote files located under
the remotedir matching the include/exclude patterns of
the fileset

del/delete

base directory from
which files get deleted

the remote files located under
the remotedir matching the include/exclude patterns of
the fileset

list

base directory from
which files are listed

the remote files located under
the remotedir matching the include/exclude patterns of
the fileset

mkdir

directory to create

not used

chmod

base directory from
which the mode of files get changed

the remote files located under
the remotedir matching the include/exclude patterns of
the fileset

rmdir

base directory from
which directories get removed

the remote directories located
under the remotedir matching the include/exclude
patterns of the fileset

Parameters specified as nested elements

fileset

The ftp task supports any number of nested <fileset> elements to specify
the files to be retrieved, or deleted, or listed, or whose mode you want to change.

The attribute followsymlinks of fileset is supported on
local (put) as well as remote (get, chmod, delete) filesets.
Before ant 1.6 there was no support of symbolic links in remote filesets.
In order to exclude symbolic links (preserve the behavior of ant 1.5.x and older),
you need to explicitly set followsymlinks to false.
On remote filesets hidden files are not checked for being symbolic links. Hidden
files are currently assumed to not be symbolic links.

Sending Files

The easiest way to describe how to send files is with a couple of examples:

Logs in to ftp.apache.org at port 2121 as
coder with password java1 and uploads all new or
changed HTML files in the htdocs/manual directory to the
/pub/incoming directory. The files are transferred in text mode.
Passive mode has been switched on to send files from behind a firewall.

Logs in to a Windows server at ftp.hypothetical.india.org
at port 2121 as coder with password java1
and uploads all new or changed (accounting for timezone differences)
HTML files in the htdocs/manual
directory to the /pub/incoming directory. The files are transferred
in text mode.

Logs in to the Windows-based ftp.nt.org as
coder with password java1 and uploads all
HTML files in the htdocs/manual directory to the
c:\uploads directory. Progress messages are displayed as each
file is uploaded.

Getting Files

Getting files from an FTP server works pretty much the same way as
sending them does. The only difference is that the nested filesets
use the remotedir attribute as the base directory for the files on the
FTP server, and the dir attribute as the local directory to put the files
into. The file structure from the FTP site is preserved on the local machine.

If apache.org ever switches to a unix FTP server that uses the new all-numeric
format for timestamps, this version would become necessary. It would accomplish
the same functionality as the previous example but would successfully handle the
numeric timestamps.
The systemTypeKey is not necessary here but helps clarify what is
going on.

Logs into a UNIX FTP server at ftp.hypothetical.fr which displays
dates with French names in Standard European format, as anonymous, and
recursively downloads all .html files from default directory for that user
into the htdocs/manual directory on the local machine.

Deleting Files

As you've probably guessed by now, you use nested fileset elements to
select the files to delete from the remote FTP server. Again, the
filesets are relative to the remote directory, not a local directory. In
fact, the dir attribute of the fileset is ignored completely.

Listing Files

This provides a file listing in data/ftp.listing of all the files on
the FTP server relative to the default directory of the anonymous
user. The listing is in whatever format the FTP server normally lists files.

Creating Directories

Note that with the mkdir action, the directory to create is specified using the
remotedir attribute.

This creates the directory some/remote/dir beneath the default root
directory. As with all other actions, the directory separator character must be correct
according to the desires of the FTP server.

Removing Directories

This action uses nested fileset elements to
select the directories to remove from the remote FTP server. The
filesets are relative to the remote directory, not a local directory.
The dir attribute of the fileset is ignored completely.
The directories to be removed must be empty, or contain only
other directories that have been also selected to be removed by the filesets
patterns, otherwise a BuildException will be thrown.
Also, if you don't have permission to remove a directory, a BuildException is
thrown.

Logs in to ftp.apache.org as anonymous and
tries to remove /somedir/dira directory and
all the directories tree starting at, and including, /somedir/dirb.
When removing the /somedir/dirb tree,
it will start at the leaves moving up to the root, so that when
it tries to remove a directory it is sure all the directories under it are
already removed.
Obviously all the files in the tree must have been already deleted.

As an example suppose you want to delete everything contained into
/somedir, so invoke first the <ftp> task with
action="delete", then with
action="rmdir" specifying in both cases
remotedir="/somedir" and

<fileset>
<include name="**"/>
</fileset>

The directory specified in the remotedir parameter is never
selected for remove, so if you need to remove it, specify its parent in
remotedir parameter and include it in the
<fileset> pattern, like "somedir/**".