net-ssh 1.0.0 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (52) hide show
  1. data/doc/manual-html/chapter-1.html +388 -0
  2. data/doc/manual-html/chapter-2.html +544 -0
  3. data/doc/manual-html/chapter-3.html +470 -0
  4. data/doc/manual-html/chapter-4.html +413 -0
  5. data/doc/manual-html/chapter-5.html +525 -0
  6. data/doc/manual-html/chapter-6.html +456 -0
  7. data/doc/manual-html/chapter-7.html +343 -0
  8. data/doc/manual-html/index.html +237 -0
  9. data/doc/manual-html/stylesheets/manual.css +270 -0
  10. data/doc/manual-html/stylesheets/ruby.css +17 -0
  11. data/doc/manual/manual.rb +2 -2
  12. data/doc/manual/manual.yml +41 -44
  13. data/doc/manual/parts/{intro_what_is.txt → 0000.txt} +0 -0
  14. data/doc/manual/parts/{intro_what_is_not.txt → 0001.txt} +0 -0
  15. data/doc/manual/parts/{intro_getting.txt → 0002.txt} +7 -6
  16. data/doc/manual/parts/{intro_license.txt → 0003.txt} +0 -0
  17. data/doc/manual/parts/{intro_support.txt → 0004.txt} +0 -0
  18. data/doc/manual/parts/{intro_author.txt → 0005.txt} +1 -1
  19. data/doc/manual/parts/{session_start.txt → 0006.txt} +11 -11
  20. data/doc/manual/parts/{session_key.txt → 0007.txt} +6 -6
  21. data/doc/manual/parts/{session_options.txt → 0008.txt} +2 -3
  22. data/doc/manual/parts/0009.txt +14 -0
  23. data/doc/manual/parts/{channels_what_are.txt → 0010.txt} +0 -0
  24. data/doc/manual/parts/{channels_loop.txt → 0011.txt} +2 -2
  25. data/doc/manual/parts/{channels_types.txt → 0012.txt} +0 -0
  26. data/doc/manual/parts/{channels_open.txt → 0013.txt} +2 -2
  27. data/doc/manual/parts/{channels_callbacks.txt → 0014.txt} +3 -3
  28. data/doc/manual/parts/{channels_operations.txt → 0015.txt} +1 -2
  29. data/doc/manual/parts/{exec_channels.txt → 0016.txt} +2 -2
  30. data/doc/manual/parts/{exec_open.txt → 0017.txt} +3 -3
  31. data/doc/manual/parts/{exec_popen3.txt → 0018.txt} +5 -5
  32. data/doc/manual/parts/{shells_intro.txt → 0019.txt} +0 -0
  33. data/doc/manual/parts/{shells_channels.txt → 0020.txt} +5 -5
  34. data/doc/manual/parts/{shells_shell.txt → 0021.txt} +6 -6
  35. data/doc/manual/parts/{shells_sync.txt → 0022.txt} +4 -4
  36. data/doc/manual/parts/{shells_clients.txt → 0023.txt} +3 -3
  37. data/doc/manual/parts/{forward_intro.txt → 0024.txt} +2 -2
  38. data/doc/manual/parts/{forward_local.txt → 0025.txt} +4 -4
  39. data/doc/manual/parts/{forward_remote.txt → 0026.txt} +6 -5
  40. data/doc/manual/parts/{forward_direct.txt → 0027.txt} +2 -2
  41. data/doc/manual/parts/{forward_handlers.txt → 0028.txt} +0 -0
  42. data/doc/manual/parts/{proxy_intro.txt → 0029.txt} +0 -0
  43. data/doc/manual/parts/{proxy_http.txt → 0030.txt} +6 -6
  44. data/doc/manual/parts/{proxy_socks.txt → 0031.txt} +4 -2
  45. data/doc/manual/stylesheets/manual.css +7 -2
  46. data/lib/net/ssh/connection/driver.rb +6 -0
  47. data/lib/net/ssh/transport/session.rb +6 -2
  48. data/lib/net/ssh/userauth/services.rb +1 -1
  49. data/lib/net/ssh/version.rb +1 -1
  50. data/test/transport/tc_session.rb +13 -0
  51. metadata +161 -149
  52. data/doc/manual/parts/session_session.txt +0 -14
