SSH Ant Task

Description

The SSH ant task provides file transfer and command execution. The <ssh> task itself establishes the connection and delegates operations to its nested elements, executing each operation synchronously. This task supports both SSH1 and SSH2 servers. The supported operations are SFTP and Exec.

The Maverick SSH ant task has been created with the J2SSH Maverick API and does not require any external dependencies; the distribution jar file maverick-ant.jar includes the task and an obfuscated version of the API. The API is compatible with JDK 1.1+ however this task has not been extensively tested with earlier version of the JDK. The task has been created using ANT 1.5.4 but may be compatible with earlier versions of ANT.

Parameters for <ssh>

Attribute

Values

Required

host

The hostname of the computer the task will connect to.

Yes

port

The connection port. Defaults to 22

No

username

The username of the user account for login

Yes

password

The password of the user account; either password or keyfile must be set to authenticate the connection. Its also possible to specify both when a server requires multiple authentication methods

Yes if keyfile not set

keyfile

The path to the private key file to use for public key authentication

Yes if password not set

passphrase

The passphrase of the private key specified in the keyfile attribute

No

newline

Sets the newline convention used when writing data to a session, possible values are "\n", "\r", "\r\n". Defaults to "\n"

No

cipher

Set the cipher to use; valid settings for SSH1 are "3DES" or "DES"; settings for SSH2 are "3DES" or "Blowfish". Defaults to "3DES" for SSH1, "Blowfish" for SSH2

No

mac

Set the message authentication code algorithm for SSH2; valid settings are "MD5" or "SHA1". Defaults to "MD5"

No

solarisbugworkaround

When connecting to some Solaris machines, after the first session is closed the connection is dropped. Setting this attribute to "true" forces a workaround by opening the first session as a dummy session keeping it open until the connection is not required. Defaults to "false"

No

sftpcmd

SSH1 does not support SFTP directly. To support SFTP over SSH1 set the path of the sftp executable on the target server. For example "/usr/sbin/sftp-server" could be set. NOTE: This attribute will only work on *nix SSH servers.

No

matcher

When executing commands with the <exec> task you can <read> input from the command output, this attribute sets the type of matcher that is used to determine when a read has completed. The default is to use a Regular Expression matcher but you can also set this to “simple” which will do a simple string comparison.

No

version

The SSH version required. Can be set to either 1 for SSH1 or 2 for SSH2. The Default behaviour is to attempt to connect using SSH2 and if not available fallback to SSH1.

No

term

The type of pseudo terminal to request

No

rows

The number of rows in the pseudo terminal

No

cols

The number of columns in the pseudo terminal

No

failOnUnkownOS

The task attempts to automatically configure the session based on the OS it detects. If this operation fails should the task continue or fail? Continuing may cause lockups as an incorrectly configured session may not be able to evaluate the shell input correctly. Defaults to true

No

eol

The EOL string to send when mimicking user input. Defaults to the EOL setting of the detected operating system

No

prompt

Set the value of the prompt which will be used to filter out output of commands.

No

promptCommand

When configuring the session the task will change the value of the shell prompt so that it can filter the output of one command against another. Use this attribute to set the exact prompt command to be executed. You should also set the prompt attribute with the value of the set prompt

No

promptTimeout

When the shell is initialized this setting defines how long the task will wait for the shell prompt before returning an error. Defaults to 10,000 milliseconds

No

shellInitPeriod

During the initialization the shell must have time to initialize before commands are sent; this setting has been added because sending a command too quickly may result in the command not being executed. The default of 5000 milliseconds has been found to be acceptable for most servers, reducing this may provide better performance at the risk of errors.

No

allocatePseudoTerminal

Force the allocation of a pseudo terminal. Default = true

No

exitCommand

The command sent to the interactive shell to exit the session

No

 

Examples

 Installing the task

<taskdef name="ssh"

      classname="com.sshtools.ant.Ssh"

      classpath="maverick-ant.jar"/>

Creating a connection using password authentication

<ssh host="foo.bar.com"

            username="lee"

            password="********">



  <!-- Exec and sftp elements are put here -->



</ssh>

Using public key authentication

<ssh host="foo.bar.com"

            username="lee"

            keyfile="/home/lee/id_rsa"

            passphrase="*****">



</ssh>


Forcing an SSH1 connection

<ssh host="foo.bar.com"

            username="lee"

            keyfile="/home/lee/id_rsa"

            passphrase="*****"

            version="1">



</ssh>


Using the <exec> and <sftp> elements

 

Previous versions of this task supported the <shell> element, this version has been changed so that all <exec> commands are performed through a shell, you can now <write> and <read> to send input to the command itself and not worry about catching the shell prompt as this is automatically handled by the API with the shell maintaining its state between exec commands.

 

<ssh host="foo.bar.com"

      username="lee"

          keyfile="/home/lee/id_rsa"

      passphrase="*****"

      version="2">

  

    <!-- Tar up a directory -->

    <exec cmd=”tar -zcf archive.tar.gz ant_rules_umask”/>

    <exec cmd="passwd">

            <read>password:</read>

            <write>oldpass</write>

            <read>password:</read>

            <write>newpass</write>

            <read>password:</read>

            <write>newpass</write>

     </exec>
 <sftp action="get">
           <filelist
              dir="."
              files="archive.tar.gz"/>
         </sftp>


</ssh>