FTP Task

## 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

Attribute | Description | Required
--- | --- | ---
server | the address of the remote FTP server. | Yes
port | the port number of the remote FTP server. | No; defaults to 21
userid | the login id to use on the FTP server. | Yes
password | the login password to use on the FTP server. | Yes
account | the account to use on the FTP server. since Ant 1.7. | No
remotedir | remote directory on the FTP server see table below for detailed usage | No
action | FTP action to perform. Currently supports put, get, del, list, chmod, mkdir, rmdir, and site. | No; defaults to send
binary | selects binary-mode (yes) or text-mode (no) transfers. | No; defaults to yes
passive | selects passive-mode (yes) transfers, for better through-firewall connectivity, at the price of performance. | No; defaults to no
verbose | displays information on each file transferred if set to yes. | No; defaults to no
depends | transfers only new or changed files if set to yes. | No; defaults to 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 or NONE (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 for put (default is MINUTE) and get (default is NONE; not as necessary 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. | No; defaults to /
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. | Yes, for the list action; ignored otherwise
ignoreNoncriticalErrors | flag which permits the task to ignore some non-fatal error codes sent by some servers during directory creation: wu-ftp in particular. | No; defaults to false
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. | No; default to false
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 positive number is 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 | No; default is true
The following attributes require jakarta-commons-net-1.4.0 or greater. Use these options when the standard options don't work, because the server is in a different timezone and you need timestamp dependency checking the default timestamp formatting doesn't match the server display and list parsing therefore fails 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). When specified as , default value will be used. Since Ant 1.7 | No; defaults to default date format for the system type indicated by systemTypeKey
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 systemTypeKey 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.

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/**`.