Debian Codegraph @

manual/Tasks/sshsession.html

raw
1 <!DOCTYPE html>
2 <!--
3 Licensed to the Apache Software Foundation (ASF) under one or more
4 contributor license agreements. See the NOTICE file distributed with
5 this work for additional information regarding copyright ownership.
6 The ASF licenses this file to You under the Apache License, Version 2.0
7 (the "License"); you may not use this file except in compliance with
8 the License. You may obtain a copy of the License at
9
10 https://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 -->
18 <html lang="en">
19
20 <head>
21 <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22 <title>SSHSESSION Task</title>
23 </head>
24
25 <body>
26
27 <h2 id="sshsession">SSHSESSION</h2>
28 <p><em>Since Apache Ant 1.8.0</em></p>
29 <h3>Description</h3>
30
31 <p>A Task which establishes an SSH connection with a remote machine running SSH daemon, optionally
32 establishes any number of local or remote tunnels over that connection, then executes any nested
33 tasks before taking down the connection.</p>
34
35 <p><strong>Note</strong>: This task depends on external libraries not included in the Ant
36 distribution. See <a href="../install.html#librarydependencies">Library Dependencies</a> for more
37 information. This task has been tested with JSCh 0.1.33 and above and won't work with versions of
38 JSCh earlier than 0.1.28.</p>
39
40 <p>See also the <a href="sshexec.html">sshexec</a> and <a href="scp.html">scp</a> tasks</p>
41
42 <h3>Parameters</h3>
43 <table class="attr">
44 <tr>
45 <th scope="col">Attribute</th>
46 <th scope="col">Description</th>
47 <th scope="col">Required</th>
48 </tr>
49 <tr>
50 <td>host</td>
51 <td>The hostname or IP address of the remote host to which you wish to connect.</td>
52 <td>Yes</td>
53 </tr>
54 <tr>
55 <td>username</td>
56 <td>The username on the remote host to which you are connecting.</td>
57 <td>Yes</td>
58 </tr>
59 <tr>
60 <td>port</td>
61 <td>The port to connect to on the remote host.</td>
62 <td>No; defaults to <q>22</q></td>
63 </tr>
64 <tr>
65 <td>localtunnels</td>
66 <td>A comma-delimited list of colon-delimited <samp>lport:rhost:rport</samp> triplets defining
67 local port forwarding.<br/>If nested <a href="#LocalTunnel">localtunnel</a> elements are also
68 provided, both sets of tunnels will be established.</td>
69 <td>No</td>
70 </tr>
71 <tr>
72 <td>remotetunnels</td>
73 <td>A comma-delimited list of colon-delimited <samp>rport:lhost:lport</samp> triplets defining
74 remote port forwarding.<br/> If nested <a href="#RemoteTunnel">remotetunnel</a> elements are
75 also provided, both sets of tunnels will be established.</td>
76 <td>No</td>
77 </tr>
78 <tr>
79 <td>trust</td>
80 <td>This trusts all unknown hosts if set to <q>yes</q>
81 or <q>true</q>.<br/><strong>Note</strong>: If you set this to <q>false</q> (the default), the
82 host you connect to must be listed in your <var>knownhosts</var> file, this also implies that
83 the file exists.</td>
84 <td>No; defaults to <q>no</q></td>
85 </tr>
86 <tr>
87 <td>knownhosts</td>
88 <td>This sets the known hosts file to use to validate the identity of the remote host. This must
89 be a SSH2 format file. SSH1 format is not supported.</td>
90 <td>No; defaults to <q>${user.home}/.ssh/known_hosts</q></td>
91 </tr>
92 <tr>
93 <td>failonerror</td>
94 <td>Whether to halt the build if the command does not complete successfully.</td>
95 <td>No; defaults to <q>true</q></td>
96 </tr>
97 <tr>
98 <td>password</td>
99 <td>The password.</td>
100 <td>Yes, unless you are using key based authentication or the password has been given in the
101 file or <var>todir</var> attribute</td>
102 </tr>
103 <tr>
104 <td>keyfile</td>
105 <td>Location of the file holding the private key.</td>
106 <td>Yes, if you are using key based authentication</td>
107 </tr>
108 <tr>
109 <td>passphrase</td>
110 <td>Passphrase for your private key.</td>
111 <td>No; defaults to an empty string</td>
112 </tr>
113 <tr>
114 <td>sshConfig</td>
115 <td>Location of the file holding the OpenSSH style configuration (e.g. <code>${user.home}/.ssh/config</code>).
116 The username and the key file are read from the configuration file,
117 unless they are already specified in the task parameters.
118 <em>since Ant 1.10.8</em></td>
119 <td>No</td>
120 </tr>
121 <tr>
122 <td>timeout</td>
123 <td>Give up if the connection cannot be established within the specified time (given in
124 milliseconds).</td>
125 <td>No; defaults to <q>0</q> which means <q>never</q></td>
126 </tr>
127 </table>
128
129 <h3>Parameters specified as nested elements</h3>
130
131 <h4 id="LocalTunnel">localtunnel</h4>
132 <p>Optionally, any number of <code>localtunnel</code> elements can be used to define local port
133 forwarding over the SSH connection. If the <var>localtunnels</var> parameter was also specified,
134 both sets of tunnels will be established.</p>
135
136 <table class="attr">
137 <tr>
138 <th scope="col">Attribute</th>
139 <th scope="col">Description</th>
140 <th scope="col">Required</th>
141 </tr>
142 <tr>
143 <td>lport</td>
144 <td>The number of the local port to be forwarded.</td>
145 <td>Yes</td>
146 </tr>
147 <tr>
148 <td>rhost</td>
149 <td>The hostname or IP address of the remote host to which the local port should be
150 forwarded.</td>
151 <td>Yes</td>
152 </tr>
153 <tr>
154 <td>rport</td>
155 <td>The number of the port on the remote host to which the local port should be forwarded.</td>
156 <td>Yes</td>
157 </tr>
158 </table>
159
160 <h4 id="RemoteTunnel">remotetunnel</h4>
161 <p>Optionally, any number of <code>remotetunnel</code> elements can be used to define remote port
162 forwarding over the SSH connection. If the <var>remotetunnels</var> parameter was also specified,
163 both sets of tunnels will be established.</p>
164
165 <table class="attr">
166 <tr>
167 <th scope="col">Attribute</th>
168 <th scope="col">Description</th>
169 <th scope="col">Required</th>
170 </tr>
171 <tr>
172 <td>rport</td>
173 <td>The number of the remote port to be forwarded.</td>
174 <td>Yes</td>
175 </tr>
176 <tr>
177 <td>lhost</td>
178 <td>The hostname or IP address of the local host to which the remote port should be
179 forwarded.</td>
180 <td>Yes</td>
181 </tr>
182 <tr>
183 <td>lport</td>
184 <td>The number of the port on the local host to which the remote port should be forwarded.</td>
185 <td>Yes</td>
186 </tr>
187 </table>
188
189 <h4 id="additionalConfig">additionalConfig</h4>
190
191 <p><em>since Ant 1.10.10</em></p>
192
193 <p>Adds configuration settings for the JSch Session created that are
194 not directly supported by specific Ant attributes.</p>
195
196 <table class="attr">
197 <tr>
198 <th scope="col">Attribute</th>
199 <th scope="col">Description</th>
200 <th scope="col">Required</th>
201 </tr>
202 <tr>
203 <td>key</td>
204 <td>The key of the configuration setting.</td>
205 <td>Yes</td>
206 </tr>
207 <tr>
208 <td>value</td>
209 <td>The value of the configuration setting.</td>
210 <td>Yes</td>
211 </tr>
212 </table>
213
214 <h4 id="Sequential">sequential</h4>
215 <p>The <code>sequential</code> element is a required parameter. It is a container for nested Tasks
216 which are to be executed once the SSH connection is established and all local and/or remote tunnels
217 established.</p>
218
219 <h3>Examples</h3>
220
221 <p>Connect to a remote machine using password authentication, forward the local CVS port to the
222 remote host, and execute a CVS command locally, which can use the tunnel.</p>
223
224 <pre>
225 &lt;sshsession host=&quot;somehost&quot;
226 username=&quot;dude&quot;
227 password=&quot;yo&quot;
228 localtunnels=&quot;2401:localhost:2401&quot;&gt;
229 &lt;sequential&gt;
230 &lt;cvs command=&quot;update ${cvs.parms} ${module}&quot;
231 cvsRoot=&quot;${cvs.root}&quot;
232 dest=&quot;${local.root}&quot;
233 failonerror=&quot;true&quot;/&gt;
234 &lt;/sequential&gt;
235 &lt;/sshsession&gt;</pre>
236
237 <p>Do the same thing using nested <code>localtunnel</code> element.</p>
238
239 <pre>
240 &lt;sshsession host=&quot;somehost&quot;
241 username=&quot;dude&quot;
242 password=&quot;yo&quot;&gt;
243 &lt;localtunnel lport=&quot;2401&quot; rhost=&quot;localhost&quot; rport=&quot;2401&quot;/&gt;
244 &lt;sequential&gt;
245 &lt;cvs command=&quot;update ${cvs.parms} ${module}&quot;
246 cvsRoot=&quot;${cvs.root}&quot;
247 dest=&quot;${local.root}&quot;
248 failonerror=&quot;true&quot;/&gt;
249 &lt;/sequential&gt;
250 &lt;/sshsession&gt;</pre>
251
252 <p>Connect to a remote machine using key authentication, forward port 1080 to port 80 of an intranet
253 server which is not directly accessible, then run a <code>get</code> task using that tunnel.</p>
254
255 <pre>
256 &lt;sshsession host=&quot;somehost&quot;
257 username=&quot;dude&quot;
258 keyfile=&quot;${user.home}/.ssh/id_dsa&quot;
259 passphrase=&quot;yo its a secret&quot;/&gt;
260 &lt;LocalTunnel lport=&quot;1080&quot; rhost=&quot;intranet.mycomp.com&quot; rport=&quot;80&quot;/&gt;
261 &lt;sequential&gt;
262 &lt;get src=&quot;http://localhost:1080/somefile&quot; dest=&quot;temp/somefile&quot;/&gt;
263 &lt;/sequential&gt;
264 &lt;/sshsession&gt;</pre>
265
266 <p><strong>Security Note</strong>: Hardcoding passwords or passphrases and/or usernames
267 in <code>sshsession</code> task can be a serious security hole. Consider using variable substitution
268 and include the password on the command line. For example:</p>
269
270 <pre>
271 &lt;sshsession host=&quot;somehost&quot;
272 username=&quot;${username}&quot;
273 password=&quot;${password}&quot;
274 localtunnels=&quot;2401:localhost:2401&quot;&gt;
275 &lt;sequential&gt;
276 &lt;sometask/&gt;
277 &lt;/sequential&gt;
278 &lt;/sshsession&gt;</pre>
279
280 <p>Invoking Ant with the following command line:</p>
281 <pre class="input">ant -Dusername=me -Dpassword=mypassword target1 target2</pre>
282 <p>is slightly better, but the username/password is exposed to all users on an Unix system (via
283 the <kbd>ps</kbd> command). The best approach is to use the <code>&lt;input&gt;</code> task and/or
284 retrieve the password from a (secured) <samp>.properties</samp> file.</p>
285 </body>
286 </html>