mirror of
https://github.com/apache/ant.git
synced 2025-05-18 14:04:48 +00:00
231e15c24e
jakarta-oro 2.0.1 or greater commons-net 1.2.0 or greater when using MS FTP servers git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@276099 13f79535-47bb-0310-9956-ffa450edef68
453 lines
18 KiB
HTML
453 lines
18 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<title>FTP Task</title>
|
|
</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#commons-net">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-2004 The Apache Software Foundation. All rights
|
|
Reserved.</p>
|
|
|
|
</body>
|
|
</html>
|
|
|