SFTP

Description

The com.dovetail.ant.ssh.Sftp task is a new task similar to the Ant Scp task. It includes the following enhancements:

Implements the SSH SFTP protocol for transferring files and managing remote files.

Note: This task is used as an antlib with external libraries that are distributed with the Dovetail ant-ssh distribution.

See also the ssh exec task, the ssh session task, and the ssh scp task

Parameters

Attribute Description Required
action The sftp subcommand. This can be: put, get, chmod, mkdir, rm, rmdir, rename, cd, pwd, lcd, lpwd, list. No, defaults to "put".
file The file to copy. This can be a local path or a remote path. Yes for get/put, unless a nested <fileset> element is used.
dir The directory to copy. This can be a local path or a remote path. Yes for get/put, unless a nested <fileset> element is used.
todir The directory to copy to. This can be a local path or a remote path. No, but either tofile or todir is required for get and put
tofile The file to copy to. This can be a local path or a remote path. No, but either tofile or todir is required for get and put
host The hostname or ip address to connect to on the remote host. No, defaults to 22. Ignored when task is nested in SSH Session task.
port The port to connect to on the remote host. No, defaults to 22. Ignored when task is nested in SSH Session task.
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. Ignored when task is nested in SSH Session task.
knownhosts This sets the list of known hosts file(s) to use to validate the identity of the remote host. This must be a SSH2 format file. SSH1 format is not supported. The special file name "putty" may be used to refer to PuTTY host keys stored in the Windows registry. The first known hosts file in this list will be updated with a new host key if trust=yes. A mismatched host key will never be replaced with a new key. No, defaults to "putty,${user.home}/.ssh/known_hosts" on Windows if PuTTY is installed or "${user.home}/.ssh/known_hosts" otherwise. On non-Windows systems, the default is "${user.home}/.ssh/known_hosts,/etc/ssh_known_hosts". Ignored when task is nested in SSH Session task.
failonerror Whether to halt the build if the transfer fails. No; defaults to true.
ignoreError Whether to quietly ignore errors if this task fails. No; defaults to false.
password The password. No. Ignored when task is nested in SSH Session task.
useAgent Determines whether an ssh-agent or PuTTY agent (Windows) will be used for user key creditials. No, defaults to true if an SSH key agent is available. Ignored when task is nested in SSH Session task. Requires jsch agentyproxy and jna library jars
allowPasswordPrompt If password is not set, set this to No to prevent a password prompt. No, defaults to true if a password or keyfile or agent key is not supplied. Ignored when task is nested in SSH Session task.
keyfile Location of the file holding the private key. Yes, if you are using key based Ignored when task is nested in SSH Session task. authentication.
passphrase Passphrase for your private key. No, defaults to an empty string. Ignored when task is nested in SSH Session task.
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.
sshVerbose Determines whether verbose messages from the JSch ssh library are output. No; defaults to false.
preserveLastModified Determines whether the last modification timestamp of downloaded files is preserved. It only works when transferring from a remote to a local system and probably doesn't work with a server that doesn't support SSH2. since Ant 1.8.0 No; defaults to false.
filemode A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to uploaded files. since Ant 1.9.5. No. If not specified, defaults to local file permissions if not running on Windows. If unable to "chmod" remote permissions after "put", a verbose message is logged.
dirmode A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to uploaded dirs. Note the actual permissions of the remote dir will be governed by this setting and the UMASK on the remote server. Default is 755. since Ant 1.9.5. No
serverAliveIntervalSeconds Sets a timeout interval in seconds after which if no data has been received from the server, the task will send a message through the encrypted channel to request a response from the server. since Ant 1.9.7 No, the default is 0, indicating that these messages will not be sent to the server. Ignored when task is nested in SSH Session task.
serverAliveCountMax The number of server alive messages which may be sent without receiving any messages back from the server. Only used if serverAliveIntervalSeconds is not 0. since Ant 1.9.7 No, defaults to 3. Ignored when task is nested in SSH Session task.
compressed Whether to enable compression during transfer. since Ant 1.9.8 No, defaults to false. Ignored when task is nested in SSH Session task.

Parameters specified as nested elements

fileset or resource collections

FileSets or Resource Collections are used to select groups of files to copy. To use a fileset or a resource collection, the todir attribute must be set.

Examples

