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.
- data/doc/manual-html/chapter-1.html +388 -0
- data/doc/manual-html/chapter-2.html +544 -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 +237 -0
- data/doc/manual-html/stylesheets/manual.css +270 -0
- data/doc/manual-html/stylesheets/ruby.css +17 -0
- data/doc/manual/manual.rb +2 -2
- data/doc/manual/manual.yml +41 -44
- data/doc/manual/parts/{intro_what_is.txt → 0000.txt} +0 -0
- data/doc/manual/parts/{intro_what_is_not.txt → 0001.txt} +0 -0
- data/doc/manual/parts/{intro_getting.txt → 0002.txt} +7 -6
- data/doc/manual/parts/{intro_license.txt → 0003.txt} +0 -0
- data/doc/manual/parts/{intro_support.txt → 0004.txt} +0 -0
- data/doc/manual/parts/{intro_author.txt → 0005.txt} +1 -1
- data/doc/manual/parts/{session_start.txt → 0006.txt} +11 -11
- data/doc/manual/parts/{session_key.txt → 0007.txt} +6 -6
- data/doc/manual/parts/{session_options.txt → 0008.txt} +2 -3
- data/doc/manual/parts/0009.txt +14 -0
- data/doc/manual/parts/{channels_what_are.txt → 0010.txt} +0 -0
- data/doc/manual/parts/{channels_loop.txt → 0011.txt} +2 -2
- data/doc/manual/parts/{channels_types.txt → 0012.txt} +0 -0
- data/doc/manual/parts/{channels_open.txt → 0013.txt} +2 -2
- data/doc/manual/parts/{channels_callbacks.txt → 0014.txt} +3 -3
- data/doc/manual/parts/{channels_operations.txt → 0015.txt} +1 -2
- data/doc/manual/parts/{exec_channels.txt → 0016.txt} +2 -2
- data/doc/manual/parts/{exec_open.txt → 0017.txt} +3 -3
- data/doc/manual/parts/{exec_popen3.txt → 0018.txt} +5 -5
- data/doc/manual/parts/{shells_intro.txt → 0019.txt} +0 -0
- data/doc/manual/parts/{shells_channels.txt → 0020.txt} +5 -5
- data/doc/manual/parts/{shells_shell.txt → 0021.txt} +6 -6
- data/doc/manual/parts/{shells_sync.txt → 0022.txt} +4 -4
- data/doc/manual/parts/{shells_clients.txt → 0023.txt} +3 -3
- data/doc/manual/parts/{forward_intro.txt → 0024.txt} +2 -2
- data/doc/manual/parts/{forward_local.txt → 0025.txt} +4 -4
- data/doc/manual/parts/{forward_remote.txt → 0026.txt} +6 -5
- data/doc/manual/parts/{forward_direct.txt → 0027.txt} +2 -2
- data/doc/manual/parts/{forward_handlers.txt → 0028.txt} +0 -0
- data/doc/manual/parts/{proxy_intro.txt → 0029.txt} +0 -0
- data/doc/manual/parts/{proxy_http.txt → 0030.txt} +6 -6
- data/doc/manual/parts/{proxy_socks.txt → 0031.txt} +4 -2
- data/doc/manual/stylesheets/manual.css +7 -2
- data/lib/net/ssh/connection/driver.rb +6 -0
- data/lib/net/ssh/transport/session.rb +6 -2
- data/lib/net/ssh/userauth/services.rb +1 -1
- data/lib/net/ssh/version.rb +1 -1
- data/test/transport/tc_session.rb +13 -0
- metadata +161 -149
- data/doc/manual/parts/session_session.txt +0 -14
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>Net::SSH Manual :: Chapter 1: Introduction</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.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><strong>
|
|
34
|
+
<a href="chapter-1.html">
|
|
35
|
+
Introduction
|
|
36
|
+
</a>
|
|
37
|
+
</strong> <big>←</big>
|
|
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>
|
|
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>
|
|
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="index.html">Up</a>
|
|
196
|
+
|
|
197
|
+
| <a href="chapter-2.html">Next (2. Starting a Session)</a>
|
|
198
|
+
|
|
199
|
+
</div></div>
|
|
200
|
+
|
|
201
|
+
<h1>1. Introduction</h1>
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
<h2>
|
|
206
|
+
<a name="s1"></a>
|
|
207
|
+
1.1. What is Net::SSH?
|
|
208
|
+
</h2>
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
<div class="section">
|
|
213
|
+
<p>Net::SSH is a pure-Ruby implementation of the <span class="caps">SSH2</span> client protocol. It supports the following features:</p>
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
<ul>
|
|
217
|
+
<li>User authentication via explicit username/password, or using a public-key/private-key pair.</li>
|
|
218
|
+
<li>Port forwarding, both from the local host to a remote computer via the remote host, and from the remote host to the local host.</li>
|
|
219
|
+
<li>Execute processes on the remote machine, both interactively and non-interactively (“batch”).</li>
|
|
220
|
+
</ul>
|
|
221
|
+
</div>
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
<h2>
|
|
226
|
+
<a name="s2"></a>
|
|
227
|
+
1.2. What isn’t Net::SSH?
|
|
228
|
+
</h2>
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
<div class="section">
|
|
233
|
+
<p>Net::SSH is only a <em>client</em> implementation, not a server. Given sufficient motivation and encouragement from the community, perhaps it will someday include an <span class="caps">SSH</span> server, but as of right now, it does not.</p>
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
<p>Furthermore, it is only an <em>SSH2</em> client. This means that it cannot connect to <span class="caps">SSH</span> servers that only understand the older <span class="caps">SSH1</span> protocol.</p>
|
|
237
|
+
</div>
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
<h2>
|
|
242
|
+
<a name="s3"></a>
|
|
243
|
+
1.3. Getting Net::SSH
|
|
244
|
+
</h2>
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
<div class="section">
|
|
249
|
+
<h3>Prerequisites:</h3>
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
<p>In order to use Net::SSH, you must be using a supported version of Ruby’s OpenSSL module. The version distributed with Ruby 1.8.1 and earlier is not sufficient, and is lacking several features that Net::SSH relies on. If you are using Ruby 1.8.1 (or earlier), you should either upgrade to 1.8.2, or download and install an updated version of the OpenSSL module. You can download a usable snapshot from the <a href="http://rubyforge.org/projects/net-ssh">Net::SSH downloads page</a>.</p>
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
<p>Furthermore, you must make sure that Ruby’s OpenSSL module has been compiled against <em>at least</em> version 0.9.7 of the OpenSSL library. Prior versions lacked functionality that Net::SSH depends on (notably, the ‘padding’ property of ciphers).</p>
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
<p>Optionally, you can install the <a href="http://raa.ruby-lang.org/project/ruby-termios">ruby-termios</a> and <a href="http://raa.ruby-lang.org/project/ruby-password">ruby-password</a> modules. If you do, then the ruby-password module will be used when prompting you for the passphrases needed to load your keys (if your keys have passphrases).</p>
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
<h3>Using <a href="http://rubygems.rubyforge.org">RubyGems</a></h3>
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
<p>If you have <a href="http://rubygems.rubyforge.org">RubyGems</a> installed, installing Net::SSH is simple:</p>
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
<div class='figure'>
|
|
268
|
+
<span class='caption'>Using Rubygems to install Net::SSH [shell]</span>
|
|
269
|
+
<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/shell.css' /><div class='shell'><pre>gem install net-ssh</pre></div></div></div>
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
<p>You still need to make sure you have a working version of Ruby’s OpenSSL module, but other than that, you should be good to go!</p>
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
<h3>Using <a href="http://rpa-base.rubyforge.org">rpa-base</a></h3>
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
<p>If you have <a href="http://rpa-base.rubyforge.org">rpa-base</a> installed:</p>
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
<div class='figure'>
|
|
282
|
+
<span class='caption'>Using RPA to install Net::SSH [shell]</span>
|
|
283
|
+
<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/shell.css' /><div class='shell'><pre>rpa install net-ssh</pre></div></div></div>
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
<p>As with the gem install, you still need to make sure you have a working version of Ruby’s OpenSSL module, but other than that, you should be good to go!</p>
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
<h3>Doing it the hard way</h3>
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
<p>If you don’t have <a href="http://rubygems.rubyforge.org">RubyGems</a> or <a href="http://rpa-base.rubyforge.org">rpa-base</a>, or if you just prefer to install things by hand, you can always go to the <a href="http://rubyforge.org/projects/net-ssh">Net::SSH downloads page</a> and grab the package of your choice: <code>tar.gz</code>, <code>tar.bz2</code>, or <code>zip</code>.</p>
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
<p>Then, unpack the archive and run the <code>setup.rb</code> script:</p>
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
<div class='figure'>
|
|
299
|
+
<span class='caption'>Using setup.rb to install Net::SSH [shell]</span>
|
|
300
|
+
<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/shell.css' /><div class='shell'><pre>ruby setup.rb config
|
|
301
|
+
ruby setup.rb setup
|
|
302
|
+
ruby setup.rb install</pre></div></div></div>
|
|
303
|
+
</div>
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
<h2>
|
|
308
|
+
<a name="s4"></a>
|
|
309
|
+
1.4. License Information
|
|
310
|
+
</h2>
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
<div class="section">
|
|
315
|
+
<p>Net::SSH is made available under either the <span class="caps">BSD</span> license, or the same license Ruby (which, by extension, also allows the <span class="caps">GPL</span> as a permissable license as well). You can view the full text of any of these licenses in the <code>doc</code> subdirectory of the Net::SSH distrubtion. The texts of the <span class="caps">BSD</span> and <span class="caps">GPL</span> licenses are also available online: <a href="http://www.opensource.org/licenses/bsd-license.php">BSD</a> and <a href="http://www.opensource.org/licenses/gpl-license.php">GPL</a>.</p>
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
<p>This manual (in any form, be it source or otherwise) and the scripts and templates used to generate it, are all distributed under the <a href="http://creativecommons.org">Creative Commons</a> <a href="http://creativecommons.org/licenses/by-sa/2.0">Attribution-ShareAlike</a> license.</p>
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
<p>If you desire permission to use either Net::SSH or the manual in a manner incompatible with these licenses, please contact the copyright holder (<a href="mailto:jgb3@email.byu.edu">Jamis Buck</a>) in order to negotiate a more compatible license.</p>
|
|
322
|
+
</div>
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
<h2>
|
|
327
|
+
<a name="s5"></a>
|
|
328
|
+
1.5. Support
|
|
329
|
+
</h2>
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
<div class="section">
|
|
334
|
+
<p>Mailing lists, bug trackers, feature requests, and public forums are all available (courtesty of <a href="http://rubyforge.org">RubyForge</a>) at the <a href="http://rubyforge.org/projects/net-ssh">Net::SSH project page</a>.</p>
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
<h3>Mailing Lists</h3>
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
<table>
|
|
341
|
+
<tr>
|
|
342
|
+
<th><strong>List Name</strong> </th>
|
|
343
|
+
<th>—</th>
|
|
344
|
+
<th><strong>Description</strong> </th>
|
|
345
|
+
</tr>
|
|
346
|
+
<tr>
|
|
347
|
+
<td style="vertical-align:top;text-align:center;"><a href="http://rubyforge.org/pipermail/net-ssh-users">net-ssh-users</a></td>
|
|
348
|
+
<td style="vertical-align:top;text-align:center;"><a href="http://rubyforge.org/mailman/listinfo/net-ssh-users">subscribe / unsubscribe</a></td>
|
|
349
|
+
<td> The Net::SSH users list is devoted to the discussion of and questions about the usage of the Net::SSH module. If you can’t quite figure out how to get a feature of Net::SSH to work, this is the list you would go to in order to ask your questions.</td>
|
|
350
|
+
</tr>
|
|
351
|
+
<tr>
|
|
352
|
+
<td style="vertical-align:top;text-align:center;"><a href="http://rubyforge.org/pipermail/net-ssh-devel">net-ssh-devel</a></td>
|
|
353
|
+
<td style="vertical-align:top;text-align:center;"><a href="http://rubyforge.org/mailman/listinfo/net-ssh-devel">subscribe / unsubscribe</a></td>
|
|
354
|
+
<td> The Net::SSH developers list is devoted to the discussion of Net::SSH’s implementation. If you have created a patch that you would like to discuss, or if you would like to discuss a new feature, this is the list for you.</td>
|
|
355
|
+
</tr>
|
|
356
|
+
</table>
|
|
357
|
+
</div>
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
<h2>
|
|
362
|
+
<a name="s6"></a>
|
|
363
|
+
1.6. About the Author
|
|
364
|
+
</h2>
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
<div class="section">
|
|
369
|
+
<p>Net::SSH was written by <a href="mailto:jamis_buck@byu.edu">Jamis Buck</a>. Feel free to send him compliments, candy, money, praise, or new feature patches—he likes all those things. You can send him questions and suggestions, too, if you really want to. However, for bug reports and general feature requests, please use the trackers on the <a href="http://rubyforge.org/projects/net-ssh">Net::SSH project page</a>.</p>
|
|
370
|
+
</div>
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
<div class="bottom"><div class="prevnext">
|
|
375
|
+
|
|
376
|
+
<a href="index.html">Up</a>
|
|
377
|
+
|
|
378
|
+
| <a href="chapter-2.html">Next (2. Starting a Session)</a>
|
|
379
|
+
|
|
380
|
+
</div></div>
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
</div>
|
|
384
|
+
|
|
385
|
+
</td></tr>
|
|
386
|
+
</table>
|
|
387
|
+
</body>
|
|
388
|
+
</html>
|
|
@@ -0,0 +1,544 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>Net::SSH Manual :: Chapter 2: Starting a Session</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.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’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><strong>
|
|
56
|
+
<a href="chapter-2.html">
|
|
57
|
+
Starting a Session
|
|
58
|
+
</a>
|
|
59
|
+
</strong> <big>←</big>
|
|
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>
|
|
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-1.html">Previous (1. Introduction)</a> |
|
|
196
|
+
|
|
197
|
+
<a href="index.html">Up</a>
|
|
198
|
+
|
|
199
|
+
| <a href="chapter-3.html">Next (3. Channels)</a>
|
|
200
|
+
|
|
201
|
+
</div></div>
|
|
202
|
+
|
|
203
|
+
<h1>2. Starting a Session</h1>
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
<h2>
|
|
208
|
+
<a name="s1"></a>
|
|
209
|
+
2.1. Using Net::SSH.start
|
|
210
|
+
</h2>
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
<div class="section">
|
|
215
|
+
<p>Before you can do anything with Net::SSH, you need to require the <code>net/ssh</code> module:</p>
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
<div class='figure'>
|
|
219
|
+
<span class='caption'>Requiring Net::SSH [ruby]</span>
|
|
220
|
+
<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">require</span> <span class="punct">'</span><span class="string">net/ssh</span><span class="punct">'</span></pre></div></div></div>
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
<p>Once you have required the <code>net/ssh</code> module, you can begin an <span class="caps">SSH</span> session by calling <code>Net::SSH.start</code>. This may be used in one of two ways. If called without a block, it will return a reference to the new session as an instance of a <code>Net::SSH::Session</code>. Used this way, you must explicitly close the session when you are finished with it.</p>
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
<div class='figure'>
|
|
227
|
+
<span class='caption'>Opening an SSH session [ruby]</span>
|
|
228
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<br /></td><td width='100%'><link rel='stylesheet' type='text/css' href='stylesheets/ruby.css' /><div class='ruby'><pre><span class="ident">session</span> <span class="punct">=</span> <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="string">user</span><span class="punct">',</span> <span class="punct">'</span><span class="string">passwd</span><span class="punct">'</span> <span class="punct">)</span>
|
|
229
|
+
<span class="punct">...</span>
|
|
230
|
+
<span class="ident">session</span><span class="punct">.</span><span class="ident">close</span></pre></div></td></tr></table></div></div>
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
<p>The other approach involves attaching a block to the start method. When used this way, the new session is passed to the block, and the session is automatically closed when the block exits.</p>
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
<div class='figure'>
|
|
237
|
+
<span class='caption'>Opening a transactional SSH session [ruby]</span>
|
|
238
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<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="string">user</span><span class="punct">',</span> <span class="punct">'</span><span class="string">passwd</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>
|
|
239
|
+
<span class="punct">...</span>
|
|
240
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
<p>If you need to specify a different port on the host to connect to (the default is 22), you can specify it immediately after the <code>host</code> parameter, like so:</p>
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
<div class='figure'>
|
|
247
|
+
<span class='caption'>Specifying the SSH port [ruby]</span>
|
|
248
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<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="number">1234</span><span class="punct">,</span> <span class="punct">'</span><span class="string">user</span><span class="punct">',</span> <span class="punct">'</span><span class="string">passwd</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="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
<h3>Using Keyword Arguments</h3>
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
<p>Some people prefer using keyword arguments for functions with more than a couple of parameters. The <code>start</code> method supports this approach as well, although the <code>host</code> parameter is always positional and always comes first.</p>
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
<div class='figure'>
|
|
260
|
+
<span class='caption'>Using keyword arguments [ruby]</span>
|
|
261
|
+
<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 /></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>
|
|
262
|
+
<span class="symbol">:password</span><span class="punct">=>'</span><span class="string">passwd</span><span class="punct">',</span>
|
|
263
|
+
<span class="symbol">:port</span><span class="punct">=></span><span class="number">1234</span><span class="punct">,</span>
|
|
264
|
+
<span class="symbol">:username</span><span class="punct">=>'</span><span class="string">user</span><span class="punct">',</span>
|
|
265
|
+
<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>
|
|
266
|
+
<span class="punct">...</span>
|
|
267
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
<p>(More about the “<code>...</code>” stuff, later.)</p>
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
<h3>Failed Authentication</h3>
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
<p>If the username and/or password given to <code>start</code> are incorrect, authentication will fail. If authentication fails, a <code>Net::SSH::AuthenticationFailed</code> exception will be raised.</p>
|
|
277
|
+
</div>
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
<h2>
|
|
282
|
+
<a name="s2"></a>
|
|
283
|
+
2.2. Using a Public/Private Key
|
|
284
|
+
</h2>
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
<div class="section">
|
|
289
|
+
<p>Just as with the <a href="http://www.openssh.org">OpenSSH</a> version of the <code>ssh</code> utilities, Net::SSH supports authentication using public/private keys.</p>
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
<h3>I don’t know what public/private keys are… Explain, please?</h3>
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
<p>Public key/private key encryption is just one way of hiding information from prying eyes. The idea is that you have two tokens: a <em>public key</em>, and a <em>private key</em>. The private key is yours alone—you never let <em>anyone</em> else see it. The <em>public key</em>, on the other hand, is distributable. You give it to anyone that you want to be able to communicate with you securely.</p>
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
<p>The remote party uses your public key to encrypt information. Anything encrypted with your public key may only be decrypted with the corresponding private key, and since you have the only copy of that, you can rest easily knowing that no one can easily intercept your communications!</p>
|
|
299
|
+
|
|
300
|
+
|
|
301
|
+
<p>Net::SSH allows you to define a private key, which it will then attempt to use during authentication with the remote server. If the remote server has a copy of the corresponding public key, you will be able to log into that remote server without having to specify a password. Not only is this convenient, but for Ruby scripts, it is much more secure, since you don’t have to hard-code your password in your script.</p>
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
<h3>Setting up public/private keys</h3>
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
<p>Net::SSH, by default, will use the private keys that you have set up for use with ssh. These keys are called “id_dsa” and “id_rsa”, and are located under your home directory, either in a ”.ssh” subdirectory, or a ”.ssh2” subdirectory.</p>
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
<p>The “id_dsa” key is the preferred key (since it uses the stronger <span class="caps">DSA</span> encryption), but both <span class="caps">DSA</span> and <span class="caps">RSA</span> are supported.</p>
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
<p>To create these keys, you can use the “ssh-keygen” utility from <a href="http://www.openssh.org">OpenSSH</a>. Alternatively, if you have the Net::SSH::Utilities package installed, you can use the “rb-keygen” utility (which is a pure-Ruby implementation of most of the functionality of ssh-keygen).</p>
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
<div class='figure'>
|
|
317
|
+
<span class='caption'>Generating an SSH key [shell]</span>
|
|
318
|
+
<div class='body'><link rel='stylesheet' type='text/css' href='stylesheets/shell.css' /><div class='shell'><pre>ssh-keygen -t dsa</pre></div></div></div>
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
<p>(If you would rather use an <span class="caps">RSA</span> key, replace “dsa” with “rsa” in the command given above.)</p>
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
<p>Accept all the defaults when prompted. You will also be asked for a passphrase. This passphrase is an additional level of protection, which prevents anyone from being able to use your private key without knowing the passphrase. Unfortunately, it also means that you have to enter the passphrase every time you use your key. It is up to you what price you want to pay for security, but if you <em>can</em> leave the passphrase blank. In this case, anyone that has a copy of your private key can use it, but it’s a little more convenient to deal with.</p>
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
<p>Once you create your keys, you then need to set up your account on each remote server so that it knows about your public key. To do this, log into the remote server and edit (or create) the file (in your home directory) ”.ssh/authorized_keys”. Just copy the contents of your public key (in your local machine’s home directory, called ”.ssh/id_dsa.pub” or ”.ssh/id_rsa.pub”) into the “authorized_keys” file on a line of its own. Then save the file and logout. Everything <em>should</em> now be set up.</p>
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
<p>(Note: if you have an <span class="caps">SSH</span> client installed, it will typically have its own key generation utility. You can use that instead, if you prefer.)</p>
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
<h3>Connecting using public/private keys</h3>
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
<p>Public/private keys are always tried before the explicit password authentication, even if you provide a password. Thus, if you <em>only</em> want to use public/private key authentication, simply remove the password from the argument list. If you can successfully obtain a session handle, then your keys are set up correctly!</p>
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
<div class='figure'>
|
|
340
|
+
<span class='caption'>SSH authentication using keys [ruby]</span>
|
|
341
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<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="string">user</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>
|
|
342
|
+
<span class="punct">...</span>
|
|
343
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
<p>Furthermore, if your <code>USER</code> environment variable is set to the username that you want to log into the remote machine as, you can even leave the <code>username</code> parameter off:</p>
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
<div class='figure'>
|
|
350
|
+
<span class='caption'>Authentication with an implicit user name [ruby]</span>
|
|
351
|
+
<div class='body'><table border='0' cellpadding='0' cellspacing='0'><tr><td class='lineno'>1<br />2<br />3<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>
|
|
352
|
+
<span class="punct">...</span>
|
|
353
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
<h3>Using keys with passphrases</h3>
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
<p>When you use a private key that was created with a passphrase, you will be prompted to enter the passphrase when the key is loaded. This may make such a key inappropriate for use in automated environments, but it is certainly more secure than the use of unprotected private keys.</p>
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
<p>If you have the <a href="http://raa.ruby-lang.org/project/ruby-termios">ruby-termios</a> and <a href="http://raa.ruby-lang.org/project/ruby-password">ruby-password</a> modules installed, the ruby-password module will be used when prompting for passphrases. Otherwise, a generic message (courtesy of the OpenSSL library) will be presented, which will not be very informative.</p>
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
<h3>Using an <span class="caps">SSH</span> agent</h3>
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
<p>Most <span class="caps">SSH</span> clients come with what is called an <em>agent</em>. This is a program that is continually running, and which keeps track of all of a user’s keys. When an <span class="caps">SSH</span> client needs to perform an operation using one of the user’s keys, it requests the operation via the agent, rather than performing the operation itself directly with a key.</p>
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
<p>The benefit of this is what is known as <em>single sign-on</em>. If any of your keys have a passphrase, this allows you to enter the passphrase <em>once</em> (when the key is loaded by the agent), and then any <span class="caps">SSH</span> program you use will never prompt you for that passphrase again.</p>
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
<p>Net::SSH includes support for interfacing with an <span class="caps">SSH</span> agent. This includes support for the <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/" title="pageant">PuTTY agent</a> on Windows systems.</p>
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
<p>On Unixish systems, you allow your Net::SSH programs to interface with a running agent by making sure that the <code>SSH_AGENT_SOCK</code> environment variable is set to the location of the Unix domain socket that the agent is listening to. Also, make sure you have added all of your keys to the agent (typically by running the <code>ssh-add</code> utility.</p>
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
<p>On Windows, the pageant process will be detected automatically, if it is running.</p>
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
<p>A future version of Net::SSH may include it’s own agent implementation as well, to make using an agent on a variety of platforms simpler.</p>
|
|
384
|
+
</div>
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
<h2>
|
|
389
|
+
<a name="s3"></a>
|
|
390
|
+
2.3. Options
|
|
391
|
+
</h2>
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
<div class="section">
|
|
396
|
+
<p>There are various additional options that you can specify when connecting. These options allow you to specify such things as the cipher algorithm to use, whether or not the data stream will be compressed, or explicit paths to the private keys to use.</p>
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
<p>Options are specified as a hash in the last parameter to the <code>start</code> method. If using the keyword parameters version of the <code>start</code> method, the options hash is whatever is left after processing the <code>:username</code>, <code>:password</code>, and <code>:port</code> options.</p>
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
<p>The complete list of available options, and their valid values, is given in the following table.</p>
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
<table class="list">
|
|
406
|
+
<tr>
|
|
407
|
+
<th>Option </th>
|
|
408
|
+
<th>Description </th>
|
|
409
|
+
</tr>
|
|
410
|
+
<tr>
|
|
411
|
+
<td style="vertical-align:top;text-align:center;"><code>:auth_methods</code> </td>
|
|
412
|
+
<td> This is the list of authorization methods to try. It defaults to “publickey”, “hostbased”, “password”, and “keyboard-interactive”. (These are also the only authorization methods that are supported.) If you want them to be tried in a different order, or if you don’t want certain methods to be used, you can specify your own list via this option.</td>
|
|
413
|
+
</tr>
|
|
414
|
+
<tr>
|
|
415
|
+
<td style="vertical-align:top;text-align:center;"><code>:compression</code> </td>
|
|
416
|
+
<td> The compression algorithm to use when compressing the data stream. Valid values are <code>none</code> and <code>zlib</code>. The default is <code>none</code>.</td>
|
|
417
|
+
</tr>
|
|
418
|
+
<tr>
|
|
419
|
+
<td style="vertical-align:top;text-align:center;"><code>:compression_level</code> </td>
|
|
420
|
+
<td> This is only used when the compression algorithm is <code>zlib</code>. It is an integer value from 0 to 9, representing the quality of the compression. <span class="caps">A 0</span> is no compression, and a 9 is most compression. The default is 6.</td>
|
|
421
|
+
</tr>
|
|
422
|
+
<tr>
|
|
423
|
+
<td style="vertical-align:top;text-align:center;"><code>:container</code> </td>
|
|
424
|
+
<td> This is the dependency injection container to use when registering all of the services that Net::SSH uses internally. If unspecified (the default) a new container will be created. This option allows you to reuse a single container for multiple application components.</td>
|
|
425
|
+
</tr>
|
|
426
|
+
<tr>
|
|
427
|
+
<td style="vertical-align:top;text-align:center;"><code>:crypto_backend</code> </td>
|
|
428
|
+
<td> This is the cryptography backend to use. It defaults to <code>:ossl</code>, which specifies the OpenSSL cryptography engine. Currently, this is the only supported backend, but in the future others may be provided, and this is how they would be selected.</td>
|
|
429
|
+
</tr>
|
|
430
|
+
<tr>
|
|
431
|
+
<td style="vertical-align:top;text-align:center;"><code>:encryption</code> </td>
|
|
432
|
+
<td> This is the cipher algorithm to use when sending/receiving data to/from the remote server. It defaults to <code>3des-cbc</code>. Other valid algorithms supported by Net::SSH are <code>aes128-cbc</code>, <code>blowfish-cbc</code>, <code>aes256-cbc</code>, <code>aes192-cbc</code>, <code>idea-cbc</code>, and <code>none</code>. Note that the values you specify here are only <em>suggestions</em>, and if the server you are contacting cannot use your recommended algorithm, a fallback algorithm will be used (typically chosen in the order the algorithms were listed, above). This option may take an array, if you want to specify the order of the fallback algorithms to try, as well. </td>
|
|
433
|
+
</tr>
|
|
434
|
+
<tr>
|
|
435
|
+
<td style="vertical-align:top;text-align:center;"><code>:hmac</code> </td>
|
|
436
|
+
<td> This specifies the “message authentication code” (MAC) algorithm to use to ensure that each packet transmitted and recieved is authentic. This defaults to <code>hmac-md5</code>. Other valid algorithms supported by Net::SSH are <code>hmac-sha1</code>, <code>hmac-md5-96</code>, <code>hmac-md5-sha1</code>, and <code>none</code>. Note that the values you specify here are only <em>suggestions</em>, and if the server you are contacting cannot use your recommended algorithm, a fallback algorithm will be used (typically chosen in the order the algorithms were listed, above). This option may take an array, if you want to specify the order of the fallback algorithms to try, as well. </td>
|
|
437
|
+
</tr>
|
|
438
|
+
<tr>
|
|
439
|
+
<td style="vertical-align:top;text-align:center;"><code>:host_key</code> </td>
|
|
440
|
+
<td> This specifies the host key type that should be used when negotiating keys with the server. This defaults to <code>ssh-dss</code>, but may also be <code>ssh-rsa</code>. As with some other option types, the value you specify is only a recommendation, not a commandment, and if the server cannot honor the key type you specified, a fallback will be chosen from among the other supported types. If you wish to specify the fallback algorithms to try, you may pass an array as the value of this option, which contains (in order) the key types to try. </td>
|
|
441
|
+
</tr>
|
|
442
|
+
<tr>
|
|
443
|
+
<td style="vertical-align:top;text-align:center;"><code>:host_keys</code> </td>
|
|
444
|
+
<td> This is an array of file names that contain the private keys which identify the host your script is running on. These default to <code>/etc/ssh/ssh_host_dsa_key</code> and <code>/etc/ssh/ssh_host_rsa_key</code> (which are both typically only readable by root). These keys are only used in hostbased authentication.</td>
|
|
445
|
+
</tr>
|
|
446
|
+
<tr>
|
|
447
|
+
<td style="vertical-align:top;text-align:center;"><code>:kex</code> </td>
|
|
448
|
+
<td> This specifies the “key-exchange” (KEX) algorithm to use when exchanging keys. Two algorithms are currently supported: <code>diffie-hellman-group-exchange-sha1</code>, and <code>diffie-hellman-group1-sha1</code>. The default is <code>diffie-hellman-group-exchange-sha1</code>.</td>
|
|
449
|
+
</tr>
|
|
450
|
+
<tr>
|
|
451
|
+
<td style="vertical-align:top;text-align:center;"><code>:keys</code> </td>
|
|
452
|
+
<td> This specifies the list of private key files to use <em>instead</em> of the defaults (<code>$HOME/.ssh/id_dsa</code>, <code>$HOME/.ssh2/id_dsa</code>, <code>$HOME/.ssh/id_rsa</code>, and <code>$HOME/.ssh2/id_rsa</code>). The value of this option should be an array of strings.</td>
|
|
453
|
+
</tr>
|
|
454
|
+
<tr>
|
|
455
|
+
<td style="vertical-align:top;text-align:center;"><code>:languages</code> </td>
|
|
456
|
+
<td> This option specifies the preferred language (or languages) that should be used when communicating error messages. It has no effect on Net::SSH, but may cause the server (if it supports your suggested language) to send errors in the language you request. The default is empty.</td>
|
|
457
|
+
</tr>
|
|
458
|
+
<tr>
|
|
459
|
+
<td style="vertical-align:top;text-align:center;"><code>:log</code> </td>
|
|
460
|
+
<td> Specifies either a string or an IO object. If it is a string, it names the file that all log messages should be written to. Otherwise, the messages will be written to the IO object directly. Defaults to <span class="caps">STDERR</span>.</td>
|
|
461
|
+
</tr>
|
|
462
|
+
<tr>
|
|
463
|
+
<td style="vertical-align:top;text-align:center;"><code>:port</code> </td>
|
|
464
|
+
<td> This is the port number that should be used to connect to the remote machine. If you wish to specify the port, you are generally better off specifying it as the second parameter to <code>start</code>, rather than as an option, but you <em>can</em> specify it this way, if you prefer.</td>
|
|
465
|
+
</tr>
|
|
466
|
+
<tr>
|
|
467
|
+
<td style="vertical-align:top;text-align:center;"><code>:registry_options</code> </td>
|
|
468
|
+
<td> If the <code>:container</code> option is not specified, a new container will be created. This option specifies a hash of additional options that may be used to configure the new container (registry). By default, it is empty.</td>
|
|
469
|
+
</tr>
|
|
470
|
+
<tr>
|
|
471
|
+
<td style="vertical-align:top;text-align:center;"><code>:verbose</code> </td>
|
|
472
|
+
<td> Specifies how verbose the logging should be. Valid values are <code>:fatal</code>, <code>:error</code>, <code>:warn</code>, <code>:info</code>, and <code>:debug</code>. Defaults to <code>:warn</code>. <span class="caps">WARNING</span>: selecting <code>:debug</code> will result in <span class="caps">LOTS</span> of output! (Further customization of verbosity can be accomplished by specifying which Net::SSH components should have which logging levels, via the <code>:registry_options</code> option.)</td>
|
|
473
|
+
</tr>
|
|
474
|
+
</table>
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
<p>For example, the following code snippet will connect to the given remote host, and requests that the <code>ssh-rsa</code> host key type be used, with the <code>blowfish-cbc</code> cipher algorithm, and requests that the given private key file be used. Also, the data stream will be compressed.</p>
|
|
480
|
+
|
|
481
|
+
|
|
482
|
+
<div class='figure'>
|
|
483
|
+
<span class='caption'>Specifying options when connecting [ruby]</span>
|
|
484
|
+
<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="ident">require</span> <span class="punct">'</span><span class="string">net/ssh</span><span class="punct">'</span>
|
|
485
|
+
<span class="ident">require</span> <span class="punct">'</span><span class="string">logger</span><span class="punct">'</span>
|
|
486
|
+
|
|
487
|
+
<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>
|
|
488
|
+
<span class="punct">'</span><span class="string">host</span><span class="punct">',</span> <span class="punct">'</span><span class="string">user</span><span class="punct">',</span>
|
|
489
|
+
<span class="symbol">:host_key</span> <span class="punct">=></span> <span class="punct">"</span><span class="string">ssh-rsa</span><span class="punct">",</span>
|
|
490
|
+
<span class="symbol">:encryption</span> <span class="punct">=></span> <span class="punct">"</span><span class="string">blowfish-cbc</span><span class="punct">",</span>
|
|
491
|
+
<span class="symbol">:keys</span> <span class="punct">=></span> <span class="punct">[</span> <span class="punct">"</span><span class="string">/tmp/temporary-key</span><span class="punct">"</span> <span class="punct">],</span>
|
|
492
|
+
<span class="symbol">:compression</span> <span class="punct">=></span> <span class="punct">"</span><span class="string">zlib</span><span class="punct">"</span>
|
|
493
|
+
<span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
|
|
494
|
+
<span class="punct">...</span>
|
|
495
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
496
|
+
</div>
|
|
497
|
+
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
<h2>
|
|
501
|
+
<a name="s4"></a>
|
|
502
|
+
2.4. Using Net::SSH::Session
|
|
503
|
+
</h2>
|
|
504
|
+
|
|
505
|
+
|
|
506
|
+
|
|
507
|
+
<div class="section">
|
|
508
|
+
<p>Alternatively, you can use <code>Net::SSH::Session</code> to start your <span class="caps">SSH</span> sessions. The <code>Net::SSH.start</code> interface described above is simply a convenience for creating a new Session object explicitly.</p>
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
<div class='figure'>
|
|
512
|
+
<span class='caption'>Using Net::SSH::Session [ruby]</span>
|
|
513
|
+
<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="ident">require</span> <span class="punct">'</span><span class="string">net/ssh</span><span class="punct">'</span>
|
|
514
|
+
|
|
515
|
+
<span class="constant">Net</span><span class="punct">::</span><span class="constant">SSH</span><span class="punct">::</span><span class="constant">Session</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span>
|
|
516
|
+
<span class="punct">'</span><span class="string">host</span><span class="punct">',</span> <span class="punct">'</span><span class="string">username</span><span class="punct">',</span> <span class="punct">'</span><span class="string">password</span><span class="punct">',</span>
|
|
517
|
+
<span class="symbol">:compression</span> <span class="punct">=></span> <span class="punct">"</span><span class="string">zlib</span><span class="punct">"</span>
|
|
518
|
+
<span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">session</span><span class="punct">|</span>
|
|
519
|
+
<span class="punct">...</span>
|
|
520
|
+
<span class="keyword">end</span></pre></div></td></tr></table></div></div>
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
<p>Note that <code>Net::SSH::Session#new</code> accepts the same parameters as Net::SSH.start, and may also be called without a block.</p>
|
|
524
|
+
</div>
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
|
|
528
|
+
<div class="bottom"><div class="prevnext">
|
|
529
|
+
|
|
530
|
+
<a href="chapter-1.html">Previous (1. Introduction)</a> |
|
|
531
|
+
|
|
532
|
+
<a href="index.html">Up</a>
|
|
533
|
+
|
|
534
|
+
| <a href="chapter-3.html">Next (3. Channels)</a>
|
|
535
|
+
|
|
536
|
+
</div></div>
|
|
537
|
+
|
|
538
|
+
|
|
539
|
+
</div>
|
|
540
|
+
|
|
541
|
+
</td></tr>
|
|
542
|
+
</table>
|
|
543
|
+
</body>
|
|
544
|
+
</html>
|