FTP

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 specifics 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.

Parameters

Note about remotedir attribute

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, list) 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.

Log in to ftp.apache.org as anonymous and upload all files in the htdocs/manual directory to the default directory for that user.

<ftp server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com">
    <fileset dir="htdocs/manual"/>
</ftp>

Log in to ftp.apache.org as anonymous and upload 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"
     remotedir="incoming"
     userid="anonymous"
     password="me@myorg.com"
     depends="yes">
    <fileset dir="htdocs/manual"/>
</ftp>

Log in to ftp.apache.org at port 2121 as coder with password java1 and upload 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.apache.org"
     port="2121"
     remotedir="/pub/incoming"
     userid="coder"
     password="java1"
     passive="yes"
     depends="yes"
     binary="no">
    <fileset dir="htdocs/manual">
        <include name="**/*.html"/>
    </fileset>
</ftp>

Log in to a Windows server at ftp.hypothetical.india.org at port 2121 as coder with password java1 and upload 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.

<ftp server="ftp.hypothetical.india.org"
     port="2121"
     remotedir="/pub/incoming"
     userid="coder"
     password="java1"
     depends="yes"
     binary="no"
     systemTypeKey="Windows"
     serverTimeZoneConfig="India/Calcutta">
    <fileset dir="htdocs/manual">
        <include name="**/*.html"/>
    </fileset>
</ftp>

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

<ftp server="ftp.nt.org"
     remotedir="c:\uploads"
     userid="coder"
     password="java1"
     separator="\"
     verbose="yes">
    <fileset dir="htdocs/manual">
        <include name="**/*.html"/>
    </fileset>
</ftp>

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.

Log in to ftp.apache.org as anonymous and recursively download all .html files from default directory for that user into the htdocs/manual directory on the local machine.

<ftp action="get"
     server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com">
    <fileset dir="htdocs/manual">
        <include name="**/*.html"/>
    </fileset>
</ftp>

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.

<ftp action="get"
     server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com"
     systemTypeKey="UNIX"
     defaultDateFormatConfig="yyyy-MM-dd HH:mm">
    <fileset dir="htdocs/manual">
        <include name="**/*.html"/>
    </fileset>
</ftp>

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

<ftp action="get"
     server="ftp.hypthetical.fr"
     userid="anonymous"
     password="me@myorg.com"
     defaultDateFormatConfig="d MMM yyyy"
     recentDateFormatConfig="d MMM HH:mm"
     serverLanguageCodeConfig="fr">
    <fileset dir="htdocs/manual">
        <include name="**/*.html"/>
    </fileset>
</ftp>

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.

Log in to ftp.apache.org as anonymous and try 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="del"
     server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com">
    <fileset>
        <include name="**/*.tmp"/>
    </fileset>
</ftp>

Listing Files

Get 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.

<ftp action="list"
     server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com"
     listing="data/ftp.listing">
    <fileset>
        <include name="**"/>
    </fileset>
</ftp>

Creating directories

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

Create 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="mkdir"
     server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com"
     remotedir="some/remote/dir"/>

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.

Log in to ftp.apache.org as anonymous and try to remove /somedir/dira directory and all the directory tree starting at, and including, /somedir/dirb. When removing the /somedir/dirb tree, the task starts 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.

<ftp action="rmdir"
     server="ftp.apache.org"
     userid="anonymous"
     password="me@myorg.com"
     remotedir="/somedir" >
    <fileset>
        <include name="dira"/>
        <include name="dirb/**"/>
    </fileset>
</ftp>

As an example suppose you want to delete everything contained in /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/**.