This task is packaged in an Antlib. To run, you must point to the Dovetail ant-ssh library jars:

   ant -lib /path/to/ant-ssh/lib

Various SFTP commands on a single SSH session.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<project name="ant-ssh test" default="ssh.example"  
  xmlns:ssh="antlib:com.dovetail.ant.ssh">
  <!-- To run this script, you must have ant-ssh lib/*.jars in your Ant classpath.
       See the ant-ssh README for more information.
  -->
  
    <target name="init" >
      <property name="server" value="localhost"/>
      <property name="serverdir" value="/tmp/anttest"/>
      <property name="userid" value="kirk"/>
      <property name="localdir" value="${java.io.tmpdir}" />
      <tempfile property="dummypath" destdir="${localdir}" deleteonexit="yes" createfile="yes" 
        prefix="anttest." suffix=".txt" />
      <basename property="dummyfile" file="${dummypath}"/>
      <echoproperties destfile="${dummypath}" />  
  </target>
        
  <target name="ssh.example" depends="init" >
    <ssh:session username="${userid}" host="${server}" trust="yes">
      <ssh:sftp action="pwd" />
      <ssh:sftp action="list" file="/etc/fstab" />  <
      <ssh:sftp action="mkdir" dir="${serverdir}" ignoreError="yes" />
      <ssh:sftp action="put" todir="${serverdir}">  
        <fileset dir="${localdir}" casesensitive="yes" >
            <include name="anttest.*"/>
          </fileset>
      </ssh:sftp>
      <ssh:sftp action="chmod" file="${serverdir}/${dummyfile}" filemode="644" />
      <ssh:sftp action="get" dir="/etc/*crontab*" todir="${localdir}" />
      <ssh:sftp action="cd" dir="${serverdir}" />
      <ssh:sftp action="list" file="*.txt" />
      <ssh:sftp action="rm" file="notthere" failOnError="no" />
      <ssh:sftp action="rename" file="${dummyfile}" tofile="${dummyfile}.bak" />        
      <ssh:sftp action="rm"    file="${dummyfile}.bak" />        
      <ssh:sftp action="rmdir" dir="foonotthere" failOnError="no" />
      <ssh:sftp action="mkdir" dir="foo" failOnError="no" />
      <ssh:sftp action="symlink" file="foosym" todir="foo" />
      <ssh:sftp action="rm" file="foosym" />
      <ssh:sftp action="rmdir" dir="foo" />
      <ssh:sftp action="list" /> 
      <ssh:exec command="uname -a" />
    </ssh:session> 
  </target>

</project>

Example connecting to an IBM z/OS system running Co:Z SFTP.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<project name="ant-ssh test1" default="upload_zos" 
    xmlns:ssh="antlib:com.dovetail.ant.ssh">
  
    <target name="init" >
      <property name="server" value="zos.dovetail.com"/>
      <property name="serverDir" value="/tmp/src"/>
      <property name="sampJclPds" value="KIRK.COZ.SAMPJCL" />
      <property name="userid" value="kirk"/>
  </target>
        
  <target name="upload_zos" depends="init" >
    <echo message="Uploading source to ${server}:${serverDir}" />
    <ssh:session username="${userid}" host="${server}">
      <ssh:sftp action="mkdir" dir="${serverDir}" ignoreError="yes" />
      <ssh:sftp action="list" file="/+mode=text" />
      <ssh:sftp action="put" todir="${serverDir}" >
        <fileset dir="src" casesensitive="yes" >
          <include name="**"/>
          <modified/>
        </fileset>
      </ssh:sftp>
      <ssh:sftp action="list" file="/+mode=binary" />
      <ssh:sftp action="put" todir="${serverDir}" >
        <fileset dir="bin" casesensitive="yes" >
          <include name="**"/>
          <modified/>
        </fileset>
      </ssh:sftp>
      <ssh:sftp action="list" file="/+mode=text" />
      <!-- Jsch SFTP requires that z/OS datasets use the prefix "/-/" -->
      <ssh:sftp action="cd" todir="/-/${sampJclPds}"/>
      <ssh:sftp action="put" todir=".">
        <fileset dir="jcl" >
          <include name="*" />
          <modified/>
        </fileset>
      </ssh:sftp>
      <ssh:exec command="cd ${serverDir}; make" />
    </ssh:session>
  </target>
  
</project>