You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

scp.html 9.4 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252
  1. <html>
  2. <head>
  3. <meta http-equiv="Content-Language" content="en-us">
  4. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  5. <title>SCP Task</title>
  6. </head>
  7. <body>
  8. <h2><a name="scp">SCP</a></h2>
  9. <h3>Description</h3>
  10. <p><em>since Ant 1.6</em></p>
  11. <p>Copies a file or FileSet to or from a (remote) machine running an SSH daemon.
  12. FileSet <i>only</i> works for copying files from the local machine to a
  13. remote machine.</p>
  14. <p><b>Note:</b> This task depends on external libraries not included
  15. in the Ant distribution. See <a
  16. href="../install.html#librarydependencies">Library Dependencies</a>
  17. for more information. This task has been tested with jsch-0.1.2 and later.</p>
  18. <p>See also the <a href="scp.html">scp task</a></p>
  19. <h3>Parameters</h3>
  20. <table border="1" cellpadding="2" cellspacing="0">
  21. <tr>
  22. <td valign="top"><b>Attribute</b></td>
  23. <td valign="top"><b>Description</b></td>
  24. <td align="center" valign="top"><b>Required</b></td>
  25. </tr>
  26. <tr>
  27. <td valign="top">file</td>
  28. <td valign="top">The file to copy. This can be a local path or a
  29. remote path of the form <i>user[:password]@host:/directory/path</i>.
  30. <i>:password</i> can be omitted if you use key based
  31. authentication or specify the password attribute. The way remote
  32. path is recognized is whether it contains @ character or not. This
  33. will not work if your localPath contains @ character.</td>
  34. <td valign="top" align="center">Yes, unless a nested
  35. <code>&lt;fileset&gt;</code> element is used.</td>
  36. </tr>
  37. <tr>
  38. <td valign="top">localFile</td>
  39. <td valign="top">This is an alternative to the file attribute. But
  40. this must always point to a local file. The reason this was added
  41. was that when you give file attribute it is treated as remote if
  42. it contains @ character. This character can exist also in local
  43. paths. <em>since Ant 1.6.2</em></td>
  44. <td valign="top" align="center">Alternative to file attribute.</td>
  45. </tr>
  46. <tr>
  47. <td valign="top">remoteFile</td>
  48. <td valign="top">This is an alternative to the file attribute. But
  49. this must always point to a remote file. <em>since Ant 1.6.2</em></td>
  50. <td valign="top" align="center">Alternative to file attribute.</td>
  51. </tr>
  52. <tr>
  53. <td valign="top">todir</td>
  54. <td valign="top">The directory to copy to. This can be a local path
  55. or a remote path of the form <i>user[:password]@host:/directory/path</i>.
  56. <i>:password</i> can be omitted if you use key based
  57. authentication or specify the password attribute. The way remote
  58. path is recognized is whether it contains @ character or not. This
  59. will not work if your localPath contains @ character.</td>
  60. <td valian="top" align="center">Yes</td>
  61. </tr>
  62. <tr>
  63. <td valign="top">localTodir</td>
  64. <td valign="top">This is an alternative to the todir
  65. attribute. But this must always point to a local directory. The
  66. reason this was added was that when you give todir attribute it is
  67. treated as remote if it contains @ character. This character can
  68. exist also in local paths. <em>since Ant 1.6.2</em></td>
  69. <td valian="top" align="center">Alternative to todir attribute.</td>
  70. </tr>
  71. <tr>
  72. <td valign="top">localTofile</td>
  73. <td valign="top">Changes the file name to the given name while
  74. receiving it, only useful if receiving a single file. <em>since
  75. Ant 1.6.2</em></td>
  76. <td valian="top" align="center">Alternative to todir attribute.</td>
  77. </tr>
  78. <tr>
  79. <td valign="top">remoteTodir</td>
  80. <td valign="top">This is an alternative to the todir
  81. attribute. But this must always point to a remote directory.
  82. <em>since Ant 1.6.2</em></td>
  83. <td valian="top" align="center">Alternative to todir attribute.</td>
  84. </tr>
  85. <tr>
  86. <td valign="top">remoteTofile</td>
  87. <td valign="top">Changes the file name to the given name while
  88. sending it, only useful if sending a single file. <em>since
  89. Ant 1.6.2</em></td>
  90. <td valian="top" align="center">Alternative to todir attribute.</td>
  91. </tr>
  92. <tr>
  93. <td valign="top">port</td>
  94. <td valign="top">The port to connect to on the remote host.</td>
  95. <td valian="top" align="center">No, defaults to 22.</td>
  96. </tr>
  97. <tr>
  98. <td valign="top">trust</td>
  99. <td valign="top">This trusts all unknown hosts if set to yes/true.<br>
  100. <strong>Note</strong> If you set this to false (the default), the
  101. host you connect to must be listed in your knownhosts file, this
  102. also implies that the file exists.</td>
  103. <td valian="top" align="center">No, defaults to No.</td>
  104. </tr>
  105. <tr>
  106. <td valign="top">knownhosts</td>
  107. <td valign="top">This sets the known hosts file to use to validate
  108. the identity of the remote host. This must be a SSH2 format file.
  109. SSH1 format is not supported.</td>
  110. <td valian="top" align="center">No, defaults to
  111. ${user.home}/.ssh/known_hosts.</td>
  112. </tr>
  113. <tr>
  114. <td valign="top">failonerror</td>
  115. <td valign="top">Whether to halt the build if the transfer fails.
  116. </td>
  117. <td valign="top" align="center">No; defaults to true.</td>
  118. </tr>
  119. <tr>
  120. <td valign="top">password</td>
  121. <td valign="top">The password.</td>
  122. <td valign="top" align="center">Not if you are using key based
  123. authentication or the password has been given in the file or
  124. todir attribute.</td>
  125. </tr>
  126. <tr>
  127. <td valign="top">keyfile</td>
  128. <td valign="top">Location of the file holding the private key.</td>
  129. <td valign="top" align="center">Yes, if you are using key based
  130. authentication.</td>
  131. </tr>
  132. <tr>
  133. <td valign="top">passphrase</td>
  134. <td valign="top">Passphrase for your private key.</td>
  135. <td valign="top" align="center">Yes, if you are using key based
  136. authentication.</td>
  137. </tr>
  138. <tr>
  139. <td valign="top">verbose</td>
  140. <td valign="top">Determines whether SCP outputs verbosely to the
  141. user. Currently this means outputting dots/stars showing the
  142. progress of a file transfer. <em>since Ant 1.6.2</em></td>
  143. <td valign="top" align="center">No; defaults to false.</td>
  144. </tr>
  145. <tr>
  146. <td valign="top">sftp</td>
  147. <td valign="top">Determines whether SCP uses the sftp protocol.
  148. The sftp protocol is the file transfer protocol of SSH2. It is
  149. recommended that this be set to true if you are copying to/from a
  150. server that doesn't support scp1. <em>since Ant 1.7</em></td>
  151. <td valign="top" align="center">No; defaults to false.</td>
  152. </tr>
  153. </table>
  154. <h3>Parameters specified as nested elements</h3>
  155. <h4>fileset</h4>
  156. <p><a href="../CoreTypes/fileset.html">FileSet</a>s are used to select
  157. sets of files to copy.
  158. To use a fileset, the <code>todir</code> attribute must be set.</p>
  159. <h3>Examples</h3>
  160. <p><b>Copy a single local file to a remote machine</b></p>
  161. <pre>
  162. &lt;scp file=&quot;myfile.txt&quot; todir=&quot;user:password@somehost:/home/chuck&quot;/&gt;
  163. </pre>
  164. <p><b>Copy a single local file to a remote machine with separate
  165. password attribute</b></p>
  166. <pre>
  167. &lt;scp file=&quot;myfile.txt&quot; todir=&quot;user@somehost:/home/chuck&quot; password=&quot;password&quot;/&gt;
  168. </pre>
  169. <p><b>Copy a single local file to a remote machine using key base
  170. authentication.</b></p>
  171. <pre>
  172. &lt;scp file=&quot;myfile.txt&quot;
  173. todir=&quot;user@somehost:/home/chuck&quot;
  174. keyfile=&quot;${user.home}/.ssh/id_dsa&quot;
  175. passphrase=&quot;my extremely secret passphrase&quot;
  176. /&gt;
  177. </pre>
  178. <p><b>Copy a single remote file to a local directory</b></p>
  179. <pre>
  180. &lt;scp file=&quot;user:password@somehost:/home/chuck/myfile.txt&quot; todir=&quot;../some/other/dir&quot;/&gt;
  181. </pre>
  182. <p><b>Copy a remote directory to a local directory</b></p>
  183. <pre>
  184. &lt;scp file=&quot;user:password@somehost:/home/chuck/*&quot; todir=&quot;/home/sara&quot;/&gt;
  185. </pre>
  186. <p><b>Copy a local directory to a remote directory</b></p>
  187. <pre>
  188. &lt;scp todir=&quot;user:password@somehost:/home/chuck/&quot;&gt;
  189. &lt;fileset dir=&quot;src_dir&quot;/&gt;
  190. &lt;/scp&gt;
  191. </pre>
  192. <p><b>Copy a set of files to a directory</b></p>
  193. <pre>
  194. &lt;scp todir=&quot;user:password@somehost:/home/chuck&quot;&gt;
  195. &lt;fileset dir=&quot;src_dir&quot;&gt;
  196. &lt;include name=&quot;**/*.java&quot;/&gt;
  197. &lt;/fileset&gt;
  198. &lt;/scp&gt;
  199. &lt;scp todir=&quot;user:password@somehost:/home/chuck&quot;&gt;
  200. &lt;fileset dir=&quot;src_dir&quot; excludes=&quot;**/*.java&quot;/&gt;
  201. &lt;/scp&gt;
  202. </pre>
  203. <p><strong>Security Note:</strong> Hard coding passwords and/or usernames
  204. in scp task can be a serious security hole. Consider using variable
  205. substitution and include the password on the command line. For example:
  206. <p>
  207. <pre>
  208. &lt;scp todir=&quot;${username}:${password}@host:/dir&quot; ...&gt;
  209. </pre>
  210. Invoking ant with the following command line:
  211. <pre>
  212. ant -Dusername=me -Dpassword=mypassword target1 target2
  213. </pre>
  214. Is slightly better, but the username/password is exposed to all users on an Unix
  215. system (via the ps command). The best approach is to use the
  216. <code>&lt;input&gt;</code> task and/or retrieve the password from a (secured)
  217. .properties file.
  218. <p>
  219. <p><strong>Unix Note:</strong> File permissions are not retained when files
  220. are copied; they end up with the default <code>UMASK</code> permissions
  221. instead. This is caused by the lack of any means to query or set file
  222. permissions in the current Java runtimes. If you need a permission-
  223. preserving copy function, use <code>&lt;exec executable="scp" ... &gt;</code>
  224. instead.
  225. </p>
  226. <hr><p align="center">Copyright &copy; 2003-2006 The Apache Software Foundation.
  227. All rights Reserved.</p>
  228. </body>
  229. </html>