1Net::SSH2(3) User Contributed Perl Documentation Net::SSH2(3)
2
6 Net::SSH2 - Support for the SSH 2 protocol via libssh2.
7
9 use Net::SSH2;
10 my $ssh2 = Net::SSH2->new();
12 $ssh2->connect('example.com') or die $!;
14 if ($ssh2->auth_keyboard('fizban')) {
16 my $chan = $ssh2->channel();
17 $chan->exec('program');
18 my $sftp = $ssh2->sftp();
20 my $fh = $sftp->open('/etc/passwd') or die;
21 print $_ while <$fh>;
22 }
23
25 "Net::SSH2" is a perl interface to the libssh2
26 (<http://www.libssh2.org>) library. It supports the SSH2 protocol
27 (there is no support for SSH1) with all of the key exchanges, ciphers,
28 and compression of libssh2.
29 Unless otherwise indicated, methods return a true value on success and
31 false on failure; use the error method to get extended error
32 information.
33 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
37 commands.
38 new
40 Create new SSH2 object.
41 To turn on tracing with a debug build of libssh2 use:
43 my $ssh2 = Net::SSH2->new(trace => -1);
45 banner ( text )
47 Set the SSH2 banner text sent to the remote host (prepends required
48 "SSH-2.0-").
49 version
51 In scalar context, returns libssh2 version/patch e.g. 0.18 or
52 "0.18.0-20071110". In list context, returns that version plus the
53 numeric version (major, minor, and patch, each encoded as 8 bits, e.g.
54 0x001200 for version 0.18) and the default banner text (e.g.
55 "SSH-2.0-libssh2_0.18.0-20071110").
56 error
58 Returns the last error code; returns false if no error. In list
59 context, returns (code, error name, error string).
60 sock
62 Returns a reference to the underlying IO::Socket::INET object, or
63 "undef" if not yet connected.
64 trace
66 Calls libssh2_trace with supplied bitmask, to enable all tracing use:
67 $ssh2->trace(-1);
69 You need a debug build of libssh2 with tracing support.
71 method ( type [, values... ] )
73 Sets or returns a method preference; for get, pass in the type only; to
74 set, pass in either a list of values or a comma-separated string.
75 Values can only be queried after the session is connected.
76 The following methods can be set or queried:
78 KEX Key exchange method names. Supported values:
80 diffie-hellman-group1-sha1
82 Diffie-Hellman key exchange with SHA-1 as hash, and Oakley
83 Group 2 (see RFC 2409).
84 diffie-hellman-group14-sha1
86 Diffie-Hellman key exchange with SHA-1 as hash, and Oakley
87 Group 14 (see RFC 3526).
88 diffie-hellman-group-exchange-sha1
90 Diffie-Hellman key exchange with SHA-1 as hash, using a
91 safe-prime/generator pair (chosen by server) of arbitrary
92 strength (specified by client) (see IETF draft secsh-dh-group-
93 exchange).
94 HOSTKEY
96 Public key algorithms. Supported values:
97 ssh-dss
99 Based on the Digital Signature Standard (FIPS-186-2).
100 ssh-rsa
102 Based on PKCS#1 (RFC 3447).
103 CRYPT_CS
105 Encryption algorithm from client to server. Supported algorithms:
106 aes256-cbc
108 AES in CBC mode, with 256-bit key.
109 rijndael-cbc@lysator.liu.se
111 Alias for aes256-cbc.
112 aes192-cbc
114 AES in CBC mode, with 192-bit key.
115 aes128-cbc
117 AES in CBC mode, with 128-bit key.
118 blowfish-cbc
120 Blowfish in CBC mode.
121 arcfour
123 ARCFOUR stream cipher.
124 cast128-cbc
126 CAST-128 in CBC mode.
127 3des-cbc
129 Three-key 3DES in CBC mode.
130 none
132 No encryption.
133 CRYPT_SC
135 Encryption algorithm from server to client. See CRYPT_CS for
136 supported algorithms.
137 MAC_CS
139 Message Authentication Code (MAC) algorithms from client to server.
140 Supported values:
141 hmac-sha1
143 SHA-1 with 20-byte digest and key length.
144 hmac-sha1-96
146 SHA-1 with 20-byte key length and 12-byte digest length.
147 hmac-md5
149 MD5 with 16-byte digest and key length.
150 hmac-md5-96
152 MD5 with 16-byte key length and 12-byte digest length.
153 hmac-ripemd160
155 RIPEMD-160 algorithm with 20-byte digest length.
156 hmac-ripemd160@openssh.com
158 Alias for hmac-ripemd160.
159 none
161 No encryption.
162 MAC_SC
164 Message Authentication Code (MAC) algorithms from server to client.
165 See MAC_SC for supported algorithms.
166 COMP_CS
168 Compression methods from client to server. Supported values:
169 zlib
171 The "zlib" compression method as described in RFC 1950 and RFC
172 1951.
173 none
175 No compression
176 COMP_SC
178 Compression methods from server to client. See COMP_CS for
179 supported compression methods.
180 connect ( handle | host [, port [, Timeout => secs ]] )
182 Accepts a handle over which to conduct the SSH 2 protocol. The handle
183 may be:
184 an "IO::*" object
186 a glob reference
187 an integer file descriptor
188 a host name and port
189 disconnect ( [description [, reason [, language]]] )
191 Send a clean disconnect message to the remote server. Default values
192 are empty strings for description and language, and
193 "SSH_DISCONNECT_BY_APPLICATION" for the reason.
194 hostkey ( hash type )
196 Returns a hash of the host key; note that the key is raw data and may
197 contain nulls or control characters. The type may be:
198 MD5 (16 bytes)
200 SHA1 (20 bytes)
201 auth_list ( [username] )
203 Get a list (or comma-separated string in scalar context) of
204 authentication methods supported by the server; or returns "undef". If
205 "undef" is returned and auth_ok is true, the server accepted an
206 unauthenticated session for the given username.
207 auth_ok
209 Returns true iff the session is authenticated.
210 auth_password ( username [, password [, callback ]] )
212 Authenticate using a password (PasswordAuthentication must be enabled
213 in sshd_config or equivalent for this to work.)
214 If the password has expired, if a callback code reference was given,
216 it's called as "callback($self, $username)" and should return a
217 password. If no callback is provided, LIBSSH2_ERROR_PASSWORD_EXPIRED
218 is returned.
219 auth_publickey ( username, public key, private key [, password ] )
221 Note that public key and private key are names of files containing the
222 keys!
223 Authenticate using keys and an optional password.
225 auth_hostbased ( username, public key, private key, hostname, [, local
227 username [, password ]] )
228 Host-based authentication using an optional password. The local
229 username defaults to be the same as the remote username.
230 auth_keyboard ( username, password | callback )
232 Authenticate using "keyboard-interactive". Takes either a password, or
233 a callback code reference which is invoked as "callback->(self,
234 username, name, instruction, prompt...)" (where each prompt is a hash
235 with "text" and "echo" keys, signifying the prompt text and whether the
236 user input should be echoed, respectively) which should return an array
237 of responses.
238 If only a username is provided, the default callback will handle
240 standard interactive responses; Term::ReadKey is required.
241 auth ( ... )
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
251 possible. The parameters are:
252 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
256 'publickey', with the addition of 'keyboard-auto' for automated
257 'keyboard-interactive'.
258 username
260 password
261 publickey
262 privatekey
263 As in the methods, publickey and privatekey are filenames.
264 hostname
266 local_username
267 interact
268 If this is set to a true value, interactive methods will be
269 considered.
270 cb_keyboard
272 auth_keyboard callback.
273 cb_password
275 auth_password callback.
276 channel ( [type, [window size, [packet size]]] )
278 Creates and returns a new channel object. The default type is
279 "session". See Net::SSH2::Channel.
280 tcpip ( host, port [, shost, sport ] )
282 Creates a TCP connection from the remote host to the given host:port,
283 returning a new channel. Binds to shost:sport (default 127.0.0.1:22).
284 listen ( port [, host [, bound port [, queue size ]]] )
286 Sets up a TCP listening port on the remote host. Host defaults to
287 0.0.0.0; if bound port is provided, it should be a scalar reference in
288 which the bound port is returned. Queue size specifies the maximum
289 number of queued connections allowed before the server refuses new
290 connections.
291 Returns a new Net::SSH2::Listener object.
293 scp_get ( remote [, local ] )
295 Retrieve a file with scp; local path defaults to basename of remote.
296 "local" may be an IO object (e.g. IO::File, IO::Scalar).
297 scp_put ( local [, remote ] )
299 Send a file with scp; remote path defaults to same as local. "local"
300 may be an IO object instead of a filename (but it must have a valid
301 stat method).
302 sftp
304 Return SecureFTP interface object (see Net::SSH2::SFTP).
305 public_key
307 Return public key interface object (see Net::SSH2::PublicKey).
308 poll ( timeout, arrayref of hashes )
310 Pass in a timeout in milliseconds and an arrayref of hashes with the
311 following keys:
312 handle
314 May be a Net::SSH2::Channel or Net::SSH2::Listener object, integer
315 file descriptor, or perl file handle.
316 events
318 Requested events. Combination of LIBSSH2_POLLFD_* constants (with
319 the POLL prefix stripped if present), or an arrayref of the names
320 ('in', 'hup' etc.).
321 revents
323 Returned events. Returns a hash with the (lowercased) names of the
324 received events ('in', 'hup', etc.) as keys with true values, and a
325 "value" key with the integer value.
326 Returns undef on error, or the number of active objects.
328 debug ( state )
330 Class method (affects all Net::SSH2 objects). Pass 1 to enable, 0 to
331 disable. Debug output is sent to stderr via "warn".
332 blocking ( flag )
334 Enable or disable blocking. Note that if blocking is disabled, methods
335 that create channels may fail, e.g. "channel", "SFTP", "scp_*".
336
338 Net::SSH2::Channel, Net::SSH2::Listener, Net::SSH2::SFTP,
339 Net::SSH2::File, Net::SSH2::Dir.
340 LibSSH2 documentation at <http://www.libssh2.org>.
342 IETF Secure Shell (secsh) working group at
344 http://www.ietf.org/html.charters/secsh-charter.html
345 <http://www.ietf.org/html.charters/secsh-charter.html>.
346 Net::SSH::Perl.
348
350 David B. Robins, <dbrobins@cpan.org>
351
353 Copyright (C) 2005 - 2010 by David B. Robins; all rights reserved.
354 This library is free software; you can redistribute it and/or modify it
356 under the same terms as Perl itself, either Perl version 5.8.0 or, at
357 your option, any later version of Perl 5 you may have available.
358perl v5.12.3 2010-07-13 Net::SSH2(3)