1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
|
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>module Net::SSH - net-ssh 4.1.0.rc1</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
</script>
<script src="../js/jquery.js"></script>
<script src="../js/darkfish.js"></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="module">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div class="nav-section">
<h3>Table of Contents</h3>
<ul class="link-list" role="directory">
<li><a href="#module-Net::SSH-label-22Um-2C+all+I+want+to+do+is+X-2C+just+show+me+how-21-22">“Um, all I want to do is X, just show me how!”</a>
<li><a href="#module-Net::SSH-label-X+-3D-3D+-22execute+a+command+and+capture+the+output-22">X == “execute a command and capture the output”</a>
<li><a href="#module-Net::SSH-label-X+-3D-3D+-22forward+connections+on+a+local+port+to+a+remote+host-22">X == “forward connections on a local port to a remote host”</a>
<li><a href="#module-Net::SSH-label-X+-3D-3D+-22forward+connections+on+a+remote+port+to+the+local+host-22">X == “forward connections on a remote port to the local host”</a>
</ul>
</div>
<div id="class-metadata">
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-assign_defaults">::assign_defaults</a>
<li ><a href="#method-c-configuration_for">::configuration_for</a>
<li ><a href="#method-c-start">::start</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="module-Net::SSH">
<h1 id="module-Net::SSH" class="module">
module Net::SSH
</h1>
<section class="description">
<p><a href="SSH.html">Net::SSH</a> is a library for interacting,
programmatically, with remote processes via the SSH2 protocol. Sessions are
always initiated via <a href="SSH.html#method-c-start">::start</a>. From
there, a program interacts with the new <a href="SSH.html">SSH</a> session
via the convenience methods on <a
href="SSH/Connection/Session.html">Net::SSH::Connection::Session</a>, by
opening and interacting with new channels
(Net::SSH::Connection:Session#open_channel and <a
href="SSH/Connection/Channel.html">Net::SSH::Connection::Channel</a>), or
by forwarding local and/or remote ports through the connection
(Net::SSH::Service::Forward).</p>
<p>The <a href="SSH.html">SSH</a> protocol is very event-oriented. Requests
are sent from the client to the server, and are answered asynchronously.
This gives great flexibility (since clients can have multiple requests
pending at a time), but it also adds complexity. <a
href="SSH.html">Net::SSH</a> tries to manage this complexity by providing
some simpler methods of synchronous communication (see <a
href="SSH/Connection/Session.html#method-i-exec-21">Net::SSH::Connection::Session#exec!</a>).</p>
<p>In general, though, and if you want to do anything more complicated than
simply executing commands and capturing their output, you'll need to
use channels (Net::SSH::Connection::Channel) to build state machines that
are executed while the event loop runs
(Net::SSH::Connection::Session#loop).</p>
<p><a href="SSH/Connection/Session.html">Net::SSH::Connection::Session</a> and
<a href="SSH/Connection/Channel.html">Net::SSH::Connection::Channel</a>
have more information about this technique.</p>
<h1 id="module-Net::SSH-label-22Um-2C+all+I+want+to+do+is+X-2C+just+show+me+how-21-22">“Um, all I want to do is X, just show me how!”<span><a href="#module-Net::SSH-label-22Um-2C+all+I+want+to+do+is+X-2C+just+show+me+how-21-22">¶</a> <a href="#top">↑</a></span></h1>
<h2 id="module-Net::SSH-label-X+-3D-3D+-22execute+a+command+and+capture+the+output-22">X == “execute a command and capture the output”<span><a href="#module-Net::SSH-label-X+-3D-3D+-22execute+a+command+and+capture+the+output-22">¶</a> <a href="#top">↑</a></span></h2>
<pre class="ruby"><span class="ruby-constant">Net</span><span class="ruby-operator">::</span><span class="ruby-constant">SSH</span>.<span class="ruby-identifier">start</span>(<span class="ruby-string">"host"</span>, <span class="ruby-string">"user"</span>, <span class="ruby-identifier">password</span><span class="ruby-operator">:</span> <span class="ruby-string">"password"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ssh</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">result</span> = <span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">exec!</span>(<span class="ruby-string">"ls -l"</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">result</span>
<span class="ruby-keyword">end</span>
</pre>
<h2 id="module-Net::SSH-label-X+-3D-3D+-22forward+connections+on+a+local+port+to+a+remote+host-22">X == “forward connections on a local port to a remote host”<span><a href="#module-Net::SSH-label-X+-3D-3D+-22forward+connections+on+a+local+port+to+a+remote+host-22">¶</a> <a href="#top">↑</a></span></h2>
<pre class="ruby"><span class="ruby-constant">Net</span><span class="ruby-operator">::</span><span class="ruby-constant">SSH</span>.<span class="ruby-identifier">start</span>(<span class="ruby-string">"host"</span>, <span class="ruby-string">"user"</span>, <span class="ruby-identifier">password</span><span class="ruby-operator">:</span> <span class="ruby-string">"password"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ssh</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">forward</span>.<span class="ruby-identifier">local</span>(<span class="ruby-value">1234</span>, <span class="ruby-string">"www.google.com"</span>, <span class="ruby-value">80</span>)
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">loop</span> { <span class="ruby-keyword">true</span> }
<span class="ruby-keyword">end</span>
</pre>
<h2 id="module-Net::SSH-label-X+-3D-3D+-22forward+connections+on+a+remote+port+to+the+local+host-22">X == “forward connections on a remote port to the local host”<span><a href="#module-Net::SSH-label-X+-3D-3D+-22forward+connections+on+a+remote+port+to+the+local+host-22">¶</a> <a href="#top">↑</a></span></h2>
<pre class="ruby"><span class="ruby-constant">Net</span><span class="ruby-operator">::</span><span class="ruby-constant">SSH</span>.<span class="ruby-identifier">start</span>(<span class="ruby-string">"host"</span>, <span class="ruby-string">"user"</span>, <span class="ruby-identifier">password</span><span class="ruby-operator">:</span> <span class="ruby-string">"password"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ssh</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">forward</span>.<span class="ruby-identifier">remote</span>(<span class="ruby-value">80</span>, <span class="ruby-string">"www.google.com"</span>, <span class="ruby-value">1234</span>)
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">loop</span> { <span class="ruby-keyword">true</span> }
<span class="ruby-keyword">end</span>
</pre>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="VALID_OPTIONS">VALID_OPTIONS
<dd><p>This is the set of options that <a
href="SSH.html#method-c-start">::start</a> recognizes. See <a
href="SSH.html#method-c-start">::start</a> for a description of each
option.</p>
</dl>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-assign_defaults" class="method-detail ">
<div class="method-heading">
<span class="method-name">assign_defaults</span><span
class="method-args">(options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="assign_defaults-source">
<pre><span class="ruby-comment"># File lib/net/ssh.rb, line 273</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">assign_defaults</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-keyword">if</span> <span class="ruby-operator">!</span><span class="ruby-identifier">options</span>[<span class="ruby-value">:logger</span>]
<span class="ruby-identifier">options</span>[<span class="ruby-value">:logger</span>] = <span class="ruby-constant">Logger</span>.<span class="ruby-identifier">new</span>(<span class="ruby-constant">STDERR</span>)
<span class="ruby-identifier">options</span>[<span class="ruby-value">:logger</span>].<span class="ruby-identifier">level</span> = <span class="ruby-constant">Logger</span><span class="ruby-operator">::</span><span class="ruby-constant">FATAL</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">options</span>[<span class="ruby-value">:password_prompt</span>] <span class="ruby-operator">||=</span> <span class="ruby-constant">Prompt</span>.<span class="ruby-identifier">default</span>(<span class="ruby-identifier">options</span>)
[<span class="ruby-value">:password</span>, <span class="ruby-value">:passphrase</span>].<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">key</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">key</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">options</span>.<span class="ruby-identifier">key?</span>(<span class="ruby-identifier">key</span>) <span class="ruby-operator">&&</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">key</span>].<span class="ruby-identifier">nil?</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-configuration_for" class="method-detail ">
<div class="method-heading">
<span class="method-name">configuration_for</span><span
class="method-args">(host, use_ssh_config)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a hash of the configuration options for the given host, as read
from the <a href="SSH.html">SSH</a> configuration file(s). If
<code>use_ssh_config</code> is true (the default), this will load
configuration from both ~/.ssh/config and /etc/ssh_config. If
<code>use_ssh_config</code> is nil or false, nothing will be loaded (and an
empty hash returned). Otherwise, <code>use_ssh_config</code> may be a file
name (or array of file names) of <a href="SSH.html">SSH</a> configuration
file(s) to read.</p>
<p>See <a href="SSH/Config.html">Net::SSH::Config</a> for the full description
of all supported options.</p>
<div class="method-source-code" id="configuration_for-source">
<pre><span class="ruby-comment"># File lib/net/ssh.rb, line 263</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">configuration_for</span>(<span class="ruby-identifier">host</span>, <span class="ruby-identifier">use_ssh_config</span>)
<span class="ruby-identifier">files</span> = <span class="ruby-keyword">case</span> <span class="ruby-identifier">use_ssh_config</span>
<span class="ruby-keyword">when</span> <span class="ruby-keyword">true</span> <span class="ruby-keyword">then</span> <span class="ruby-constant">Net</span><span class="ruby-operator">::</span><span class="ruby-constant">SSH</span><span class="ruby-operator">::</span><span class="ruby-constant">Config</span>.<span class="ruby-identifier">expandable_default_files</span>
<span class="ruby-keyword">when</span> <span class="ruby-keyword">false</span>, <span class="ruby-keyword">nil</span> <span class="ruby-keyword">then</span> <span class="ruby-keyword">return</span> {}
<span class="ruby-keyword">else</span> <span class="ruby-constant">Array</span>(<span class="ruby-identifier">use_ssh_config</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-constant">Net</span><span class="ruby-operator">::</span><span class="ruby-constant">SSH</span><span class="ruby-operator">::</span><span class="ruby-constant">Config</span>.<span class="ruby-identifier">for</span>(<span class="ruby-identifier">host</span>, <span class="ruby-identifier">files</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-start" class="method-detail ">
<div class="method-heading">
<span class="method-name">start</span><span
class="method-args">(host, user=nil, options={}) { |connection| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The standard means of starting a new <a href="SSH.html">SSH</a> connection.
When used with a block, the connection will be closed when the block
terminates, otherwise the connection will just be returned. The yielded (or
returned) value will be an instance of <a
href="SSH/Connection/Session.html">Net::SSH::Connection::Session</a>
(q.v.). (See also <a
href="SSH/Connection/Channel.html">Net::SSH::Connection::Channel</a> and <a
href="SSH/Service/Forward.html">Net::SSH::Service::Forward</a>.)</p>
<pre class="ruby"><span class="ruby-constant">Net</span><span class="ruby-operator">::</span><span class="ruby-constant">SSH</span>.<span class="ruby-identifier">start</span>(<span class="ruby-string">"host"</span>, <span class="ruby-string">"user"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ssh</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">exec!</span> <span class="ruby-string">"cp /some/file /another/location"</span>
<span class="ruby-identifier">hostname</span> = <span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">exec!</span>(<span class="ruby-string">"hostname"</span>)
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">open_channel</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ch</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">ch</span>.<span class="ruby-identifier">exec</span> <span class="ruby-string">"sudo -p 'sudo password: ' ls"</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ch</span>, <span class="ruby-identifier">success</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">abort</span> <span class="ruby-string">"could not execute sudo ls"</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">success</span>
<span class="ruby-identifier">ch</span>.<span class="ruby-identifier">on_data</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">ch</span>, <span class="ruby-identifier">data</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">print</span> <span class="ruby-identifier">data</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">data</span> <span class="ruby-operator">=~</span> <span class="ruby-regexp">/sudo password: /</span>
<span class="ruby-identifier">ch</span>.<span class="ruby-identifier">send_data</span>(<span class="ruby-string">"password\n"</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">ssh</span>.<span class="ruby-identifier">loop</span>
<span class="ruby-keyword">end</span>
</pre>
<p>This method accepts the following options (all are optional):</p>
<ul><li>
<p>:auth_methods => an array of authentication methods to try</p>
</li><li>
<p>:bind_address => the IP address on the connecting machine to use in
establishing connection. (:bind_address is discarded if :proxy is set.)</p>
</li><li>
<p>:compression => the compression algorithm to use, or <code>true</code>
to use whatever is supported.</p>
</li><li>
<p>:compression_level => the compression level to use when sending data</p>
</li><li>
<p>:config => set to <code>true</code> to load the default OpenSSH config
files (~/.ssh/config, /etc/ssh_config), or to <code>false</code> to not
load them, or to a file-name (or array of file-names) to load those
specific configuration files. Defaults to <code>true</code>.</p>
</li><li>
<p>:encryption => the encryption cipher (or ciphers) to use</p>
</li><li>
<p>:forward_agent => set to true if you want the <a href="SSH.html">SSH</a>
agent connection to be forwarded</p>
</li><li>
<p>:known_hosts => a custom object holding known hosts records. It must
implement search_for and add in a similiar manner as <a
href="SSH/KnownHosts.html">KnownHosts</a>.</p>
</li><li>
<p>:global_known_hosts_file => the location of the global known hosts file.
Set to an array if you want to specify multiple global known hosts files.
Defaults to %w(/etc/ssh/ssh_known_hosts /etc/ssh/ssh_known_hosts2).</p>
</li><li>
<p>:hmac => the hmac algorithm (or algorithms) to use</p>
</li><li>
<p>:host_key => the host key algorithm (or algorithms) to use</p>
</li><li>
<p>:host_key_alias => the host name to use when looking up or adding a host
to a known_hosts dictionary file</p>
</li><li>
<p>:host_name => the real host name or IP to log into. This is used instead
of the <code>host</code> parameter, and is primarily only useful when
specified in an <a href="SSH.html">SSH</a> configuration file. It lets you
specify an “alias”, similarly to adding an entry in /etc/hosts but without
needing to modify /etc/hosts.</p>
</li><li>
<p>:keepalive => set to <code>true</code> to send a keepalive packet to the
<a href="SSH.html">SSH</a> server when there's no traffic between the
<a href="SSH.html">SSH</a> server and <a href="SSH.html">Net::SSH</a>
client for the keepalive_interval seconds. Defaults to <code>false</code>.</p>
</li><li>
<p>:keepalive_interval => the interval seconds for keepalive. Defaults to
<code>300</code> seconds.</p>
</li><li>
<p>:keepalive_maxcount => the maximun number of keepalive packet miss
allowed. Defaults to 3</p>
</li><li>
<p>:kex => the key exchange algorithm (or algorithms) to use</p>
</li><li>
<p>:keys => an array of file names of private keys to use for publickey and
hostbased authentication</p>
</li><li>
<p>:key_data => an array of strings, with each element of the array being a
raw private key in PEM format.</p>
</li><li>
<p>:keys_only => set to <code>true</code> to use only private keys from
<code>keys</code> and <code>key_data</code> parameters, even if ssh-agent
offers more identities. This option is intended for situations where
ssh-agent offers many different identites.</p>
</li><li>
<p>:logger => the logger instance to use when logging</p>
</li><li>
<p>:max_pkt_size => maximum size we tell the other side that is supported
per packet. Default is 0x8000 (32768 bytes). Increase to 0x10000 (65536
bytes) for better performance if your <a href="SSH.html">SSH</a> server
supports it (most do).</p>
</li><li>
<p>:max_win_size => maximum size we tell the other side that is supported
for the window.</p>
</li><li>
<p>:non_interactive => set to true if your app is non interactive and
prefers authentication failure vs password prompt. Non-interactive
applications should set it to true to prefer failing a password/etc auth
methods vs. asking for password.</p>
</li><li>
<p>:paranoid => either false, true, :very, or :secure specifying how strict
host-key verification should be (in increasing order here). You can also
provide an own Object which responds to <code>verify</code>. The argument
given to <code>verify</code> is a hash consisting of the <code>:key</code>,
the <code>:key_blob</code>, the <code>:fingerprint</code> and the
<code>:session</code>. Returning true accepts the host key, returning false
declines it and closes the connection.</p>
</li><li>
<p>:passphrase => the passphrase to use when loading a private key (default
is <code>nil</code>, for no passphrase)</p>
</li><li>
<p>:password => the password to use to login</p>
</li><li>
<p>:port => the port to use when connecting to the remote host</p>
</li><li>
<p>:properties => a hash of key/value pairs to add to the new
connection's properties (see <a
href="SSH/Connection/Session.html#attribute-i-properties">Net::SSH::Connection::Session#properties</a>)</p>
</li><li>
<p>:proxy => a proxy instance (see <a href="SSH/Proxy.html">Proxy</a>) to
use when connecting</p>
</li><li>
<p>:rekey_blocks_limit => the max number of blocks to process before
rekeying</p>
</li><li>
<p>:rekey_limit => the max number of bytes to process before rekeying</p>
</li><li>
<p>:rekey_packet_limit => the max number of packets to process before
rekeying</p>
</li><li>
<p>:send_env => an array of local environment variable names to export to
the remote environment. Names may be given as <a
href="../String.html">String</a> or Regexp.</p>
</li><li>
<p>:timeout => how long to wait for the initial connection to be made</p>
</li><li>
<p>:user => the user name to log in as; this overrides the
<code>user</code> parameter, and is primarily only useful when provided via
an <a href="SSH.html">SSH</a> configuration file.</p>
</li><li>
<p>:remote_user => used for substitution into the '%r' part of a
ProxyCommand</p>
</li><li>
<p>:user_known_hosts_file => the location of the user known hosts file. Set
to an array to specify multiple user known hosts files. Defaults to
%w(~/.ssh/known_hosts ~/.ssh/known_hosts2).</p>
</li><li>
<p>:use_agent => Set false to disable the use of ssh-agent. Defaults to
true</p>
</li><li>
<p>:verbose => how verbose to be (Logger verbosity constants, Logger::DEBUG
is very verbose, Logger::FATAL is all but silent). Logger::FATAL is the
default. The symbols :debug, :info, :warn, :error, and :fatal are also
supported and are translated to the corresponding Logger constant.</p>
</li><li>
<p>:append_all_supported_algorithms => set to <code>true</code> to append
all supported algorithms by net-ssh. Was the default behaviour until 2.10</p>
</li><li>
<p>:number_of_password_prompts => Number of prompts for the password
authentication method defaults to 3 set to 0 to disable prompt for password
auth method</p>
</li><li>
<p>:password_prompt => a custom prompt object with ask method. See <a
href="SSH/Prompt.html">Net::SSH::Prompt</a></p>
</li><li>
<p>:agent_socket_factory => enables the user to pass a lambda/block that
will serve as the socket factory</p>
<pre>Net::SSH::start(user,host,agent_socket_factory: ->{ UNIXSocket.open('/foo/bar') })
example: ->{ UNIXSocket.open('/foo/bar')}</pre>
</li></ul>
<p>If <code>user</code> parameter is nil it defaults to USER from ssh_config,
or local username</p>
<div class="method-source-code" id="start-source">
<pre><span class="ruby-comment"># File lib/net/ssh.rb, line 204</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">start</span>(<span class="ruby-identifier">host</span>, <span class="ruby-identifier">user</span>=<span class="ruby-keyword">nil</span>, <span class="ruby-identifier">options</span>={}, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>)
<span class="ruby-identifier">invalid_options</span> = <span class="ruby-identifier">options</span>.<span class="ruby-identifier">keys</span> <span class="ruby-operator">-</span> <span class="ruby-constant">VALID_OPTIONS</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">invalid_options</span>.<span class="ruby-identifier">any?</span>
<span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-node">"invalid option(s): #{invalid_options.join(', ')}"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">assign_defaults</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-identifier">_sanitize_options</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-identifier">options</span>[<span class="ruby-value">:user</span>] = <span class="ruby-identifier">user</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">user</span>
<span class="ruby-identifier">options</span> = <span class="ruby-identifier">configuration_for</span>(<span class="ruby-identifier">host</span>, <span class="ruby-identifier">options</span>.<span class="ruby-identifier">fetch</span>(<span class="ruby-value">:config</span>, <span class="ruby-keyword">true</span>)).<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-identifier">host</span> = <span class="ruby-identifier">options</span>.<span class="ruby-identifier">fetch</span>(<span class="ruby-value">:host_name</span>, <span class="ruby-identifier">host</span>)
<span class="ruby-keyword">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-value">:non_interactive</span>]
<span class="ruby-identifier">options</span>[<span class="ruby-value">:number_of_password_prompts</span>] = <span class="ruby-value">0</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-value">:verbose</span>]
<span class="ruby-identifier">options</span>[<span class="ruby-value">:logger</span>].<span class="ruby-identifier">level</span> = <span class="ruby-keyword">case</span> <span class="ruby-identifier">options</span>[<span class="ruby-value">:verbose</span>]
<span class="ruby-keyword">when</span> <span class="ruby-constant">Integer</span> <span class="ruby-keyword">then</span> <span class="ruby-identifier">options</span>[<span class="ruby-value">:verbose</span>]
<span class="ruby-keyword">when</span> <span class="ruby-value">:debug</span> <span class="ruby-keyword">then</span> <span class="ruby-constant">Logger</span><span class="ruby-operator">::</span><span class="ruby-constant">DEBUG</span>
<span class="ruby-keyword">when</span> <span class="ruby-value">:info</span> <span class="ruby-keyword">then</span> <span class="ruby-constant">Logger</span><span class="ruby-operator">::</span><span class="ruby-constant">INFO</span>
<span class="ruby-keyword">when</span> <span class="ruby-value">:warn</span> <span class="ruby-keyword">then</span> <span class="ruby-constant">Logger</span><span class="ruby-operator">::</span><span class="ruby-constant">WARN</span>
<span class="ruby-keyword">when</span> <span class="ruby-value">:error</span> <span class="ruby-keyword">then</span> <span class="ruby-constant">Logger</span><span class="ruby-operator">::</span><span class="ruby-constant">ERROR</span>
<span class="ruby-keyword">when</span> <span class="ruby-value">:fatal</span> <span class="ruby-keyword">then</span> <span class="ruby-constant">Logger</span><span class="ruby-operator">::</span><span class="ruby-constant">FATAL</span>
<span class="ruby-keyword">else</span> <span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-node">"can't convert #{options[:verbose].inspect} to any of the Logger level constants"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">transport</span> = <span class="ruby-constant">Transport</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">host</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">auth</span> = <span class="ruby-constant">Authentication</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">transport</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">user</span> = <span class="ruby-identifier">options</span>.<span class="ruby-identifier">fetch</span>(<span class="ruby-value">:user</span>, <span class="ruby-identifier">user</span>) <span class="ruby-operator">||</span> <span class="ruby-constant">Etc</span>.<span class="ruby-identifier">getlogin</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">auth</span>.<span class="ruby-identifier">authenticate</span>(<span class="ruby-string">"ssh-connection"</span>, <span class="ruby-identifier">user</span>, <span class="ruby-identifier">options</span>[<span class="ruby-value">:password</span>])
<span class="ruby-identifier">connection</span> = <span class="ruby-constant">Connection</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">transport</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-keyword">if</span> <span class="ruby-identifier">block_given?</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-keyword">yield</span> <span class="ruby-identifier">connection</span>
<span class="ruby-keyword">ensure</span>
<span class="ruby-identifier">connection</span>.<span class="ruby-identifier">close</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">connection</span>.<span class="ruby-identifier">closed?</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">else</span>
<span class="ruby-keyword">return</span> <span class="ruby-identifier">connection</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">transport</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">raise</span> <span class="ruby-constant">AuthenticationFailed</span>, <span class="ruby-node">"Authentication failed for user #{user}@#{host}"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="http://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.0.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>
|
