| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>FTP Task</title> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css"> |
| </head> |
| |
| <body> |
| |
| <h2><a name="ftp">FTP</a></h2> |
| <h3>Description</h3> |
| <p>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.</p> |
| <p><b>Note:</b> This task depends on external libraries not included in the Ant distribution. |
| See <a href="../install.html#librarydependencies">Library Dependencies</a> for more information.</p> |
| <p>The ftp task makes no attempt to determine what file system syntax is |
| required by the remote server, and defaults to Unix standards. |
| <i>remotedir</i> must be specified in the exact syntax required by the ftp |
| server. If the usual Unix conventions are not supported by the server, |
| <i>separator</i> can be used to set the file separator that should be used |
| instead.</p> |
| <p>See the section on <a href="../dirtasks.html#directorybasedtasks">directory based |
| tasks</a>, on how the inclusion/exclusion of files works, and how to |
| write patterns.</p> |
| <p> |
| This task does not currently use the proxy information set by the |
| <a href="setproxy.html"><setproxy></a> task, and cannot go through |
| a firewall via socks. |
| <p> |
| <b>Warning: </b> 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 langage 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). |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">server</td> |
| <td valign="top">the address of the remote ftp server.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">port</td> |
| <td valign="top">the port number of the remote ftp server. |
| Defaults to port 21.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">userid</td> |
| <td valign="top">the login id to use on the ftp server.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">password</td> |
| <td valign="top">the login password to use on the ftp server.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">remotedir</td> |
| <td valign="top">remote directory on the |
| ftp server |
| see table below for detailed usage |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">action</td> |
| <td valign="top">the ftp action to perform, defaulting to "send". |
| Currently supports "put", "get", |
| "del", "list", "chmod", |
| "mkdir" and "rmdir".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">binary</td> |
| <td valign="top">selects binary-mode ("yes") or text-mode |
| ("no") transfers. |
| Defaults to "yes"</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">passive</td> |
| <td valign="top">selects passive-mode ("yes") transfers. |
| Defaults to "no"</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">displays information on each file transferred if set |
| to "yes". Defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">depends</td> |
| <td valign="top">transfers only new or changed files if set to |
| "yes". Defaults to "no".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">newer</td> |
| <td valign="top">a synonym for <i>depends</i>. |
| see timediffauto and timediffmillis</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">timediffauto</td> |
| <td valign="top">set to <code>"true"</code> |
| to make ant calculate the time difference between client and server.<br/> |
| <em>requires write access in the remote directory</em><br/> |
| Since ant 1.6</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">timediffmillis</td> |
| <td valign="top">number of milliseconds to add to the time on the remote machine |
| to get the time on the local machine.<br/> |
| Since ant 1.6 |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">separator</td> |
| <td valign="top">sets the file separator used on the ftp server. |
| Defaults to "/".</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">umask</td> |
| <td valign="top">sets the default file permissions for new files, |
| unix only.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">chmod</td> |
| <td valign="top">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.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">listing</td> |
| <td valign="top">the file to write results of the "list" action. |
| Required for the "list" action, ignored otherwise.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">ignoreNoncriticalErrors</td> |
| <td valign="top">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</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">skipFailedTransfers</td> |
| <td valign="top">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</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">preservelastmodified</td> |
| <td valign="top">Give the copied files the same last modified |
| time as the original source files (applies to getting files only). |
| (<em>Note</em>: Ignored on Java 1.1)</td> |
| <td valign="top" align="center">No; defaults to false.</td> |
| </tr> |
| </table> |
| <h3>Note about remotedir attribute</h3> |
| <table border="1" cellpadding="2" cellspacing="0" |
| > |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;" width="20%">Action<br> |
| </td> |
| <td style="vertical-align: top;" width="40%">meaning of <code>remotedir</code><br> |
| </td> |
| <td style="vertical-align: top;">use of nested <code>fileset</code> |
| (s)<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">send/put<br> |
| </td> |
| <td style="vertical-align: top;" width="40%">base directory to |
| which the files are sent<br> |
| </td> |
| <td style="vertical-align: top;">they are used normally and |
| evaluated on the local machine<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">recv/get<br> |
| </td> |
| <td style="vertical-align: top;" width="40%">base directory from |
| which the files are retrieved<br> |
| </td> |
| <td style="vertical-align: top;">the remote files located under |
| the <code>remotedir </code>matching the include/exclude patterns of |
| the <code>fileset </code></td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">del/delete<br> |
| </td> |
| <td style="vertical-align: top;" width="40%">base directory from |
| which files get deleted<br> |
| </td> |
| <td style="vertical-align: top;">the remote files located under |
| the <code>remotedir </code>matching the include/exclude patterns of |
| the <code>fileset <br> |
| </code></td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">list<br> |
| </td> |
| <td style="vertical-align: top;" width="40%">base directory from |
| which files are listed<br> |
| </td> |
| <td style="vertical-align: top;">the remote files located under |
| the <code>remotedir </code>matching the include/exclude patterns of |
| the <code>fileset <br> |
| </code></td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">mkdir</td> |
| <td style="vertical-align: top;" width="40%">directory to create<br> |
| </td> |
| <td style="vertical-align: top;">not used<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">chmod</td> |
| <td style="vertical-align: top;" width="40%">base directory from |
| which the mode of files get changed<br> |
| </td> |
| <td style="vertical-align: top;">the remote files located under |
| the <code>remotedir </code>matching the include/exclude patterns of |
| the <code>fileset <br> |
| </code></td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;" width="20%">rmdir<br> |
| </td> |
| <td style="vertical-align: top;" width="40%">base directory from |
| which directories get removed<br> |
| </td> |
| <td style="vertical-align: top;">the remote directories located |
| under the <code>remotedir </code>matching the include/exclude |
| patterns of the <code>fileset <br> |
| </code></td> |
| </tr> |
| </tbody> |
| </table><h3>Parameters specified as nested elements</h3> |
| <h4>fileset</h4> |
| <p>The ftp task supports any number of nested <a |
| href="../CoreTypes/fileset.html"><code><fileset></code></a> elements to specify |
| the files to be retrieved, or deleted, or listed, or whose mode you want to change.</p> |
| <p> |
| The attribute <code>followsymlinks</code> of <code>fileset</code> is fully supported on |
| local (put) as well as remote (get, chmod, delete) filesets. |
| <em>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 <code>followsymlinks</code> to <code>false</code>.</em> |
| </p> |
| <p> |
| Remote filesets do not support selectors.<br/> |
| </p> |
| |
| <h3>Sending Files</h3> |
| <p>The easiest way to describe how to send files is with a couple of examples:</p> |
| <pre> |
| <ftp server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com"> |
| <fileset dir="htdocs/manual"/> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| uploads all files in the <code>htdocs/manual</code> directory |
| to the default directory for that user.</p> |
| <pre> <ftp server="ftp.apache.org" |
| remotedir="incoming" |
| userid="anonymous" |
| password="me@myorg.com" |
| depends="yes" |
| > |
| <fileset dir="htdocs/manual"/> |
| </ftp></pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| uploads all new or changed files in the <code>htdocs/manual</code> directory |
| to the <code>incoming</code> directory relative to the default directory |
| for <code>anonymous</code>.</p> |
| <pre> <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></pre> |
| <p>Logs in to <code>ftp.apache.org</code> at port <code>2121</code> as |
| <code>coder</code> with password <code>java1</code> and uploads all new or |
| changed HTML files in the <code>htdocs/manual</code> directory to the |
| <code>/pub/incoming</code> directory. The files are transferred in text mode. Passive mode has been switched on to send files from behind a firewall.</p> |
| <pre> <ftp server="ftp.nt.org" |
| remotedir="c:\uploads" |
| userid="coder" |
| password="java1" |
| separator="\" |
| verbose="yes"</pre> |
| <PRE> |
| > |
| <fileset dir="htdocs/manual"> |
| <include name="**/*.html"/> |
| </fileset> |
| </ftp></PRE><p>Logs in to the Windows-based <code>ftp.nt.org</code> as |
| <code>coder</code> with password <code>java1</code> and uploads all |
| HTML files in the <code>htdocs/manual</code> directory to the |
| <code>c:\uploads</code> directory. Progress messages are displayed as each |
| file is uploaded.</p> |
| <h3>Getting Files</h3> |
| <p>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.</p> |
| <pre> |
| <ftp action="get" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com"> |
| <fileset dir="htdocs/manual"> |
| <include name="**/*.html"/> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| recursively downloads all .html files from default directory for that user |
| into the <code>htdocs/manual</code> directory on the local machine.</p> |
| . |
| <h3>Deleting Files</h3> |
| 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. |
| |
| <pre> |
| <ftp action="del" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com"> |
| <fileset> |
| <include name="**/*.tmp"/> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> 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.</p> |
| <h3>Listing Files</h3> |
| <pre> |
| <ftp action="list" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com" |
| listing="data/ftp.listing"> |
| <fileset> |
| <include name="**"/> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>This provides a file listing in <code>data/ftp.listing</code> of all the files on |
| the FTP server relative to the default directory of the <code>anonymous</code> |
| user. The listing is in whatever format the FTP server normally lists files.</p> |
| |
| <h3>Creating Directories</h3> |
| <p>Note that with the mkdir action, the directory to create is specified using the |
| remotedir attribute.</p> |
| <pre> |
| <ftp action="mkdir" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com" |
| remotedir="some/remote/dir"/> |
| </pre> |
| <p>This creates the directory <code>some/remote/dir</code> 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.</p> |
| <h3>Removing Directories</h3> |
| 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. |
| |
| <pre> |
| <ftp action="rmdir" |
| server="ftp.apache.org" |
| userid="anonymous" |
| password="me@myorg.com" |
| remotedir="/somedir" > |
| <fileset> |
| <include name="dira"/> |
| <include name="dirb/**"/> |
| </fileset> |
| </ftp> |
| </pre> |
| <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and |
| tries to remove <code>/somedir/dira</code> directory and |
| all the directories tree starting at, and including, <code>/somedir/dirb</code>. |
| When removing the <code>/somedir/dirb</code> 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. |
| Obviuosly all the files in the tree must have been already deleted. |
| </p> |
| <p>As an example suppose you want to delete everything contained into |
| <code>/somedir</code>, so invoke first the <code><ftp></code> task with |
| <code>action="delete"</code>, then with |
| <code>action="rmdir"</code> specifying in both cases |
| <code>remotedir="/somedir"</code> and |
| |
| <pre> |
| <fileset> |
| <include name="**"/> |
| </fileset> |
| </pre> |
| |
| The directory specified in the <code>remotedir</code> parameter is never |
| selected for remove, so if you need to remove it, specify its parent in |
| <code>remotedir</code> parameter and include it in the |
| <code><fileset></code> pattern, like <code>"somedir/**"</code>. |
| </p> |
| <hr> |
| <p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |
