mirror of
https://github.com/apache/ant.git
synced 2025-05-18 22:14:47 +00:00
289 lines
10 KiB
HTML
289 lines
10 KiB
HTML
|
<!--
|
||
|
|
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.
|
||
|
|
-->
|
||
|
|
<html>
|
||
|
|
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Language" content="en-us">
|
||
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
||
|
|
<title>SSHSESSION Task</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<h2><a name="sshsession">SSHSESSION</a></h2>
|
||
|
|
<h3>Description</h3>
|
||
|
|
|
||
|
|
<p><em>since Ant 1.8.0</em></p>
|
||
|
|
|
||
|
|
<p>A Task which establishes an SSH connection with a remote machine
|
||
|
|
running SSH daemon, optionally establishes any number of local or
|
||
|
|
remote tunnels over that connection, then executes any nested tasks
|
||
|
|
before taking down the connection.
|
||
|
|
</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> for more information. This task has been tested with
|
||
|
|
jsch-0.1.33 and above and won't work with versions of jsch earlier
|
||
|
|
than 0.1.28.</p>
|
||
|
|
|
||
|
|
<p>See also the <a href="sshexec.html">sshexec</a>
|
||
|
|
and <a href="scp.html">scp</a> tasks</p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">host</td>
|
||
|
|
<td valign="top">The hostname or IP address of the remote host to which you wish to connect.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
<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">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>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">localtunnels</td>
|
||
|
|
<td valign="top">A comma-delimited list of
|
||
|
|
colon-delimited <code>lport:rhost:rport</code> triplets defining
|
||
|
|
local port forwarding.<br> If
|
||
|
|
nested <a href="#LocalTunnel">localtunnel</a> elements are also
|
||
|
|
provided, both sets of tunnels will be established.</td>
|
||
|
|
<td valian="top" align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">remotetunnels</td>
|
||
|
|
<td valign="top">A comma-delimited list of
|
||
|
|
colon-delimited <code>rport:lhost:lport</code> triplets defining
|
||
|
|
remote port forwarding.<br> If
|
||
|
|
nested <a href="#RemoteTunnel">remotetunnel</a> elements are
|
||
|
|
also provided, both sets of tunnels will be established.</td>
|
||
|
|
<td valian="top" align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">trust</td>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<td valign="top">Whether to halt the build if the command does not complete successfully.
|
||
|
|
</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>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">timeout</td>
|
||
|
|
<td valign="top">Give up if the connection cannot be established
|
||
|
|
within the specified time (given in milliseconds). Defaults to 0
|
||
|
|
which means "wait forever".</td>
|
||
|
|
<td align="center" valign="top">No</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h3>Parameters specified as nested elements</h3>
|
||
|
|
|
||
|
|
<a name="LocalTunnel"><h4>localtunnel</h4></a>
|
||
|
|
<p>Optionally, any number of localtunnel elements can be used to
|
||
|
|
define local port forwarding over the SSH connection. If the
|
||
|
|
localtunnels parameter was also specified, both sets of tunnels will
|
||
|
|
be established.</p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">lport</td>
|
||
|
|
<td valign="top">The number of the local port to be forwarded.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">rhost</td>
|
||
|
|
<td valign="top">The hostname or IP address of the remote host to
|
||
|
|
which the local port should be forwarded.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">rport</td>
|
||
|
|
<td valign="top">The number of the port on the remote host to
|
||
|
|
which the local port should be forwarded.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<a name="RemoteTunnel"><h4>remotetunnel</h4></a>
|
||
|
|
<p>Optionally, any number of remotetunnel elements can be used to
|
||
|
|
define remote port forwarding over the SSH connection. If the
|
||
|
|
remotetunnels parameter was also specified, both sets of tunnels will
|
||
|
|
be established.</p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">rport</td>
|
||
|
|
<td valign="top">The number of the remote port to be forwarded.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">lhost</td>
|
||
|
|
<td valign="top">The hostname or IP address of the local host to
|
||
|
|
which the remote port should be forwarded.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">lport</td>
|
||
|
|
<td valign="top">The number of the port on the local host to which
|
||
|
|
the remote port should be forwarded.</td>
|
||
|
|
<td valign="top" align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<a name="Sequential"><h4>sequential</h4></a>
|
||
|
|
<p>The sequential element is a required parameter. It is a container
|
||
|
|
for nested Tasks which are to be executed once the SSH connection is
|
||
|
|
established and all local and/or remote tunnels established.</p>
|
||
|
|
|
||
|
|
<h3>Examples</h3>
|
||
|
|
<p><b>Connect to a remote machine using password authentication,
|
||
|
|
forward the local cvs port to the remote host, and execute a cvs
|
||
|
|
command locally, which can use the tunnel.</b></p>
|
||
|
|
<pre>
|
||
|
|
<sshsession host="somehost"
|
||
|
|
username="dude"
|
||
|
|
password="yo"
|
||
|
|
localtunnels="2401:localhost:2401"
|
||
|
|
>
|
||
|
|
<sequential>
|
||
|
|
<cvs command="update ${cvs.parms} ${module}"
|
||
|
|
cvsRoot="${cvs.root}"
|
||
|
|
dest="${local.root}"
|
||
|
|
failonerror="true"
|
||
|
|
/>
|
||
|
|
</sequential>
|
||
|
|
</sshsession>
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p><b>Do the same thing using nested localtunnel element.</b></p>
|
||
|
|
<pre>
|
||
|
|
<sshsession host="somehost"
|
||
|
|
username="dude"
|
||
|
|
password="yo"
|
||
|
|
>
|
||
|
|
<localtunnel lport="2401" rhost="localhost" rport="2401"/>
|
||
|
|
<sequential>
|
||
|
|
<cvs command="update ${cvs.parms} ${module}"
|
||
|
|
cvsRoot="${cvs.root}"
|
||
|
|
dest="${local.root}"
|
||
|
|
failonerror="true"
|
||
|
|
/>
|
||
|
|
</sequential>
|
||
|
|
</sshsession>
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p><b>Connect to a remote machine using key authentication, forward
|
||
|
|
port 1080 to port 80 of an intranet server which is not directly
|
||
|
|
accessible, then run a get task using that tunnel.</b></p>
|
||
|
|
<pre>
|
||
|
|
<sshsession host="somehost"
|
||
|
|
username="dude"
|
||
|
|
keyfile="${user.home}/.ssh/id_dsa"
|
||
|
|
passphrase="yo its a secret"/>
|
||
|
|
<LocalTunnel lport="1080" rhost="intranet.mycomp.com" rport="80"/>
|
||
|
|
<sequential>
|
||
|
|
<get src="http://localhost:1080/somefile" dest="temp/somefile"/>
|
||
|
|
</sequential>
|
||
|
|
</sshsession>
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
|
||
|
|
<p><strong>Security Note:</strong> Hard coding passwords or
|
||
|
|
passphrases and/or usernames in sshsession task can be a serious
|
||
|
|
security hole. Consider using variable substitution and include the
|
||
|
|
password on the command line. For example:<br>
|
||
|
|
<pre>
|
||
|
|
<sshsession host="somehost"
|
||
|
|
username="${username}"
|
||
|
|
password="${password}"
|
||
|
|
localtunnels="2401:localhost:2401">
|
||
|
|
<sequential>
|
||
|
|
<sometask/>
|
||
|
|
</sequential>
|
||
|
|
</sshsession>
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Invoking ant with the following command line:
|
||
|
|
<pre>
|
||
|
|
ant -Dusername=me -Dpassword=mypassword target1 target2
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
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.
|
||
|
|
</p>
|
||
|
|
</body>
|
||
|
|
</html>
|