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 Ant distribution. See Library Dependencies for more information.
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 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).
| Attribute | Description | Required |
| server | the address of the remote ftp server. | Yes |
| port | the port number of the remote ftp server. Defaults to port 21. | No |
| userid | the login id to use on the ftp server. | Yes |
| password | the login password to use on the ftp server. | Yes |
| remotedir | remote directory on the ftp server see table below for detailed usage | No |
| action | the ftp action to perform, defaulting to "send". Currently supports "put", "get", "del", "list", "chmod", "mkdir" and "rmdir". | No |
| binary | selects binary-mode ("yes") or text-mode ("no") transfers. Defaults to "yes" | No |
| passive | selects passive-mode ("yes") transfers. 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 |
| timediffmillis | number of milliseconds to add to the time on the remote machine
to get the time on the local machine. 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. |
| 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 |
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 fully 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.
Remote filesets do not support selectors.
The easiest way to describe how to send files is with a couple of examples:
<ftp server="ftp.apache.org"
userid="anonymous"
password="[email protected]">
<fileset dir="htdocs/manual"/>
</ftp>
Logs in to ftp.apache.org as anonymous and
uploads all files in the htdocs/manual directory
to the default directory for that user.
<ftp server="ftp.apache.org"
remotedir="incoming"
userid="anonymous"
password="[email protected]"
depends="yes"
>
<fileset dir="htdocs/manual"/>
</ftp>
Logs in to ftp.apache.org as anonymous and
uploads all new or changed files in the htdocs/manual directory
to the incoming directory relative to the default directory
for anonymous.
<ftp server="ftp.apache.org"
port="2121"
remotedir="/pub/incoming"
userid="coder"
password="java1"
depends="yes"
binary="no"
>
<fileset dir="htdocs/manual">
<include name="**/*.html"/>
</fileset>
</ftp>
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.
<ftp server="ftp.nt.org"
remotedir="c:\uploads"
userid="coder"
password="java1"
separator="\"
verbose="yes"
>
<fileset dir="htdocs/manual">
<include name="**/*.html"/>
</fileset>
</ftp>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 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.
<ftp action="get"
server="ftp.apache.org"
userid="anonymous"
password="[email protected]">
<fileset dir="htdocs/manual">
<include name="**/*.html"/>
</fileset>
</ftp>
Logs in to ftp.apache.org as anonymous and
recursively downloads all .html files from default directory for that user
into the htdocs/manual directory on the local machine.
<ftp action="del"
server="ftp.apache.org"
userid="anonymous"
password="[email protected]">
<fileset>
<include name="**/*.tmp"/>
</fileset>
</ftp>
Logs in to ftp.apache.org as anonymous and
tries to delete all *.tmp files from the default directory for that user.
If you don't have permission to delete a file, a BuildException is thrown.
<ftp action="list"
server="ftp.apache.org"
userid="anonymous"
password="[email protected]"
listing="data/ftp.listing">
<fileset>
<include name="**"/>
</fileset>
</ftp>
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.
Note that with the mkdir action, the directory to create is specified using the remotedir attribute.
<ftp action="mkdir"
server="ftp.apache.org"
userid="anonymous"
password="[email protected]"
remotedir="some/remote/dir"/>
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.
<ftp action="rmdir"
server="ftp.apache.org"
userid="anonymous"
password="[email protected]"
remotedir="/somedir" >
<fileset>
<include name="dira"/>
<include name="dirb/**"/>
</fileset>
</ftp>
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/**".
Copyright © 2000-2004 The Apache Software Foundation. All rights Reserved.