view release on metacpan or  search on metacpan

local/lib/perl5/Net/SFTP/Foreign.pm  view on Meta::CPAN

arrives on the SSH socket for the given time while waiting for some
command to complete.

When the timeout expires, the current method is aborted and
the SFTP connection becomes invalid.

Note that the given value is used internally to time out low level
operations. The high level operations available through the API may
take longer to expire (sometimes up to 4 times longer).

The C<Windows> backend used by default when the operating system is MS
Windows (though, not under Cygwin perl), does not support timeouts. To
overcome this limitation you can switch to the C<Net_SSH2> backend or
use L<Net::SSH::Any> that provides its own backend supporting
timeouts.

=item fs_encoding =E<gt> $encoding

Version 3 of the SFTP protocol (the one supported by this module)
knows nothing about the character encoding used on the remote
filesystem to represent file and directory names.

This option allows one to select the encoding used in the remote
machine. The default value is C<utf8>.

For instance:

  $sftp = Net::SFTP::Foreign->new('user@host', fs_encoding => 'latin1');

will convert any path name passed to any method in this package to its
C<latin1> representation before sending it to the remote side.

Note that this option will not affect file contents in any way.

This feature is not supported in perl 5.6 due to incomplete Unicode
support in the interpreter.

=item key_path =E<gt> $filename

=item key_path =E<gt> \@filenames

asks C<ssh> to use the key(s) in the given file(s) for authentication.

=item password =E<gt> $password

Logs into the remote host using password authentication with the given
password.

Password authentication is only available if the module L<IO::Pty> is
installed. Note also, that on Windows this module is only available
when running the Cygwin port of Perl.

=item asks_for_username_at_login =E<gt> 0|'auto'|1

During the interactive authentication dialog, most SSH servers only
ask for the user password as the login name is passed inside the SSH
protocol. But under some uncommon servers or configurations it is
possible that a username is also requested.

When this flag is set to C<1>, the username will be send
unconditionally at the first remote prompt and then the password at
the second.

When it is set to C<auto> the module will use some heuristics in order
to determine if it is being asked for an username.

When set to C<0>, the username will never be sent during the
authentication dialog. This is the default.

=item password_prompt => $regex_or_str

The module expects the password prompt from the remote server to end
in a colon or a question mark. This seems to cover correctly 99% of
real life cases.

Otherwise this option can be used to handle the exceptional cases. For
instance:

  $sftp = Net::SFTP::Foreign->new($host, password => $password,
                                  password_prompt => qr/\bpassword>\s*$/);

Note that your script will hang at the login phase if the wrong prompt
is used.

=item passphrase =E<gt> $passphrase

Logs into the remote server using a passphrase protected private key.

Requires also the module L<IO::Pty>.

=item expect_log_user =E<gt> $bool

This feature is obsolete as Expect is not used anymore to handle
password authentication.

=item ssh_cmd =E<gt> $sshcmd

=item ssh_cmd =E<gt> \@sshcmd

name of the external SSH client. By default C<ssh> is used.

For instance:

  $sftp = Net::SFTP::Foreign->new($host, ssh_cmd => 'plink');

When an array reference is used, its elements are inserted at the
beginning of the system call. That allows one, for instance, to
connect to the target host through some SSH proxy:

  $sftp = Net::SFTP::Foreign->new($host,
              ssh_cmd => [qw(ssh -l user proxy.server ssh)]);

But note that the module will not handle password authentication for
those proxies.

=item ssh_cmd_interface =E<gt> 'plink' or 'ssh' or 'tectia'

declares the command line interface that the SSH client used to
connect to the remote host understands. Currently C<plink>, C<ssh> and
C<tectia> are supported.

This option would be rarely required as the module infers the
interface from the SSH command name.

=item transport =E<gt> $fh

=item transport =E<gt> [$in_fh, $out_fh]

=item transport =E<gt> [$in_fh, $out_fh, $pid]

allows one to use an already open pipe or socket as the transport for
the SFTP protocol.

It can be (ab)used to make this module work with password
authentication or with keys requiring a passphrase.

C<in_fh> is the file handler used to read data from the remote server,
C<out_fh> is the file handler used to write data.

On some systems, when using a pipe as the transport, closing it, does
not cause the process at the other side to exit. The additional
C<$pid> argument can be used to instruct this module to kill that