SCP Task

## SCP

### Description

since Ant 1.6

Copies a file or FileSet to or from a remote machine running SSH daemon. FileSet only works for copying files from the local machine to a remote machine.

Note: This task depends on external libraries not included in the Ant distribution. See Library Dependencies for more information. This task has been tested with jsch-0.1.2 to jsch-0.1.14.

### Parameters

Attribute | Description | Required
file | The file to copy. This can be a local path or a remote path of the form user[:password]@host:/directory/path. :password can be ommitted if you use key based authentication or specify the password attribute. The way remote path is recognized is whether it contains @ character or not. This will not work if your localPath contains @ character. | Yes, unless a nested `<fileset>` element is used.
localFile | This is an alternative to the file attribute. But this must always point to a local file. The reason this was added was that when you give file attribute it is treated as remote if it contains @ character. This character can exist also in local paths. since Ant 1.6.2 | Alternative to file attribute.
remoteFile | This is an alternative to the file attribute. But this must always point to a remote file. since Ant 1.6.2 | Alternative to file attribute.
todir | The directory to copy to. This can be a local path or a remote path of the form user[:password]@host:/directory/path. :password can be ommitted if you use key based authentication or specify the password attribute. The way remote path is recognized is whether it contains @ character or not. This will not work if your localPath contains @ character. | Yes
localTodir | This is an alternative to the todir attribute. But this must always point to a local directory. The reason this was added was that when you give todir attribute it is treated as remote if it contains @ character. This character can exist also in local paths. since Ant 1.6.2 | Alternative to todir attribute.
localTofile | Changes the file name to the given name while receiving it, only useful if receiving a single file. since Ant 1.6.2 | Alternative to todir attribute.
remoteTodir | This is an alternative to the todir attribute. But this must always point to a remote directory. since Ant 1.6.2 | Alternative to todir attribute.
remoteTofile | Changes the file name to the given name while sending it, only useful if sending a single file. since Ant 1.6.2 | Alternative to todir attribute.
port | The port to connect to on the remote host. | No, defaults to 22.
trust | This trusts all unknown hosts if set to yes/true. Note If you set this to false (the default), the host you connect to must be listed in your knownhosts file, this also implies that the file exists. | No, defaults to No.
knownhosts | This sets the known hosts file to use to validate the identity of the remote host. This must be a SSH2 format file. SSH1 format is not supported. | No, defaults to ${user.home}/.ssh/known_hosts.
failonerror | Whether to halt the build if the transfer fails. | No; defaults to true.
password | The password. | Not if you are using key based authentication or the password has been given in the file or todir attribute.
keyfile | Location of the file holding the private key. | Yes, if you are using key based authentication.
passphrase | Passphrase for your private key. | Yes, if you are using key based authentication.
verbose | Determines whether SCP outputs verbosely to the user. Currently this means outputting dots/stars showing the progress of a file transfer. since Ant 1.6.2 | No; defaults to false.

### Parameters specified as nested elements

#### fileset

FileSets are used to select sets of files to copy. To use a fileset, the `todir` attribute must be set.

### Examples

Copy a single local file to a remote machine

      <scp file="myfile.txt" todir="user:password@somehost:/home/chuck"/>

Copy a single local file to a remote machine with separate password attribute

      <scp file="myfile.txt" todir="user@somehost:/home/chuck" password="password"/>

Copy a single local file to a remote machine using key base authentication.

      <scp file="myfile.txt"
           todir="user@somehost:/home/chuck"
           keyfile="${user.home}/.ssh/id_dsa"
           passphrase="my extremely secret passphrase"
      />

Copy a single remote file to a local directory

      <scp file="user:password@somehost:/home/chuck/myfile.txt" todir="../some/other/dir"/>

Copy a remote directory to a local directory

      <scp file="user:password@somehost:/home/chuck/*" todir="/home/sara" />

Copy a local directory to a remote directory

      <scp todir="user:password@somehost:/home/chuck/">
        <fileset dir="src_dir"/>
      </scp>

Copy a set of files to a directory

      <scp todir="user:password@somehost:/home/chuck">
        <fileset dir="src_dir">
          <include name="**/*.java"/>
        </fileset>
      </scp>

      <scp todir="user:password@somehost:/home/chuck">
        <fileset dir="src_dir" excludes="**/*.java"/>
      </scp>

Security Note: Hard coding passwords and/or usernames in scp task can be a serious security hole. Consider using variable substituion and include the password on the command line. For example:

        <scp todir="${username}:${password}@host:/dir" ...>

Invoke ant with the following command line:

        ant -Dusername=me -Dpassword=mypassword target1 target2

Unix Note: File permissions are not retained when files are copied; they end up with the default `UMASK` permissions instead. This is caused by the lack of any means to query or set file permissions in the current Java runtimes. If you need a permission- preserving copy function, use `<exec executable="scp" ... >` instead.

Copyright © 2003-2004 The Apache Software Foundation. All rights Reserved.