net-ssh 1.1.3 → 1.1.4
Sign up to get free protection for your applications and to get access to all the features.
- data/NEWS +3 -0
- data/doc/manual-html/chapter-1.html +388 -0
- data/doc/manual-html/chapter-2.html +552 -0
- data/doc/manual-html/chapter-3.html +470 -0
- data/doc/manual-html/chapter-4.html +413 -0
- data/doc/manual-html/chapter-5.html +525 -0
- data/doc/manual-html/chapter-6.html +456 -0
- data/doc/manual-html/chapter-7.html +343 -0
- data/doc/manual-html/index.html +235 -0
- data/doc/manual-html/stylesheets/manual.css +270 -0
- data/doc/manual-html/stylesheets/ruby.css +17 -0
- data/lib/net/ssh/transport/packet-stream.rb +15 -15
- data/lib/net/ssh/version.rb +1 -1
- metadata +14 -2
|
@@ -0,0 +1,470 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>Net::SSH Manual :: Chapter 3: Channels</title>
|
|
4
|
+
<link type="text/css" rel="stylesheet" href="stylesheets/manual.css" />
|
|
5
|
+
</head>
|
|
6
|
+
|
|
7
|
+
<body>
|
|
8
|
+
<div id="banner">
|
|
9
|
+
<table border='0' cellpadding='0' cellspacing='0' width='100%'>
|
|
10
|
+
<tr><td valign='top' align='left'>
|
|
11
|
+
<div class="title">
|
|
12
|
+
<span class="product">Net::SSH—</span><br />
|
|
13
|
+
<span class="tagline">Secure Shell for Ruby</span>
|
|
14
|
+
</div>
|
|
15
|
+
</td><td valign='middle' align='right'>
|
|
16
|
+
<div class="info">
|
|
17
|
+
Net::SSH Version: <strong>1.1.4</strong><br />
|
|
18
|
+
Manual Last Updated: <strong>2008-05-01 21:55 UTC</strong>
|
|
19
|
+
</div>
|
|
20
|
+
</td></tr>
|
|
21
|
+
</table>
|
|
22
|
+
</div>
|
|
23
|
+
|
|
24
|
+
<table border='0' width='100%' cellpadding='0' cellspacing='0'>
|
|
25
|
+
<tr><td valign='top'>
|
|
26
|
+
|
|
27
|
+
<div id="navigation">
|
|
28
|
+
<h1>Net::SSH Manual</h1>
|
|
29
|
+
|
|
30
|
+
<h2>Chapters</h2>
|
|
31
|
+
<ol type="I">
|
|
32
|
+
|
|
33
|
+
<li>
|
|
34
|
+
<a href="chapter-1.html">
|
|
35
|
+
Introduction
|
|
36
|
+
</a>
|
|
37
|
+
|
|
38
|
+
<ol type="1">
|
|
39
|
+
|
|
40
|
+
<li><a href="chapter-1.html#s1">What is Net::SSH?</a></li>
|
|
41
|
+
|
|
42
|
+
<li><a href="chapter-1.html#s2">What isn’t Net::SSH?</a></li>
|
|
43
|
+
|
|
44
|
+
<li><a href="chapter-1.html#s3">Getting Net::SSH</a></li>
|
|
45
|
+
|
|
46
|
+
<li><a href="chapter-1.html#s4">License Information</a></li>
|
|
47
|
+
|
|
48
|
+
<li><a href="chapter-1.html#s5">Support</a></li>
|
|
49
|
+
|
|
50
|
+
<li><a href="chapter-1.html#s6">About the Author</a></li>
|
|
51
|
+
|
|
52
|
+
</ol>
|
|
53
|
+
</li>
|
|
54
|
+
|
|
55
|
+
<li>
|
|
56
|
+
<a href="chapter-2.html">
|
|
57
|
+
Starting a Session
|
|
58
|
+
</a>
|
|
59
|
+
|
|
60
|
+
<ol type="1">
|
|
61
|
+
|
|
62
|
+
<li><a href="chapter-2.html#s1">Using Net::SSH.start</a></li>
|
|
63
|
+
|
|
64
|
+
<li><a href="chapter-2.html#s2">Using a Public/Private Key</a></li>
|
|
65
|
+
|
|
66
|
+
<li><a href="chapter-2.html#s3">Options</a></li>
|
|
67
|
+
|
|
68
|
+
<li><a href="chapter-2.html#s4">Using Net::SSH::Session</a></li>
|
|
69
|
+
|
|
70
|
+
</ol>
|
|
71
|
+
</li>
|
|
72
|
+
|
|
73
|
+
<li><strong>
|
|
74
|
+
<a href="chapter-3.html">
|
|
75
|
+
Channels
|
|
76
|
+
</a>
|
|
77
|
+
</strong> <big>←</big>
|
|
78
|
+
<ol type="1">
|
|
79
|
+
|
|
80
|
+
<li><a href="chapter-3.html#s1">What are Channels?</a></li>
|
|
81
|
+
|
|
82
|
+
<li><a href="chapter-3.html#s2">Session.loop</a></li>
|
|
83
|
+
|
|
84
|
+
<li><a href="chapter-3.html#s3">Channel Types</a></li>
|
|
85
|
+
|
|
86
|
+
<li><a href="chapter-3.html#s4">Opening a Channel</a></li>
|
|
87
|
+
|
|
88
|
+
<li><a href="chapter-3.html#s5">Callbacks</a></li>
|
|
89
|
+
|
|
90
|
+
<li><a href="chapter-3.html#s6">Channel Operations</a></li>
|
|
91
|
+
|
|
92
|
+
</ol>
|
|
93
|
+
</li>
|
|
94
|
+
|
|
95
|
+
<li>
|
|
96
|
+
<a href="chapter-4.html">
|
|
97
|
+
Executing Commands
|
|
98
|
+
</a>
|
|
99
|
+
|
|
100
|
+
<ol type="1">
|
|
101
|
+
|
|
102
|
+
<li><a href="chapter-4.html#s1">Using Channels</a></li>
|
|
103
|
+
|
|
104
|
+
<li><a href="chapter-4.html#s2">Using #process.open</a></li>
|
|
105
|
+
|
|
106
|
+
<li><a href="chapter-4.html#s3">Using #process.popen3</a></li>
|
|
107
|
+
|
|
108
|
+
</ol>
|
|
109
|
+
</li>
|
|
110
|
+
|
|
111
|
+
<li>
|
|
112
|
+
<a href="chapter-5.html">
|
|
113
|
+
User Shells
|
|
114
|
+
</a>
|
|
115
|
+
|
|
116
|
+
<ol type="1">
|
|
117
|
+
|
|
118
|
+
<li><a href="chapter-5.html#s1">Introduction</a></li>
|
|
119
|
+
|
|
120
|
+
<li><a href="chapter-5.html#s2">Using Channels</a></li>
|
|
121
|
+
|
|
122
|
+
<li><a href="chapter-5.html#s3">Shell Service</a></li>
|
|
123
|
+
|
|
124
|
+
<li><a href="chapter-5.html#s4">SyncShell Service</a></li>
|
|
125
|
+
|
|
126
|
+
<li><a href="chapter-5.html#s5">Terminal Clients</a></li>
|
|
127
|
+
|
|
128
|
+
</ol>
|
|
129
|
+
</li>
|
|
130
|
+
|
|
131
|
+
<li>
|
|
132
|
+
<a href="chapter-6.html">
|
|
133
|
+
Port Forwarding
|
|
134
|
+
</a>
|
|
135
|
+
|
|
136
|
+
<ol type="1">
|
|
137
|
+
|
|
138
|
+
<li><a href="chapter-6.html#s1">Introduction</a></li>
|
|
139
|
+
|
|
140
|
+
<li><a href="chapter-6.html#s2">Local-to-Remote</a></li>
|
|
141
|
+
|
|
142
|
+
<li><a href="chapter-6.html#s3">Remote-to-Local</a></li>
|
|
143
|
+
|
|
144
|
+
<li><a href="chapter-6.html#s4">Direct Channels</a></li>
|
|
145
|
+
|
|
146
|
+
<li><a href="chapter-6.html#s5">Remote-to-Local Handlers</a></li>
|
|
147
|
+
|
|
148
|
+
</ol>
|
|
149
|
+
</li>
|
|
150
|
+
|
|
151
|
+
<li>
|
|
152
|
+
<a href="chapter-7.html">
|
|
153
|
+
Using Proxies
|
|
154
|
+
</a>
|
|
155
|
+
|
|
156
|
+
<ol type="1">
|
|
157
|
+
|
|
158
|
+
<li><a href="chapter-7.html#s1">Introduction</a></li>
|
|
159
|
+
|
|
160
|
+
<li><a href="chapter-7.html#s2"><span class="caps">HTTP</span></a></li>
|
|
161
|
+
|
|
162
|
+
<li><a href="chapter-7.html#s3"><span class="caps">SOCKS</span></a></li>
|
|
163
|
+
|
|
164
|
+
</ol>
|
|
165
|
+
</li>
|
|
166
|
+
|
|
167
|
+
</ol>
|
|
168
|
+
|
|
169
|
+
<h2>Other Documentation</h2>
|
|
170
|
+
|
|
171
|
+
<ul>
|
|
172
|
+
<li><a href="http://net-ssh.rubyforge.org/api/index.html">Net::SSH API</a></li>
|
|
173
|
+
<li><a href="http://rubyforge.org/tracker/?atid=1842&group_id=274&func=browse">Net::SSH FAQ</a></li>
|
|
174
|
+
</ul>
|
|
175
|
+
|
|
176
|
+
<h2>Tutorials</h2>
|
|
177
|
+
<ol>
|
|
178
|
+
|
|
179
|
+
</ol>
|
|
180
|
+
|
|
181
|
+
<p align="center"><strong>More To Come...</strong></p>
|
|
182
|
+
|
|
183
|
+
<div class="license">
|
|
184
|
+
<a href="http://creativecommons.org/licenses/by-sa/2.0/"><img alt="Creative Commons License" border="0" src="http://creativecommons.org/images/public/somerights" /></a><br />
|
|
185
|
+
This manual is licensed under a <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons License</a>.
|
|
186
|
+
</div>
|
|
187
|
+
</div>
|
|
188
|
+
|
|
189
|
+
</td><td valign='top' width="100%">
|
|
190
|
+
|
|
191
|
+
<div id="content">
|
|
192
|
+
|
|
193
|
+
<div class="top"><div class="prevnext">
|
|
194
|
+
|
|
195
|
+
<a href="chapter-2.html">Previous (2. Starting a Session)</a> |
|
|
196
|
+
|
|
197
|
+
<a href="index.html">Up</a>
|
|
198
|
+
|
|
199
|
+
| <a href="chapter-4.html">Next (4. Executing Commands)</a>
|
|
200
|
+
|
|
201
|
+
</div></div>
|
|
202
|
+
|
|
203
|
+
<h1>3. Channels</h1>
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
<h2>
|
|
208
|
+
<a name="s1"></a>
|
|
209
|
+
3.1. What are Channels?
|
|
210
|
+
</h2>
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
<div class="section">
|
|
215
|
+
<p>The <span class="caps">SSH</span> protocol requires that requests for services on a remote machine be made over <em>channels</em>. A single <span class="caps">SSH</span> connection may contain multiple channels, all run simultaneously over that connection.</p>
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
<p>Each channel, in turn, represents the processing of a single service. When you invoke a process on the remote host with Net::SSH, a channel is opened for that invocation, and all input and output relevant to that process is sent through that channel. The connection itself simply manages the packets of all of the channels that it has open.</p>
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
<p>This means that, for instance, over a single <span class="caps">SSH</span> connection you could execute a process, download a file via <span class="caps">SFTP</span>, and forward any number of ports, all (seemingly) at the same time!</p>
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
<p>Naturally, they do not occur simultaneously, but rather work in a “time-share” fashion by sharing the bandwidth of the connection. Nevertheless, the fact that these channels exist make working with the <span class="caps">SSH</span> protocol a bit more challenging than simpler protocols (like <span class="caps">FTP</span>, HTTP, or Telnet).</p>
|
|
225
|
+
</div>
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
<h2>
|
|
230
|
+
<a name="s2"></a>
|
|
231
|
+
3.2. Session.loop
|
|
232
|
+
</h2>
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
<div class="section">
|
|
237
|
+
<p>Because a session may be composed of multiple simultaneously operating channels, the Net::SSH interface works by means of <em>callbacks</em>. You specify actions that need to occur in response to various events, and when those events occur, the framework invokes the corresonding callbacks.</p>
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
<p>In order to allow the events to be processed in a continuous manner, you need to be sure to call the <code>loop</code> method of your session handle, after setting up any callbacks that you want to be executed. If you do not call the <code>loop</code> method, your session will terminate as soon as the block is exited, which means none of your carefully laid callbacks will ever be called.</p>
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
<p>The <code>loop</code> method is easy to invoke:</p>
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
<div class='figure'>
|
|
247
|
+
<span class='caption'>Session#loop [ruby]</span>
|
|
248
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="constant">Net</span><span class="punct">::</span><span class="constant">SSH</span><span class="punct">.</span><span class="ident">start</span><span class="punct">(</span> <span class="punct">'</span><span class="string">host</span><span class="punct">'</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
|
|
249
|
+
<span class="punct">...</span>
|
|
250
|
+
<span class="ident">session</span><span class="punct">.</span><span class="ident">loop</span>
|
|
251
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
<p>Incidentally, the <code>loop</code> method accepts an optional block, which if specified should return a “false” value when the loop should terminate. In the absense of a block, the loop will continue until there are no more open channels. Sometimes, however, you only want the loop to continue until some action occurs, at which time you then do some processing and then start the loop again.</p>
|
|
255
|
+
</div>
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
<h2>
|
|
260
|
+
<a name="s3"></a>
|
|
261
|
+
3.3. Channel Types
|
|
262
|
+
</h2>
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
<div class="section">
|
|
267
|
+
<p>Each channel has a <em>type</em>. Usually, you will use “session” channels, but there are also “x11” channels, “forwarded-tcpip” channels, and “direct-tcpip” channels. Net::SSH currently has no support for “x11” channels. The “forwarded-tcpip” and “direct-tcpip” channels are managed internally via the port-forwarding interfaces.</p>
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
<p>The “session” channel type allows for a broad range of actions, including (but not limited to) <span class="caps">SFTP</span> requests and remote process execution.</p>
|
|
271
|
+
</div>
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
<h2>
|
|
276
|
+
<a name="s4"></a>
|
|
277
|
+
3.4. Opening a Channel
|
|
278
|
+
</h2>
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
<div class="section">
|
|
283
|
+
<p>The simplest way to open a channel is via the <code>open_channel</code> method of Net::SSH::Session. By default, the channel will be of type “session”, but you can optionally specify the channel type and any extra data to initialize the channel with. You also pass a block to the <code>open_channel</code> invocation. This block will be called after the server has confirmed that the channel is valid and has been opened successfully.</p>
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
<p>The <code>open_channel</code> method always returns immediately—all it does is inform the server that a channel needs to be opened and then registers the associated block as the callback to be invoked when the channel is confirmed.</p>
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
<p>This behavior is typical of most of the methods in the Net::SSH <span class="caps">API</span>; they simply send a request to the server and then (optionally) register a callback. Very few of them actually block (pause) until the server responds.</p>
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
<p>Here is an example of opening a channel:</p>
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
<div class='figure'>
|
|
296
|
+
<span class='caption'>Opening a channel [ruby]</span>
|
|
297
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="constant">Net</span><span class="punct">::</span><span class="constant">SSH</span><span class="punct">.</span><span class="ident">start</span><span class="punct">(</span> <span class="punct">'</span><span class="string">host</span><span class="punct">'</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
|
|
298
|
+
<span class="ident">session</span><span class="punct">.</span><span class="ident">open_channel</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">channel</span><span class="punct">|</span>
|
|
299
|
+
<span class="ident">puts</span> <span class="punct">"</span><span class="string">channel successfully opened... closing...</span><span class="punct">"</span>
|
|
300
|
+
<span class="ident">channel</span><span class="punct">.</span><span class="ident">close</span>
|
|
301
|
+
<span class="keyword">end</span>
|
|
302
|
+
|
|
303
|
+
<span class="ident">session</span><span class="punct">.</span><span class="ident">loop</span>
|
|
304
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
<p>Note the use of the <code>close</code> method for the channel. Just like most methods in the Net::SSH <span class="caps">API</span>, it does not immediately close the channel, but instead sends a close request to the server and returns. When the server responds that the channel has been closed, the framework will then call any final callbacks for the channel and then remove it.</p>
|
|
308
|
+
</div>
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
<h2>
|
|
313
|
+
<a name="s5"></a>
|
|
314
|
+
3.5. Callbacks
|
|
315
|
+
</h2>
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
<div class="section">
|
|
320
|
+
<p>There are various callbacks that may be registered on a channel. Registering a callback is as simple as invoking the corresponding method on the channel and giving it a block that should be invoked when the named action occurs. The following table describes each callback and how it is used.</p>
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
<table class="list">
|
|
324
|
+
<tr>
|
|
325
|
+
<th>Name </th>
|
|
326
|
+
<th>Description </th>
|
|
327
|
+
</tr>
|
|
328
|
+
<tr>
|
|
329
|
+
<td style="vertical-align:top;text-align:center;"><code>on_close</code> </td>
|
|
330
|
+
<td> This callback should accept a single parameter: the channel being closed. It is called immediately after the channel is removed from the connection. The callback should not send any data through the channel, since at this point the channel is no longer connected to the remote host.</td>
|
|
331
|
+
</tr>
|
|
332
|
+
<tr>
|
|
333
|
+
<td style="vertical-align:top;text-align:center;"><code>on_confirm_failed</code> </td>
|
|
334
|
+
<td> This callback should accept four parameters: the channel instance, the reason code, a description of why the confirm failed, and the language code for the message. It is called immediately after the server has indicated that a channel could not be opened.</td>
|
|
335
|
+
</tr>
|
|
336
|
+
<tr>
|
|
337
|
+
<td style="vertical-align:top;text-align:center;"><code>on_confirm_open</code> </td>
|
|
338
|
+
<td> This callback should accept a single parameter: the channel being opened. It is called immediately after the server has confirmed that the channel has been opened. This callback is typically set by a block passed to an <code>#open_channel</code> call.</td>
|
|
339
|
+
</tr>
|
|
340
|
+
<tr>
|
|
341
|
+
<td style="vertical-align:top;text-align:center;"><code>on_data</code> </td>
|
|
342
|
+
<td> This callback is invoked when data is received over the channel from the remote server. This data typically corresponds to the remote process’s <code>stdout</code> stream. The channel should accept two parameters: the channel itself, and the data being received.</td>
|
|
343
|
+
</tr>
|
|
344
|
+
<tr>
|
|
345
|
+
<td style="vertical-align:top;text-align:center;"><code>on_eof</code> </td>
|
|
346
|
+
<td> This callback is called when the server indicates that no more data will be sent <em>from the server</em> over this channel. Your program is still welcome to send data to the server, but you are guaranteed at this point that your <code>on_data</code> and <code>on_extended_data</code> callbacks will no longer be called for this channel. The callback should accept a single parameter, the channel itself.</td>
|
|
347
|
+
</tr>
|
|
348
|
+
<tr>
|
|
349
|
+
<td style="vertical-align:top;text-align:center;"><code>on_extended_data</code> </td>
|
|
350
|
+
<td> This callback is called when <em>extended data</em> is received from the server. There are (potentially) many <em>types</em> of extended data. The callback should accept three parameters: the channel, an integer indicating the type of the data, and the data itself. Right now, you can pretty much count on the data type being a “1”, which corresponds to the remote process’s <code>stderr</code> stream. Other data types are not defined in the <span class="caps">SSH</span> specification, but that does not mean some <span class="caps">SSH</span> servers won’t try to invent their own.</td>
|
|
351
|
+
</tr>
|
|
352
|
+
<tr>
|
|
353
|
+
<td style="vertical-align:top;text-align:center;"><code>on_failure</code> </td>
|
|
354
|
+
<td> When a request is sent over a channel (via the <code>send_request</code> or <code>send_request_string</code> methods), it may either succeed or fail. If it fails, this callback will be invoked. It should take a single parameter: the channel itself.</td>
|
|
355
|
+
</tr>
|
|
356
|
+
<tr>
|
|
357
|
+
<td style="vertical-align:top;text-align:center;"><code>on_request</code> </td>
|
|
358
|
+
<td> When the server sends a “channel request” to the client, this callback will be invoked. Channel requests from the server typically indicate things like the exit status of a process. This callback should take four parameters: the channel, the type of request (as a string, like “exit-status”), a boolean (indicating whether or not the server wants an explicit reply to this request), and the data from the request, which will be a buffer object (see the <span class="caps">API</span> documentation for <code>Net::SSH::Util::ReaderBufferImpl</code>).</td>
|
|
359
|
+
</tr>
|
|
360
|
+
<tr>
|
|
361
|
+
<td style="vertical-align:top;text-align:center;"><code>on_success</code> </td>
|
|
362
|
+
<td> When a request is sent over a channel (via the <code>send_request</code> or <code>send_request_string</code> methods), it may either succeed or fail. If it succeeds, this callback will be invoked. It should take a single parameter: the channel itself.</td>
|
|
363
|
+
</tr>
|
|
364
|
+
<tr>
|
|
365
|
+
<td style="vertical-align:top;text-align:center;"><code>on_window_adjust</code> </td>
|
|
366
|
+
<td> When the server asks the client to adjust this channel’s window size, this callback will be invoked. It should accept two parameters: the channel, and the number of bytes to add the channel’s window size.</td>
|
|
367
|
+
</tr>
|
|
368
|
+
</table>
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
<p>In general, you will never need to register callbacks for <code>on_failure</code>, <code>on_request</code>, <code>on_success</code>, or <code>on_window_adjust</code>, unless you are needing to implement support for some subservice or piggy-backed protocol (like <span class="caps">SFTP</span>).</p>
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
<p>Following is an example of registering callbacks on a channel:</p>
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
<div class='figure'>
|
|
380
|
+
<span class='caption'>Registering callbacks on a channel [ruby]</span>
|
|
381
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br />4<br />5<br />6<br />7<br />8<br />9<br />10<br />11<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="constant">Net</span><span class="punct">::</span><span class="constant">SSH</span><span class="punct">.</span><span class="ident">start</span><span class="punct">(</span> <span class="punct">'</span><span class="string">host</span><span class="punct">'</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
|
|
382
|
+
<span class="ident">session</span><span class="punct">.</span><span class="ident">open_channel</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">channel</span><span class="punct">|</span>
|
|
383
|
+
<span class="ident">channel</span><span class="punct">.</span><span class="ident">on_close</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">ch</span><span class="punct">|</span>
|
|
384
|
+
<span class="ident">puts</span> <span class="punct">"</span><span class="string">channel closed successfully.</span><span class="punct">"</span>
|
|
385
|
+
<span class="keyword">end</span>
|
|
386
|
+
<span class="ident">puts</span> <span class="punct">"</span><span class="string">closing channel...</span><span class="punct">"</span>
|
|
387
|
+
<span class="ident">channel</span><span class="punct">.</span><span class="ident">close</span>
|
|
388
|
+
<span class="keyword">end</span>
|
|
389
|
+
|
|
390
|
+
<span class="ident">session</span><span class="punct">.</span><span class="ident">loop</span>
|
|
391
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
392
|
+
</div>
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
|
|
396
|
+
<h2>
|
|
397
|
+
<a name="s6"></a>
|
|
398
|
+
3.6. Channel Operations
|
|
399
|
+
</h2>
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
<div class="section">
|
|
404
|
+
<p>There are a variety of operations that may be performed on a channel. Some we’ve already mentioned, like registering callbacks, or closing the channel. Some of the other more common operations are listed (and described) in the following table.</p>
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
<table class="list">
|
|
408
|
+
<tr>
|
|
409
|
+
<th>Operation </th>
|
|
410
|
+
<th>Description </th>
|
|
411
|
+
</tr>
|
|
412
|
+
<tr>
|
|
413
|
+
<td> <code>#exec</code> </td>
|
|
414
|
+
<td> Executes a command asynchronously on this channel.</td>
|
|
415
|
+
</tr>
|
|
416
|
+
<tr>
|
|
417
|
+
<td> <code>#request_pty</code> </td>
|
|
418
|
+
<td> Requests that a pseudo-terminal (pty) be opened for this channel.</td>
|
|
419
|
+
</tr>
|
|
420
|
+
<tr>
|
|
421
|
+
<td> <code>#send_data</code> </td>
|
|
422
|
+
<td> Sends the given data string to the server via this channel. This is useful for sending data to a remote process, or sending an <span class="caps">SFTP</span> packet to the <span class="caps">SFTP</span> subsystem.</td>
|
|
423
|
+
</tr>
|
|
424
|
+
<tr>
|
|
425
|
+
<td> <code>#send_eof</code> </td>
|
|
426
|
+
<td> Tells the server that no further data will be sent from the client to the server. The client must honor this by not sending any more data (either normal or extended) to the server over this channel.</td>
|
|
427
|
+
</tr>
|
|
428
|
+
<tr>
|
|
429
|
+
<td> <code>#send_extended_data</code> </td>
|
|
430
|
+
<td> Sends a data string to the server, along with an integer describing its type. This is typically used to send <code>stderr</code> data.</td>
|
|
431
|
+
</tr>
|
|
432
|
+
<tr>
|
|
433
|
+
<td> <code>#send_request</code> </td>
|
|
434
|
+
<td> Sends a named request to the server for this channel. This is primarily used by implementations of protocols and subsystems that run on top of <span class="caps">SSH</span>.</td>
|
|
435
|
+
</tr>
|
|
436
|
+
<tr>
|
|
437
|
+
<td> <code>#send_signal</code> </td>
|
|
438
|
+
<td> Indicates that the server should send the given signal to the process on the other end of the channel.</td>
|
|
439
|
+
</tr>
|
|
440
|
+
<tr>
|
|
441
|
+
<td> <code>#subsystem</code> </td>
|
|
442
|
+
<td> Requests that the server start the given subsystem on this channel. This is how (for instance) the <span class="caps">SFTP</span> subsystem is invoked. </td>
|
|
443
|
+
</tr>
|
|
444
|
+
</table>
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
|
|
448
|
+
|
|
449
|
+
<p>See the <span class="caps">API</span> documentation for an exhaustive reference of all available channel operations.</p>
|
|
450
|
+
</div>
|
|
451
|
+
|
|
452
|
+
|
|
453
|
+
|
|
454
|
+
<div class="bottom"><div class="prevnext">
|
|
455
|
+
|
|
456
|
+
<a href="chapter-2.html">Previous (2. Starting a Session)</a> |
|
|
457
|
+
|
|
458
|
+
<a href="index.html">Up</a>
|
|
459
|
+
|
|
460
|
+
| <a href="chapter-4.html">Next (4. Executing Commands)</a>
|
|
461
|
+
|
|
462
|
+
</div></div>
|
|
463
|
+
|
|
464
|
+
|
|
465
|
+
</div>
|
|
466
|
+
|
|
467
|
+
</td></tr>
|
|
468
|
+
</table>
|
|
469
|
+
</body>
|
|
470
|
+
</html>
|