diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/sshsession.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/sshsession.html | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/sshsession.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/sshsession.html new file mode 100644 index 00000000..e9696d1f --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/sshsession.html @@ -0,0 +1,288 @@ +<!-- + 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 Apache 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> |