2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2003-03-13 09:01:54 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2003-03-13 09:01:54 +00:00
|
|
|
<title>SSHEXEC Task</title>
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<h2><a name="sshexec">SSHEXEC</a></h2>
|
|
|
|
|
<h3>Description</h3>
|
2003-03-14 15:10:27 +00:00
|
|
|
|
2010-11-11 17:04:16 +00:00
|
|
|
<p><em>since Apache Ant 1.6</em></p>
|
2003-03-14 15:10:27 +00:00
|
|
|
|
2003-03-13 09:01:54 +00:00
|
|
|
<p>Runs a command on a remote machine running SSH daemon.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p><b>Note:</b> This task depends on external libraries not included
|
|
|
|
|
in the Ant distribution. See <a
|
|
|
|
|
href="../install.html#librarydependencies">Library Dependencies</a>
|
2006-09-13 00:05:04 +00:00
|
|
|
for more information. This task has been tested with jsch-0.1.29 and above
|
2005-08-10 23:02:50 +00:00
|
|
|
and won't work with versions of jsch earlier than
|
2006-09-13 00:05:04 +00:00
|
|
|
0.1.28.</p>
|
2003-03-13 09:01:54 +00:00
|
|
|
|
2005-08-10 23:02:50 +00:00
|
|
|
<p>See also the <a href="scp.html">scp task</a></p>
|
|
|
|
|
|
2003-03-13 09:01:54 +00:00
|
|
|
<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>
|
2004-03-18 11:25:34 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">host</td>
|
2004-11-12 10:36:29 +00:00
|
|
|
<td valign="top">The hostname or IP address of the remote host to which you wish to connect.</td>
|
2004-03-18 11:25:34 +00:00
|
|
|
<td valign="top" align="center">Yes</td>
|
|
|
|
|
</tr>
|
2003-03-13 09:01:54 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">username</td>
|
|
|
|
|
<td valign="top">The username on the remote host to which you are connecting.</td>
|
|
|
|
|
<td valign="top" align="center">Yes</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">command</td>
|
|
|
|
|
<td valign="top">The command to run on the remote host.</td>
|
2007-05-12 04:18:36 +00:00
|
|
|
<td valian="top" align="center">Either this or commandResource must be set</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">commandResource</td>
|
2007-10-11 13:19:03 +00:00
|
|
|
<td valign="top">The resource (file) that contains the commands to run on the remote host.
|
|
|
|
|
Since Ant 1.7.1</td>
|
2007-05-12 04:18:36 +00:00
|
|
|
<td valian="top" align="center">Either this or command must be set</td>
|
2003-03-13 09:01:54 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">port</td>
|
|
|
|
|
<td valign="top">The port to connect to on the remote host.</td>
|
|
|
|
|
<td valian="top" align="center">No, defaults to 22.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">trust</td>
|
2003-10-16 11:21:14 +00:00
|
|
|
|
|
|
|
|
<td valign="top">This trusts all unknown hosts if set to yes/true.<br>
|
|
|
|
|
<strong>Note</strong> 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.</td>
|
2003-03-13 09:01:54 +00:00
|
|
|
<td valian="top" align="center">No, defaults to No.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">knownhosts</td>
|
|
|
|
|
<td valign="top">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.</td>
|
|
|
|
|
<td valian="top" align="center">No, defaults to
|
|
|
|
|
${user.home}/.ssh/known_hosts.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">failonerror</td>
|
2003-10-28 10:29:53 +00:00
|
|
|
<td valign="top">Whether to halt the build if the command does not complete successfully.
|
2003-03-13 09:01:54 +00:00
|
|
|
</td>
|
|
|
|
|
<td valign="top" align="center">No; defaults to true.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">password</td>
|
|
|
|
|
<td valign="top">The password.</td>
|
|
|
|
|
<td valign="top" align="center">Not if you are using key based
|
|
|
|
|
authentication or the password has been given in the file or
|
|
|
|
|
todir attribute.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">keyfile</td>
|
|
|
|
|
<td valign="top">Location of the file holding the private key.</td>
|
|
|
|
|
<td valign="top" align="center">Yes, if you are using key based
|
|
|
|
|
authentication.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">passphrase</td>
|
|
|
|
|
<td valign="top">Passphrase for your private key.</td>
|
|
|
|
|
<td valign="top" align="center">No, defaults to an empty string.</td>
|
|
|
|
|
</tr>
|
2013-02-18 16:13:11 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">suppresssystemout</td>
|
|
|
|
|
<td valign="top">Whether to suppress system out.
|
|
|
|
|
<em>since Ant 1.9.0</em></td>
|
|
|
|
|
<td align="center" valign="top">No, defaults to false</td>
|
|
|
|
|
</tr>
|
2003-04-01 13:01:09 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">output</td>
|
|
|
|
|
<td valign="top">Name of a file to which to write the output.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">append</td>
|
|
|
|
|
<td valign="top">Whether output file should be appended to or overwritten. Defaults to false, meaning overwrite any existing file.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">outputproperty</td>
|
|
|
|
|
<td valign="top">The name of a property in which the output of the
|
2009-10-24 06:25:03 +00:00
|
|
|
command should be stored. If you use the commandResource
|
|
|
|
|
attribute, each command's output will be prefixed by the
|
|
|
|
|
command itself.</td>
|
2003-04-01 13:01:09 +00:00
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">timeout</td>
|
|
|
|
|
<td valign="top">Stop the command if it doesn't finish within the
|
2008-07-14 14:54:49 +00:00
|
|
|
specified time (given in milliseconds <b>unlike telnet, which
|
|
|
|
|
expects a timeout in seconds</b>).
|
|
|
|
|
Defaults to 0 which means "wait forever".</td>
|
2003-04-01 13:01:09 +00:00
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2008-07-15 13:14:26 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">input</td>
|
|
|
|
|
<td valign="top">A file from which the executed command's standard
|
|
|
|
|
input is taken. This attribute is mutually exclusive with the
|
2011-01-25 11:00:20 +00:00
|
|
|
inputstring and inputproperty attributes.<br/>
|
2009-10-24 06:25:03 +00:00
|
|
|
When executing more than one command via commandResource, input
|
2008-07-15 13:14:26 +00:00
|
|
|
will be read for each command.
|
|
|
|
|
<em>since Ant 1.8.0</em></td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2009-12-01 13:02:51 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">verbose</td>
|
|
|
|
|
<td valign="top">Determines whether sshexec outputs verbosely to the user.<br/>
|
|
|
|
|
Similar output is generated as the ssh commandline tool wit the -v option.
|
|
|
|
|
<em>since Ant 1.8.0</em></td>
|
|
|
|
|
<td align="center">No, defaults to false</td>
|
|
|
|
|
</tr>
|
2011-01-25 11:00:20 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">inputproperty</td>
|
|
|
|
|
<td valign="top">Name of a property who's content serves as the
|
|
|
|
|
input stream for the executed command. This attribute is
|
|
|
|
|
mutually exclusive with the input and inputstring
|
|
|
|
|
attributes.<br/>
|
|
|
|
|
When executing more than one command via commandResource, input
|
|
|
|
|
will be read for each command.
|
|
|
|
|
<em>since Ant 1.8.0</em></td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2008-07-15 13:14:26 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">inputstring</td>
|
|
|
|
|
<td valign="top">A string which serves as the input stream for the
|
|
|
|
|
executed command. This attribute is mutually exclusive with the
|
2011-01-25 11:00:20 +00:00
|
|
|
input and inputproperty attributes.<br/>
|
2009-10-24 06:25:03 +00:00
|
|
|
When executing more than one command via commandResource, input
|
2008-07-15 13:14:26 +00:00
|
|
|
will be read for each command.
|
2011-01-25 11:00:20 +00:00
|
|
|
<em>since Ant 1.8.3</em></td>
|
2008-07-15 13:14:26 +00:00
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2012-02-01 13:19:44 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">usepty</td>
|
|
|
|
|
<td valign="top">Whether to allocate a pseudo-tty (like ssh -t).
|
|
|
|
|
<em>since Ant 1.8.3</em></td>
|
|
|
|
|
<td align="center" valign="top">No, defaults to false</td>
|
|
|
|
|
</tr>
|
2003-03-13 09:01:54 +00:00
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h3>Examples</h3>
|
|
|
|
|
<p><b>Run a command on a remote machine using password authentication</b></p>
|
|
|
|
|
<pre>
|
|
|
|
|
<sshexec host="somehost"
|
|
|
|
|
username="dude"
|
|
|
|
|
password="yo"
|
|
|
|
|
command="touch somefile"/>
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<p><b>Run a command on a remote machine using key authentication</b></p>
|
|
|
|
|
<pre>
|
|
|
|
|
<sshexec host="somehost"
|
|
|
|
|
username="dude"
|
|
|
|
|
keyfile="${user.home}/.ssh/id_dsa"
|
|
|
|
|
passphrase="yo its a secret"
|
|
|
|
|
command="touch somefile"/>
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<p><b>Run a command on a remote machine using key authentication with no passphrase</b></p>
|
|
|
|
|
<pre>
|
|
|
|
|
<sshexec host="somehost"
|
|
|
|
|
username="dude"
|
|
|
|
|
keyfile="${user.home}/.ssh/id_dsa"
|
|
|
|
|
command="touch somefile"/>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2007-05-12 04:18:36 +00:00
|
|
|
<p><b>Run a set of commands from a command resource (file) on a remote machine using key authentication with no passphrase</b></p>
|
|
|
|
|
<pre>
|
|
|
|
|
<sshexec host="somehost"
|
|
|
|
|
username="dude"
|
|
|
|
|
keyfile="${user.home}/.ssh/id_dsa"
|
|
|
|
|
commandResource="to_run"/>
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
2003-03-13 09:01:54 +00:00
|
|
|
<p><strong>Security Note:</strong> Hard coding passwords and/or usernames
|
|
|
|
|
in sshexec task can be a serious security hole. Consider using variable
|
2004-11-12 10:36:29 +00:00
|
|
|
substitution and include the password on the command line. For example:<br>
|
2003-03-13 09:01:54 +00:00
|
|
|
<pre>
|
|
|
|
|
<sshexec host="somehost"
|
|
|
|
|
username="${username}"
|
|
|
|
|
password="${password}"
|
|
|
|
|
command="touch somefile"/>
|
|
|
|
|
</pre>
|
2008-07-16 09:57:21 +00:00
|
|
|
Invoking ant with the following command line:
|
2003-03-13 09:01:54 +00:00
|
|
|
<pre>
|
|
|
|
|
ant -Dusername=me -Dpassword=mypassword target1 target2
|
|
|
|
|
</pre>
|
2008-07-16 09:57:21 +00:00
|
|
|
|
|
|
|
|
Is slightly better, but the username/password is exposed to all users
|
|
|
|
|
on an Unix system (via the ps command). The best approach is to use
|
|
|
|
|
the
|
|
|
|
|
<code><input></code> task and/or retrieve the password from a (secured)
|
|
|
|
|
.properties file.
|
2003-03-13 09:01:54 +00:00
|
|
|
</p>
|
|
|
|
|
</body>
|
2007-10-11 08:31:12 +00:00
|
|
|
</html>
|