@@ -0,0 +1,413 @@
1
+ <html>
2
+ <head>
3
+ <title>Net::SSH Manual :: Chapter 4: Executing Commands</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&mdash;</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.0.1</strong><br />
18
+ Manual Last Updated: <strong>2005-06-17 20: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&#8217;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>
74
+ <a href="chapter-3.html">
75
+ Channels
76
+ </a>
77
+
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><strong>
96
+ <a href="chapter-4.html">
97
+ Executing Commands
98
+ </a>
99
+ </strong> <big>&larr;</big>
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-3.html">Previous (3. Channels)</a> |
196
+
197
+ <a href="index.html">Up</a>
198
+
199
+ | <a href="chapter-5.html">Next (5. User Shells)</a>
200
+
201
+ </div></div>
202
+
203
+ <h1>4. Executing Commands</h1>
204
+
205
+
206
+
207
+ <h2>
208
+ <a name="s1"></a>
209
+ 4.1. Using Channels
210
+ </h2>
211
+
212
+
213
+
214
+ <div class="section">
215
+ <p>To run multiple processes in parallel, you can access the channel <span class="caps">API</span> directly, setting up multiple channels and callbacks in order to process the output from the channel.</p>
216
+
217
+
218
+ <p>Suppose, for example, that you wanted to run multiple &#8220;tail&#8221; commands on various logs on the remote machine, combining them all into the output on the client. Something like the following would suffice:</p>
219
+
220
+
221
+ <div class='figure'>
222
+ <span class='caption'>Running "tail" on multiple remote files [ruby]</span>
223
+ <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 />12<br />13<br />14<br />15<br />16<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="keyword">def </span><span class="method">do_tail</span><span class="punct">(</span> <span class="ident">session</span><span class="punct">,</span> <span class="ident">file</span> <span class="punct">)</span>
224
+ <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>
225
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_data</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">ch</span><span class="punct">,</span> <span class="ident">data</span><span class="punct">|</span>
226
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">[<span class="expr">#{file}</span>] -&gt; <span class="expr">#{data}</span></span><span class="punct">&quot;</span>
227
+ <span class="keyword">end</span>
228
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">exec</span> <span class="punct">&quot;</span><span class="string">tail -f <span class="expr">#{file}</span></span><span class="punct">&quot;</span>
229
+ <span class="keyword">end</span>
230
+ <span class="keyword">end</span>
231
+
232
+ <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>
233
+ <span class="ident">do_tail</span> <span class="ident">session</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">/var/log/messages</span><span class="punct">&quot;</span>
234
+ <span class="ident">do_tail</span> <span class="ident">session</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">/var/log/XFree86.0.log</span><span class="punct">&quot;</span>
235
+ <span class="ident">do_tail</span> <span class="ident">session</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">/var/log/tomcat/catalina.log</span><span class="punct">&quot;</span>
236
+ <span class="ident">do_tail</span> <span class="ident">session</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">/var/log/mysql/mysql.err</span><span class="punct">&quot;</span>
237
+ <span class="ident">session</span><span class="punct">.</span><span class="ident">loop</span>
238
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
239
+
240
+
241
+ <p>As you can see, four different logs are tailed on four separate channels. Each channel registers an <code>on_data</code> callback (which simply displays the data it recieves, together with the name of the log file it came from). The <code>exec</code> method of the channel is then invoked, which simply sends the request to execute the process to the server, and then returns.</p>
242
+
243
+
244
+ <p>The <code>loop</code> method then blocks while packets and processed and callbacks are invoked, completing the program.</p>
245
+
246
+
247
+ <p>This approach works fine for processing data coming from the server, and with a little work and coordination can work well for sending data <em>to</em> the server as well, by calling the <code>send_data</code> method of the channel at the appropriate times. However, it requires a bit of forethought, since you have to come up with a simple state machine to manage most interactive sessions, and many times that&#8217;s more effort than it is worth.</p>
248
+ </div>
249
+
250
+
251
+
252
+ <h2>
253
+ <a name="s2"></a>
254
+ 4.2. Using #process.open
255
+ </h2>
256
+
257
+
258
+
259
+ <div class="section">
260
+ <p>The <code>#process.open</code> interface provides a simpler way to manage interactive sessions. It still works via callbacks, and it still requires a kind of state machine in order to process input, but it does simplify things a little bit.</p>
261
+
262
+
263
+ <p>Just open an <span class="caps">SSH</span> session. The <code>#process</code> service of the session manages access to convenience methods for handling and communicating with remote processes. In particular the <code>#open</code> method of the <code>#process</code> service allows you to constuct callbacks for dealing with remote processes, more conveniently than using channels directly.</p>
264
+
265
+
266
+ <p>Consider the &#8220;bc&#8221; command. It is a command-line calculator that accepts expressions on <code>stdin</code> and writes the results to <code>stdout</code>. When it encounters the word <code>quit</code> on the input, it exits. Sounds like a great way to demonstrate the <code>process</code> service&#8230;</p>
267
+
268
+
269
+ <div class='figure'>
270
+ <span class='caption'>Using #process.open [ruby]</span>
271
+ <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 />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br />21<br />22<br />23<br />24<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>
272
+
273
+ <span class="ident">session</span><span class="punct">.</span><span class="ident">process</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span> <span class="punct">&quot;</span><span class="string">bc</span><span class="punct">&quot;</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">bc</span><span class="punct">|</span>
274
+ <span class="ident">dialog</span> <span class="punct">=</span> <span class="punct">[</span> <span class="punct">&quot;</span><span class="string">5+5</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">7*12</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">sqrt(2.000000)</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">quit</span><span class="punct">&quot;</span> <span class="punct">]</span>
275
+
276
+ <span class="ident">bc</span><span class="punct">.</span><span class="ident">on_success</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">p</span><span class="punct">|</span>
277
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">requesting result of <span class="expr">#{dialog.first}</span></span><span class="punct">&quot;</span>
278
+ <span class="ident">p</span><span class="punct">.</span><span class="ident">puts</span> <span class="ident">dialog</span><span class="punct">.</span><span class="ident">shift</span>
279
+ <span class="keyword">end</span>
280
+
281
+ <span class="ident">bc</span><span class="punct">.</span><span class="ident">on_stdout</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">p</span><span class="punct">,</span><span class="ident">data</span><span class="punct">|</span>
282
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">--&gt; <span class="expr">#{data}</span></span><span class="punct">&quot;</span>
283
+ <span class="keyword">unless</span> <span class="ident">dialog</span><span class="punct">.</span><span class="ident">empty?</span>
284
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">requesting result of <span class="expr">#{dialog.first}</span></span><span class="punct">&quot;</span>
285
+ <span class="ident">p</span><span class="punct">.</span><span class="ident">puts</span> <span class="ident">dialog</span><span class="punct">.</span><span class="ident">shift</span>
286
+ <span class="keyword">end</span>
287
+ <span class="keyword">end</span>
288
+
289
+ <span class="ident">bc</span><span class="punct">.</span><span class="ident">on_exit</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">p</span><span class="punct">,</span> <span class="ident">status</span><span class="punct">|</span>
290
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">process finished with exit status: <span class="expr">#{status}</span></span><span class="punct">&quot;</span>
291
+ <span class="keyword">end</span>
292
+ <span class="keyword">end</span>
293
+
294
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
295
+
296
+
297
+ <p>Notice the progression. First, the session itself is started. Then, while the session is active, the process is invoked (via <code>#process.open</code>). After we have a handle to the process (which is yielded to the block, in this case), we set up the callbacks on the process. These are reminiscent of, but different from, the callbacks that we set up on the channel itself in the previous section.</p>
298
+
299
+
300
+ <p>The following callbacks are defined for a process handle:</p>
301
+
302
+
303
+ <table class="list">
304
+ <tr>
305
+ <th>Name </th>
306
+ <th>Description </th>
307
+ </tr>
308
+ <tr>
309
+ <td style="vertical-align:top;text-align:center;"><code>on_exit</code> </td>
310
+ <td> This callback is invoked when the process terminates normally. The block should accept two parameters: the process handle itself, and the exit status of the process.</td>
311
+ </tr>
312
+ <tr>
313
+ <td style="vertical-align:top;text-align:center;"><code>on_failure</code> </td>
314
+ <td> This callback is invoked when the process could not be invoked. It should take two parameters: the process handle itself, and a status string (which currently always <code>nil</code>).</td>
315
+ </tr>
316
+ <tr>
317
+ <td style="vertical-align:top;text-align:center;"><code>on_success</code> </td>
318
+ <td> This callback is invoked after the process has been successfully started. The callback should take a single parameter: the process handle itself.</td>
319
+ </tr>
320
+ <tr>
321
+ <td style="vertical-align:top;text-align:center;"><code>on_stderr</code> </td>
322
+ <td> This callback is invoked when data is received from the process&#8217;s <code>stderr</code> stream. The callback should have two parameters: the process handle, and the data.</td>
323
+ </tr>
324
+ <tr>
325
+ <td style="vertical-align:top;text-align:center;"><code>on_stdout</code> </td>
326
+ <td> This callback is invoked when data is received from the process&#8217;s <code>stdout</code> stream. The callback should have two parameters: the process handle, and the data.</td>
327
+ </tr>
328
+ </table>
329
+
330
+
331
+
332
+
333
+ <p>Sending data to the process is as simple as calling <code>puts</code> on the process handle. If you don&#8217;t want a newline appended to your data, use <code>write</code> instead.</p>
334
+
335
+
336
+ <p>Notice that, when sending a block to <code>#process.open</code>, you do not have to explicitly invoke <code>session.loop</code>. It is implicitly called at the end of the block. If you ever want to set up multiple processes to run in parallel, simply use <code>#process.open</code> without a block. The process handle will be returned, and you will be required to execute <code>session.loop</code> manually.</p>
337
+
338
+
339
+ <p>For more information on the <code>#process.open</code> service, see the <span class="caps">API</span> documentation for <code>Net::SSH::Service::Process::Open</code>.</p>
340
+ </div>
341
+
342
+
343
+
344
+ <h2>
345
+ <a name="s3"></a>
346
+ 4.3. Using #process.popen3
347
+ </h2>
348
+
349
+
350
+
351
+ <div class="section">
352
+ <p>The last approach to interacting with remote processes is the <code>#popen3</code> method of <code>#process</code> service. It is a <em>synchronous</em> approach, meaning that each method call <em>may</em> (potentially) block until data is received; you can&#8217;t be using other features of the Net::SSH package while using it, but you don&#8217;t have to mess with callbacks.</p>
353
+
354
+
355
+ <p>If you are familiar with the &#8220;popen3&#8221; Ruby module, this will seem familiar. It&#8217;s not a perfect clone of the &#8220;popen3&#8221; module&#8217;s functionality, but it&#8217;s close. What you do is you specify the process to invoke, and then you get three pseudo-IO objects back: the process&#8217;s input stream, it&#8217;s output stream, and it&#8217;s error stream. You can write to the input stream to send data to the process, or read from the output and error streams. Reading from the output or error streams will block until data is available, which makes it very convenient for interacting with a single remote process.</p>
356
+
357
+
358
+ <p>Here&#8217;s the previous &#8220;bc&#8221; example, rewritten to use <code>#popen3</code>:</p>
359
+
360
+
361
+ <div class='figure'>
362
+ <span class='caption'>Using #process.popen3 [ruby]</span>
363
+ <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 />12<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>
364
+
365
+ <span class="ident">input</span><span class="punct">,</span> <span class="ident">output</span><span class="punct">,</span> <span class="ident">error</span> <span class="punct">=</span> <span class="ident">session</span><span class="punct">.</span><span class="ident">process</span><span class="punct">.</span><span class="ident">popen3</span><span class="punct">(</span> <span class="punct">&quot;</span><span class="string">bc</span><span class="punct">&quot;</span> <span class="punct">)</span>
366
+
367
+ <span class="punct">[</span> <span class="punct">&quot;</span><span class="string">5+5</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">7*12</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">sqrt(2.000000)</span><span class="punct">&quot;</span> <span class="punct">].</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">formula</span><span class="punct">|</span>
368
+ <span class="ident">input</span><span class="punct">.</span><span class="ident">puts</span> <span class="ident">formula</span>
369
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"><span class="expr">#{formula}</span>=<span class="expr">#{output.read}</span></span><span class="punct">&quot;</span>
370
+ <span class="keyword">end</span>
371
+
372
+ <span class="ident">input</span><span class="punct">.</span><span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">quit</span><span class="punct">&quot;</span>
373
+
374
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
375
+
376
+
377
+ <p>Much more concise, isn&#8217;t it? One caveat, though: there is no way to kill the process (unless the process can terminate itself, such as through the use of issuing bc&#8217;s &#8220;quit&#8221; command as used above) without closing the session. To remedy this, there is also a block version of popen3 that provides an explicit scope for the three data streams:</p>
378
+
379
+
380
+ <div class='figure'>
381
+ <span class='caption'>Transactional form of #process.popen3 [ruby]</span>
382
+ <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>
383
+ <span class="ident">session</span><span class="punct">.</span><span class="ident">process</span><span class="punct">.</span><span class="ident">popen3</span><span class="punct">(</span> <span class="punct">&quot;</span><span class="string">bc</span><span class="punct">&quot;</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">input</span><span class="punct">,</span> <span class="ident">output</span><span class="punct">,</span> <span class="ident">error</span><span class="punct">|</span>
384
+ <span class="punct">[</span> <span class="punct">&quot;</span><span class="string">5+5</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">7*12</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">sqrt(2.000000)</span><span class="punct">&quot;</span> <span class="punct">].</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">formula</span><span class="punct">|</span>
385
+ <span class="ident">input</span><span class="punct">.</span><span class="ident">puts</span> <span class="ident">formula</span>
386
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"><span class="expr">#{formula}</span>=<span class="expr">#{output.read}</span></span><span class="punct">&quot;</span>
387
+ <span class="keyword">end</span>
388
+ <span class="keyword">end</span>
389
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
390
+
391
+
392
+ <p>The three streams will be closed and process explicitly terminated when the block ends.</p>
393
+ </div>
394
+
395
+
396
+
397
+ <div class="bottom"><div class="prevnext">
398
+
399
+ <a href="chapter-3.html">Previous (3. Channels)</a> |
400
+
401
+ <a href="index.html">Up</a>
402
+
403
+ | <a href="chapter-5.html">Next (5. User Shells)</a>
404
+
405
+ </div></div>
406
+
407
+
408
+ </div>
409
+
410
+ </td></tr>
411
+ </table>
412
+ </body>
413
+ </html>
@@ -0,0 +1,525 @@
1
+ <html>
2
+ <head>
3
+ <title>Net::SSH Manual :: Chapter 5: User Shells</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&mdash;</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.0.1</strong><br />
18
+ Manual Last Updated: <strong>2005-06-17 20: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&#8217;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>
74
+ <a href="chapter-3.html">
75
+ Channels
76
+ </a>
77
+
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><strong>
112
+ <a href="chapter-5.html">
113
+ User Shells
114
+ </a>
115
+ </strong> <big>&larr;</big>
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-4.html">Previous (4. Executing Commands)</a> |
196
+
197
+ <a href="index.html">Up</a>
198
+
199
+ | <a href="chapter-6.html">Next (6. Port Forwarding)</a>
200
+
201
+ </div></div>
202
+
203
+ <h1>5. User Shells</h1>
204
+
205
+
206
+
207
+ <h2>
208
+ <a name="s1"></a>
209
+ 5.1. Introduction
210
+ </h2>
211
+
212
+
213
+
214
+ <div class="section">
215
+ <p>A user&#8217;s <em>shell</em> is the environment in which commands are executed on a remote machine. There are a variety of different shells, including <a href="http://www.gnu.org/software/bash/bash.html">bash</a>, csh, tcsh, <a href="http://www.kornshell.com/">ksh</a>, and many others.</p>
216
+
217
+
218
+ <p>A shell may be executed like any other program, and when run, it (more-or-less) enters a read-execute-prompt cycle in which the user may interactively run commands.</p>
219
+
220
+
221
+ <p><span class="caps">SSH</span> has special support for shells, allowing you to start a shell on a channel and have all subsequent data sent to that channel interpreted as the user&#8217;s input to the shell. Also, <span class="caps">SSH</span> supports pty&#8217;s (<em>pseudo-tty</em>&#8217;s, or terminals), which allow the shell to act as if it were running locally on the users own machine.</p>
222
+
223
+
224
+ <p>Because a shell is just a program, you can always start a shell simply by executing it (as described in the previous chapter). However, you can also take advantage of <span class="caps">SSH</span>&#8217;s builtin shell support to execute the user&#8217;s preferred shell. This chapter will discuss this approach.</p>
225
+ </div>
226
+
227
+
228
+
229
+ <h2>
230
+ <a name="s2"></a>
231
+ 5.2. Using Channels
232
+ </h2>
233
+
234
+
235
+
236
+ <div class="section">
237
+ <p>At the lowest level, starting a shell is a matter of sending a &#8220;shell&#8221; request over a channel.</p>
238
+
239
+
240
+ <div class='figure'>
241
+ <span class='caption'>Sending a shell request [ruby]</span>
242
+ <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 />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br />21<br />22<br />23<br />24<br />25<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="ident">host</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
243
+
244
+ <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>
245
+
246
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_success</span> <span class="keyword">do</span>
247
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">shell was started successfully!</span><span class="punct">&quot;</span>
248
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">send_data</span> <span class="punct">&quot;</span><span class="string">exit<span class="escape">\n</span></span><span class="punct">&quot;</span> <span class="comment"># tell the shell to exit</span>
249
+ <span class="keyword">end</span>
250
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_failure</span> <span class="keyword">do</span>
251
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">shell could not be started!</span><span class="punct">&quot;</span>
252
+ <span class="keyword">end</span>
253
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_data</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">ch</span><span class="punct">,</span><span class="ident">data</span><span class="punct">|</span>
254
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">recieved <span class="expr">#{data}</span> from shell</span><span class="punct">&quot;</span>
255
+ <span class="keyword">end</span>
256
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_close</span> <span class="keyword">do</span>
257
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">shell terminated</span><span class="punct">&quot;</span>
258
+ <span class="keyword">end</span>
259
+
260
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">send_request</span> <span class="punct">&quot;</span><span class="string">shell</span><span class="punct">&quot;,</span> <span class="constant">nil</span><span class="punct">,</span> <span class="constant">true</span>
261
+
262
+ <span class="keyword">end</span>
263
+
264
+ <span class="ident">session</span><span class="punct">.</span><span class="ident">loop</span>
265
+
266
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
267
+
268
+
269
+ <p>The <code>#send_request</code> method accepts three parameters&#8212;the name of the request (in this case, &#8220;shell&#8221;), any additional data to send with the request (none, in this case), and whether or not you want the server to reply with the success or failure of the request. In general, it is a good idea to ask for the server to reply, so that you know when you can start sending data to the shell.</p>
270
+
271
+
272
+ <p>If you want to open a pty before starting the shell, you can use the #request_pty method of the channel:</p>
273
+
274
+
275
+ <div class='figure'>
276
+ <span class='caption'>Opening a pty on a channel [ruby]</span>
277
+ <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 />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br />21<br />22<br />23<br />24<br />25<br />26<br />27<br />28<br />29<br />30<br />31<br />32<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="ident">host</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
278
+
279
+ <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>
280
+
281
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_success</span> <span class="keyword">do</span>
282
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">pty was requested successfully!</span><span class="punct">&quot;</span>
283
+
284
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_success</span> <span class="keyword">do</span>
285
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">shell was started successfully!</span><span class="punct">&quot;</span>
286
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">send_data</span> <span class="punct">&quot;</span><span class="string">exit<span class="escape">\n</span></span><span class="punct">&quot;</span> <span class="comment"># tell the shell to exit</span>
287
+ <span class="keyword">end</span>
288
+
289
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">send_request</span> <span class="punct">&quot;</span><span class="string">shell</span><span class="punct">&quot;,</span> <span class="constant">nil</span><span class="punct">,</span> <span class="constant">true</span>
290
+ <span class="keyword">end</span>
291
+
292
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_failure</span> <span class="keyword">do</span>
293
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">shell could not be started!</span><span class="punct">&quot;</span>
294
+ <span class="keyword">end</span>
295
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_data</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">ch</span><span class="punct">,</span><span class="ident">data</span><span class="punct">|</span>
296
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">recieved <span class="expr">#{data}</span> from shell</span><span class="punct">&quot;</span>
297
+ <span class="keyword">end</span>
298
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">on_close</span> <span class="keyword">do</span>
299
+ <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">shell terminated</span><span class="punct">&quot;</span>
300
+ <span class="keyword">end</span>
301
+
302
+ <span class="ident">channel</span><span class="punct">.</span><span class="ident">request_pty</span> <span class="symbol">:want_reply</span> <span class="punct">=&gt;</span> <span class="constant">true</span>
303
+
304
+ <span class="keyword">end</span>
305
+
306
+ <span class="ident">session</span><span class="punct">.</span><span class="ident">loop</span>
307
+
308
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
309
+
310
+
311
+ <p>First, the pty is requested (with an indicator to the server that it should return a &#8220;success&#8221; or &#8220;failure&#8221; notification). When the pty is successfully opened, the &#8220;on_success&#8221; callback is changed, and the shell is then requested.</p>
312
+
313
+
314
+ <p>It&#8217;s a lot of hoops to jump through, but it gives you the finest-grained control over opening a shell. For most things, though, you can live with less control. For those tasks, there are the <em>shell</em> and <em>sync</em> services.</p>
315
+ </div>
316
+
317
+
318
+
319
+ <h2>
320
+ <a name="s3"></a>
321
+ 5.3. Shell Service
322
+ </h2>
323
+
324
+
325
+
326
+ <div class="section">
327
+ <p>To make interacting with shells, simpler, version 0.9 of Net::SSH introduced the <em>shell service</em>. This allows you to open a shell (with or without a pty), send a series of commands to the shell, and then wait for the output from the shell.</p>
328
+
329
+
330
+ <div class='figure'>
331
+ <span class='caption'>Using the shell service [ruby]</span>
332
+ <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 />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br />21<br />22<br />23<br />24<br />25<br />26<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">localhost</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>
333
+
334
+ <span class="ident">shell</span> <span class="punct">=</span> <span class="ident">session</span><span class="punct">.</span><span class="ident">shell</span><span class="punct">.</span><span class="ident">open</span>
335
+
336
+ <span class="comment"># script what we want to do</span>
337
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">pwd</span>
338
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">cd</span> <span class="punct">&quot;</span><span class="string">/</span><span class="punct">&quot;</span>
339
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">pwd</span>
340
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">test</span> <span class="punct">&quot;</span><span class="string">-e foo</span><span class="punct">&quot;</span>
341
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">cd</span> <span class="punct">&quot;</span><span class="string">/really/bogus/directory</span><span class="punct">&quot;</span>
342
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">send_data</span> <span class="punct">&quot;</span><span class="string">/sbin/ifconfig<span class="escape">\n</span></span><span class="punct">&quot;</span>
343
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">pwd</span>
344
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">ruby</span> <span class="punct">&quot;</span><span class="string">-v</span><span class="punct">&quot;</span>
345
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">cd</span> <span class="punct">&quot;</span><span class="string">/usr/lib</span><span class="punct">&quot;</span>
346
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">pwd</span>
347
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">exit</span>
348
+
349
+ <span class="comment"># give the above commands sufficient time to terminate</span>
350
+ <span class="ident">sleep</span> <span class="number">0.5</span>
351
+
352
+ <span class="comment"># display the output</span>
353
+ <span class="global">$stdout</span><span class="punct">.</span><span class="ident">print</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">stdout</span> <span class="keyword">while</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">stdout?</span>
354
+ <span class="global">$stderr</span><span class="punct">.</span><span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">-- stderr: --</span><span class="punct">&quot;</span>
355
+ <span class="global">$stderr</span><span class="punct">.</span><span class="ident">print</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">stderr</span> <span class="keyword">while</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">stderr?</span>
356
+
357
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
358
+
359
+
360
+ <p>Any unrecognized method that is sent to the shell object is interpreted as a command to send to the server. To explicitly send a command, use the <code>#send_data</code> method (but remember to add a newline!). The <code>#send_data</code> method may also be used to send data to any process running in the shell as that process&#8217; <code>stdin</code> stream.</p>
361
+
362
+
363
+ <p>You can also specify that a pty should be allocated for this shell:</p>
364
+
365
+
366
+ <div class='figure'>
367
+ <span class='caption'>Allocating a pty for the shell [ruby]</span>
368
+ <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 /></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">localhost</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>
369
+
370
+ <span class="ident">shell</span> <span class="punct">=</span> <span class="ident">session</span><span class="punct">.</span><span class="ident">shell</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span> <span class="symbol">:pty</span> <span class="punct">=&gt;</span> <span class="constant">true</span> <span class="punct">)</span>
371
+
372
+ <span class="comment"># or</span>
373
+
374
+ <span class="ident">shell</span> <span class="punct">=</span> <span class="ident">session</span><span class="punct">.</span><span class="ident">shell</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span> <span class="symbol">:pty</span> <span class="punct">=&gt;</span> <span class="punct">{</span> <span class="punct">...</span> <span class="punct">}</span> <span class="punct">)</span>
375
+
376
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
377
+
378
+
379
+ <p>If you give a hash for the <code>:pty</code> option, it must be a map of the options that describe the new pty. See the <span class="caps">API</span> documentation for the <code>Channel#request_pty</code> method for more information.</p>
380
+
381
+
382
+ <p>Note that this is still an asynchronous approach. You send all the commands through the pipe and then wait for the output. (And be sure to give sufficient time or the processes to terminate!) This is fine for scripts that you just want to throw at the server, but many times you want a more interactive interface, for executing a command and receiving its output before moving on.</p>
383
+ </div>
384
+
385
+
386
+
387
+ <h2>
388
+ <a name="s4"></a>
389
+ 5.4. SyncShell Service
390
+ </h2>
391
+
392
+
393
+
394
+ <div class="section">
395
+ <p>The SyncShell service allows you to execute commands on the shell and block until they finish. It is not fool-proof&#8212;it has to use some tricks to accomplish this task, and some commands may foul it up. But for most tasks, it works admirably.</p>
396
+
397
+
398
+ <div class='figure'>
399
+ <span class='caption'>Using the SyncShell service [ruby]</span>
400
+ <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 />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br />21<br />22<br />23<br />24<br />25<br />26<br />27<br />28<br />29<br />30<br />31<br />32<br />33<br />34<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">localhost</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>
401
+
402
+ <span class="ident">shell</span> <span class="punct">=</span> <span class="ident">session</span><span class="punct">.</span><span class="ident">shell</span><span class="punct">.</span><span class="ident">sync</span>
403
+
404
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">pwd</span>
405
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">stdout</span>
406
+
407
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">test</span> <span class="punct">&quot;</span><span class="string">-e foo</span><span class="punct">&quot;</span>
408
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">status</span>
409
+
410
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">cd</span> <span class="punct">&quot;</span><span class="string">/really/bogus/directory</span><span class="punct">&quot;</span>
411
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">stderr</span>
412
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">status</span>
413
+
414
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">ruby</span> <span class="punct">&quot;</span><span class="string">-v</span><span class="punct">&quot;</span>
415
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">stdout</span>
416
+
417
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">cd</span> <span class="punct">&quot;</span><span class="string">/usr/lib</span><span class="punct">&quot;</span>
418
+
419
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">ls</span> <span class="punct">&quot;</span><span class="string">-l</span><span class="punct">&quot;</span>
420
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">stdout</span>
421
+
422
+ <span class="ident">out</span> <span class="punct">=</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">send_command</span><span class="punct">(</span> <span class="punct">&quot;</span><span class="string">bc</span><span class="punct">&quot;,</span> <span class="punct">&lt;&lt;</span><span class="constant">CMD</span> <span class="punct">)</span><span class="string">
423
+ 5+5
424
+ 10*2
425
+ scale=5
426
+ 3/4
427
+ quit
428
+ </span><span class="constant">CMD</span>
429
+ <span class="ident">p</span> <span class="ident">out</span><span class="punct">.</span><span class="ident">stdout</span>
430
+
431
+ <span class="ident">p</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">exit</span>
432
+
433
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
434
+
435
+
436
+ <p>The result of executing each command is an object that encapsulates the <code>stdout</code> and <code>stderr</code> streams, and the exit status of the command.</p>
437
+
438
+
439
+ <p>To explicitly execute a command, use the <code>#send_command</code> instead of <code>#send_data</code>&#8212;otherwise, the command will be executed asynchronously, which is not what you want. Also, if you pass a second parameter to the <code>#send_command</code> method, it is interpreted as the <code>stdin</code> data to send to the new process.</p>
440
+ </div>
441
+
442
+
443
+
444
+ <h2>
445
+ <a name="s5"></a>
446
+ 5.5. Terminal Clients
447
+ </h2>
448
+
449
+
450
+
451
+ <div class="section">
452
+ <p>Using the shell service and pty&#8217;s, you can now create a simple <span class="caps">SSH</span> terminal client. (You&#8217;ll also want to download and install the <a href="http://arika.org/ruby/termios">ruby-termios</a> library so that your input is not interpreted in a linewise fashion.)</p>
453
+
454
+
455
+ <div class='figure'>
456
+ <span class='caption'>A simple SSH terminal client in Ruby [ruby]</span>
457
+ <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 />12<br />13<br />14<br />15<br />16<br />17<br />18<br />19<br />20<br />21<br />22<br />23<br />24<br />25<br />26<br />27<br />28<br />29<br />30<br />31<br />32<br />33<br />34<br />35<br />36<br />37<br />38<br />39<br />40<br />41<br />42<br />43<br />44<br />45<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="keyword">begin</span>
458
+ <span class="ident">require</span> <span class="punct">'</span><span class="string">termios</span><span class="punct">'</span>
459
+ <span class="keyword">rescue</span> <span class="constant">LoadError</span>
460
+ <span class="keyword">end</span>
461
+
462
+ <span class="keyword">def </span><span class="method">stdin_buffer</span><span class="punct">(</span> <span class="ident">enable</span> <span class="punct">)</span>
463
+ <span class="keyword">return</span> <span class="keyword">unless</span> <span class="keyword">defined?</span><span class="punct">(</span> <span class="constant">Termios</span> <span class="punct">)</span>
464
+ <span class="ident">attr</span> <span class="punct">=</span> <span class="constant">Termios</span><span class="punct">::</span><span class="ident">getattr</span><span class="punct">(</span> <span class="global">$stdin</span> <span class="punct">)</span>
465
+ <span class="keyword">if</span> <span class="ident">enable</span>
466
+ <span class="ident">attr</span><span class="punct">.</span><span class="ident">c_lflag</span> <span class="punct">|=</span> <span class="constant">Termios</span><span class="punct">::</span><span class="constant">ICANON</span> <span class="punct">|</span> <span class="constant">Termios</span><span class="punct">::</span><span class="constant">ECHO</span>
467
+ <span class="keyword">else</span>
468
+ <span class="ident">attr</span><span class="punct">.</span><span class="ident">c_lflag</span> <span class="punct">&amp;=</span> ~<span class="punct">(</span><span class="constant">Termios</span><span class="punct">::</span><span class="constant">ICANON</span><span class="punct">|</span><span class="constant">Termios</span><span class="punct">::</span><span class="constant">ECHO</span><span class="punct">)</span>
469
+ <span class="keyword">end</span>
470
+ <span class="constant">Termios</span><span class="punct">::</span><span class="ident">setattr</span><span class="punct">(</span> <span class="global">$stdin</span><span class="punct">,</span> <span class="constant">Termios</span><span class="punct">::</span><span class="constant">TCSANOW</span><span class="punct">,</span> <span class="ident">attr</span> <span class="punct">)</span>
471
+ <span class="keyword">end</span>
472
+
473
+ <span class="ident">host</span> <span class="punct">=</span> <span class="constant">ARGV</span><span class="punct">.</span><span class="ident">shift</span> <span class="keyword">or</span> <span class="ident">abort</span> <span class="punct">&quot;</span><span class="string">You must specify the [user@]host to connect to</span><span class="punct">&quot;</span>
474
+ <span class="keyword">if</span> <span class="ident">host</span> <span class="punct">=~</span> <span class="punct">/</span><span class="regex">@</span><span class="punct">/</span>
475
+ <span class="ident">user</span><span class="punct">,</span> <span class="ident">host</span> <span class="punct">=</span> <span class="ident">host</span><span class="punct">.</span><span class="ident">match</span><span class="punct">(</span> <span class="punct">/</span><span class="regex">(.*?)@(.*)</span><span class="punct">/</span> <span class="punct">)[</span><span class="number">1</span><span class="punct">,</span><span class="number">2</span><span class="punct">]</span>
476
+ <span class="keyword">else</span>
477
+ <span class="ident">user</span> <span class="punct">=</span> <span class="constant">ENV</span><span class="punct">['</span><span class="string">USER</span><span class="punct">']</span> <span class="punct">||</span> <span class="constant">ENV</span><span class="punct">['</span><span class="string">USER_NAME</span><span class="punct">']</span>
478
+ <span class="keyword">end</span>
479
+
480
+ <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="ident">host</span><span class="punct">,</span> <span class="ident">user</span> <span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
481
+
482
+ <span class="keyword">begin</span>
483
+ <span class="ident">stdin_buffer</span> <span class="constant">false</span>
484
+
485
+ <span class="ident">shell</span> <span class="punct">=</span> <span class="ident">session</span><span class="punct">.</span><span class="ident">shell</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span> <span class="symbol">:pty</span> <span class="punct">=&gt;</span> <span class="constant">true</span> <span class="punct">)</span>
486
+
487
+ <span class="ident">loop</span> <span class="keyword">do</span>
488
+ <span class="keyword">break</span> <span class="keyword">unless</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">open?</span>
489
+ <span class="keyword">if</span> <span class="constant">IO</span><span class="punct">.</span><span class="ident">select</span><span class="punct">([</span><span class="global">$stdin</span><span class="punct">],</span><span class="constant">nil</span><span class="punct">,</span><span class="constant">nil</span><span class="punct">,</span><span class="number">0.01</span><span class="punct">)</span>
490
+ <span class="ident">data</span> <span class="punct">=</span> <span class="global">$stdin</span><span class="punct">.</span><span class="ident">sysread</span><span class="punct">(</span><span class="number">1</span><span class="punct">)</span>
491
+ <span class="ident">shell</span><span class="punct">.</span><span class="ident">send_data</span> <span class="ident">data</span>
492
+ <span class="keyword">end</span>
493
+
494
+ <span class="global">$stdout</span><span class="punct">.</span><span class="ident">print</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">stdout</span> <span class="keyword">while</span> <span class="ident">shell</span><span class="punct">.</span><span class="ident">stdout?</span>
495
+ <span class="global">$stdout</span><span class="punct">.</span><span class="ident">flush</span>
496
+ <span class="keyword">end</span>
497
+ <span class="keyword">ensure</span>
498
+ <span class="ident">stdin_buffer</span> <span class="constant">true</span>
499
+ <span class="keyword">end</span>
500
+
501
+ <span class="keyword">end</span></pre></div></td></tr></table></div></div>
502
+
503
+
504
+ <p>The above code is also available as an example script in the Net::SSH distribution (<code>examples/ssh-client.rb</code>).</p>
505
+ </div>
506
+
507
+
508
+
509
+ <div class="bottom"><div class="prevnext">
510
+
511
+ <a href="chapter-4.html">Previous (4. Executing Commands)</a> |
512
+
513
+ <a href="index.html">Up</a>
514
+
515
+ | <a href="chapter-6.html">Next (6. Port Forwarding)</a>
516
+
517
+ </div></div>
518
+
519
+
520
+ </div>
521
+
522
+ </td></tr>
523
+ </table>
524
+ </body>
525
+ </html>