Net::SSH2(3pm)

1Net::SSH2(3)          User Contributed Perl Documentation         Net::SSH2(3)
2
3
4

NAME

6       Net::SSH2 - Support for the SSH 2 protocol via libssh2.
7

SYNOPSIS

9         use Net::SSH2;
10
11         my $ssh2 = Net::SSH2->new();
12
13         $ssh2->connect('example.com') or die;
14
15         if ($ssh2->auth_keyboard('fizban')) {
16             my $chan = $ssh2->channel();
17             $chan->exec('program');
18
19             my $sftp = $ssh2->sftp();
20             my $fh = $sftp->open('/etc/passwd') or die;
21             print $_ while <$fh>;
22         }
23

DESCRIPTION

25       "Net::SSH2" is a perl interface to the libssh2 (<http://www.lib‐
26       ssh2.org>) library.  It supports the SSH2 protocol (there is no support
27       for SSH1) with all of the key exchanges, ciphers, and compression of
28       libssh2.
29
30       Unless otherwise indicated, methods return a true value on success and
31       false on failure; use the error method to get extended error informa‐
32       tion.
33
34       The typical order is to create the SSH2 object, set up the connection
35       methods you want to use, call connect, authenticate with one of the
36       "auth" methods, then create channels on the connection to perform com‐
37       mands.
38
39       new
40
41       Create new SSH2 object.
42
43       banner ( text )
44
45       Set the SSH2 banner text sent to the remote host (prepends required
46       "SSH-2.0-").
47
48       version
49
50       In scalar context, returns libssh2 version/patch e.g. 0.18 or
51       "0.18.0-20071110".  In list context, returns that version plus the
52       numeric version (major, minor, and patch, each encoded as 8 bits, e.g.
53       0x001200 for version 0.18) and the default banner text (e.g.
54       "SSH-2.0-libssh2_0.18.0-20071110").
55
56       error
57
58       Returns the last error code; returns false if no error.  In list con‐
59       text, returns (code, error name, error string).
60
61       method ( type [, values... ] )
62
63       Sets or returns a method preference; for get, pass in the type only; to
64       set, pass in either a list of values or a comma-separated string.  Val‐
65       ues can only be queried after the session is connected.
66
67       The following methods can be set or queried:
68
69       KEX Key exchange method names. Supported values:
70
71           diffie-hellman-group1-sha1
72               Diffie-Hellman key exchange with SHA-1 as hash, and Oakley
73               Group 2 (see RFC 2409).
74
75           diffie-hellman-group14-sha1
76               Diffie-Hellman key exchange with SHA-1 as hash, and Oakley
77               Group 14 (see RFC 3526).
78
79           diffie-hellman-group-exchange-sha1
80               Diffie-Hellman key exchange with SHA-1 as hash, using a
81               safe-prime/generator pair (chosen by server) of arbitrary
82               strength (specified by client) (see IETF draft
83               secsh-dh-group-exchange).
84
85       HOSTKEY
86           Public key algorithms. Supported values:
87
88           ssh-dss
89               Based on the Digital Signature Standard (FIPS-186-2).
90
91           ssh-rsa
92               Based on PKCS#1 (RFC 3447).
93
94       CRYPT_CS
95           Encryption algorithm from client to server. Supported algorithms:
96
97           aes256-cbc
98               AES in CBC mode, with 256-bit key.
99
100           rijndael-cbc@lysator.liu.se
101               Alias for aes256-cbc.
102
103           aes192-cbc
104               AES in CBC mode, with 192-bit key.
105
106           aes128-cbc
107               AES in CBC mode, with 128-bit key.
108
109           blowfish-cbc
110               Blowfish in CBC mode.
111
112           arcfour
113               ARCFOUR stream cipher.
114
115           cast128-cbc
116               CAST-128 in CBC mode.
117
118           3des-cbc
119               Three-key 3DES in CBC mode.
120
121           none
122               No encryption.
123
124       CRYPT_SC
125           Encryption algorithm from server to client. See CRYPT_CS for sup‐
126           ported algorithms.
127
128       MAC_CS
129           Message Authentication Code (MAC) algorithms from client to server.
130           Supported values:
131
132           hmac-sha1
133               SHA-1 with 20-byte digest and key length.
134
135           hmac-sha1-96
136               SHA-1 with 20-byte key length and 12-byte digest length.
137
138           hmac-md5
139               MD5 with 16-byte digest and key length.
140
141           hmac-md5-96
142               MD5 with 16-byte key length and 12-byte digest length.
143
144           hmac-ripemd160
145               RIPEMD-160 algorithm with 20-byte digest length.
146
147           hmac-ripemd160@openssh.com
148               Alias for hmac-ripemd160.
149
150           none
151               No encryption.
152
153       MAC_SC
154           Message Authentication Code (MAC) algorithms from server to client.
155           See MAC_SC for supported algorithms.
156
157       COMP_CS
158           Compression methods from client to server. Supported values:
159
160           zlib
161               The "zlib" compression method as described in RFC 1950 and RFC
162               1951.
163
164           none
165               No compression
166
167       COMP_SC
168           Compression methods from server to client. See COMP_CS for sup‐
169           ported compression methods.
170
171       connect ( [handle ⎪ host [, port]] )
172
173       Accepts a handle over which to conduct the SSH 2 protocol.  The handle
174       may be:
175
176       an "IO::*" object
177       a glob reference
178       an integer file descriptor
179       a host name and port
180
181       disconnect ( [description [, reason [, language]]] )
182
183       Send a clean disconnect message to the remote server.  Default values
184       are empty strings for description and language, and "SSH_DISCON‐
185       NECT_BY_APPLICATION" for the reason.
186
187       hostkey ( hash type )
188
189       Returns a hash of the host key; note that the key is raw data and may
190       contain nulls or control characters.  The type may be:
191
192       MD5 (16 bytes)
193       SHA1 (20 bytes)
194
195       auth_list ( [username] )
196
197       Get a list (or comma-separated string in scalar context) of authentica‐
198       tion methods supported by the server; or returns "undef".  If "undef"
199       is returned and auth_ok is true, the server accepted an unauthenticated
200       session for the given username.
201
202       auth_ok
203
204       Returns true iff the session is authenticated.
205
206       auth_password ( username [, password [, callback ]] )
207
208       Authenticate using a password (PasswordAuthentication must be enabled
209       in sshd_config or equivalent for this to work.)
210
211       If the password has expired, if a callback code reference was given,
212       it's called as "callback($self, $username)" and should return a pass‐
213       word.  If no callback is provided, LIBSSH2_ERROR_PASSWORD_EXPIRED is
214       returned.
215
216       auth_publickey ( username, public key, private key [, password ] )
217
218       Note that public key and private key are names of files containing the
219       keys!
220
221       Authenticate using keys and an optional password.
222
223       auth_hostbased ( username, public key, private key, hostname, [, local
224       username [, password ]] )
225
226       Host-based authentication using an optional password.  The local user‐
227       name defaults to be the same as the remote username.
228
229       auth_keyboard ( username, password ⎪ callback )
230
231       Authenticate using "keyboard-interactive".  Takes either a password, or
232       a callback code reference which is invoked as "callback->(self, user‐
233       name, name, instruction, prompt...)" (where each prompt is a hash with
234       "text" and "echo" keys, signifying the prompt text and whether the user
235       input should be echoed, respectively) which should return an array of
236       responses.
237
238       If only a username is provided, the default callback will handle stan‐
239       dard interactive responses; Term::ReadKey is required.
240
241       auth ( ... )
242
243       This is a general, prioritizing authentication mechanism that can use
244       any of the previous methods.  You provide it some parameters and
245       (optionally) a ranked list of methods you want considered (defaults to
246       all).  It will remove any unsupported methods or methods for which it
247       doesn't have parameters (e.g. if you don't give it a public key, it
248       can't use publickey or hostkey), and try the rest, returning whichever
249       one succeeded or a false value if they all failed.  If a parameter is
250       passed with an undef value, a default value will be supplied if possi‐
251       ble.  The parameters are:
252
253       rank
254           An optional ranked list of methods to try.  The names should be the
255           names of the Net::SSH2 "auth" methods, e.g. 'keyboard' or 'pub‐
256           lickey', with the addition of 'keyboard-auto' for automated 'key‐
257           board-interactive'.
258
259       username
260       password
261       publickey
262       privatekey
263           As in the methods, publickey and privatekey are filenames.
264
265       hostname
266       local_username
267       interact
268           If this is set to a true value, interactive methods will be consid‐
269           ered.
270
271       cb_keyboard
272           auth_keyboard callback.
273
274       cb_password
275           auth_password callback.
276
277       channel ( [type, [window size, [packet size]]] )
278
279       Creates and returns a new channel object.  The default type is "ses‐
280       sion".  See Net::SSH2::Channel.
281
282       tcpip ( host, port [, shost, sport ] )
283
284       Creates a TCP connection from the remote host to the given host:port,
285       returning a new channel.  Binds to shost:sport (default 127.0.0.1:22).
286
287       listen ( port [, host [, bound port [, queue size ]]] )
288
289       Sets up a TCP listening port on the remote host.  Host defaults to
290       0.0.0.0; if bound port is provided, it should be a scalar reference in
291       which the bound port is returned.  Queue size specifies the maximum
292       number of queued connections allowed before the server refuses new con‐
293       nections.
294
295       Returns a new Net::SSH2::Listener object.
296
297       scp_get ( remote [, local ] )
298
299       Retrieve a file with scp; local path defaults to basename of remote.
300       "local" may be an IO object (e.g. IO::File, IO::Scalar).
301
302       scp_put ( local [, remote ] )
303
304       Send a file with scp; remote path defaults to same as local.  "local"
305       may be an IO object instead of a filename (but it must have a valid
306       stat method).
307
308       sftp
309
310       Return SecureFTP interface object (see Net::SSH2::SFTP).
311
312       public_key
313
314       Return public key interface object (see Net::SSH2::PublicKey).
315
316       poll ( timeout, arrayref of hashes )
317
318       Pass in a timeout in milliseconds and an arrayref of hashes with the
319       following keys:
320
321       handle
322           May be a Net::SSH2::Channel or Net::SSH2::Listener object, integer
323           file descriptor, or perl file handle.
324
325       events
326           Requested events.  Combination of LIBSSH2_POLLFD_* constants (with
327           the POLL prefix stripped if present), or an arrayref of the names
328           ('in', 'hup' etc.).
329
330       revents
331           Returned events.  Returns a hash with the (lowercased) names of the
332           received events ('in', 'hup', etc.) as keys with true values, and a
333           "value" key with the integer value.
334
335       Returns undef on error, or the number of active objects.
336
337       debug ( state )
338
339       Class method (affects all Net::SSH2 objects).  Pass 1 to enable, 0 to
340       disable.  Debug output is sent to stderr via "warn".
341
342       blocking ( flag )
343
344       Enable or disable blocking.  Note that if blocking is disabled, methods
345       that create channels may fail, e.g. "channel", "SFTP", "scp_*".
346

AUTHOR

359       David B. Robins, <dbrobins@cpan.org>
360

COPYRIGHT AND LICENSE

362       Copyright (C) 2005, 2006 by David B. Robins; all rights reserved.
363
364       This library is free software; you can redistribute it and/or modify it
365       under the same terms as Perl itself, either Perl version 5.8.0 or, at
366       your option, any later version of Perl 5 you may have available.
367
368
369
370perl v5.8.8                       2007-02-24                      Net::SSH2(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE