NAME

Net::SFTP::Recursive - Perl class for transfering files recursively and securely

SYNOPSIS

use Net::SFTP::Recursive;

my %cfg = (user=>'usr_id', password=>'secret',
           local_dir=>'/ftp/dir', remote_dir=>'/remote/dir',
           file_filter=>'ftp*');
my $sftp = Net::SFTP::Recursive->new;
# or combine the two together
my $sftp = Net::SFTP::Recursive->new(%cfg);

# transfer files from local to remote
$sftp->rput('/my/local/dir','/remote/dir'); 

# transfer files from remote to local
$sftp->rget('/pub/remotel/dir','/local/dir'); 

# pass the output to &my_cb method to process
$sftp->rget('/pub/mydir', '/local/dir', \&my_cb);

# with file and dir filters
$sftp->rget('/pub/mydir', '/local/dir', \&my_cb,
      {file_pat=>'pdf$', dir_pat=>'^f'});

# you can also use a callback method for get or put method as well
$sftp->rget('/remote/dir','/my/dir',\&my_cb,{cb4get=>\&myget_cb});
$sftp->rput('/my/dir','/remote/dir',\&my_cb,{cb4put=>\&mysub_cb});

DESCRIPTION

This class contains methods to transfer files recursively and securely using Net::SFTP and Net::SSH::Perl.

Net::SFTP is a pure-Perl implementation of the Secure File Transfer Protocol (SFTP)--file transfer built on top of the SSH protocol. Net::SFTP uses Net::SSH::Perl to build a secure, encrypted tunnel through which files can be transferred and managed. It provides a subset of the commands listed in the SSH File Transfer Protocol IETF draft, which can be found at http://www.openssh.com/txt/draft-ietf-secsh-filexfer-00.txt.

SFTP stands for Secure File Transfer Protocol and is a method of transferring files between machines over a secure, encrypted connection (as opposed to regular FTP, which functions over an insecure connection). The security in SFTP comes through its integration with SSH, which provides an encrypted transport layer over which the SFTP commands are executed, and over which files can be transferred. The SFTP protocol defines a client and a server; only the client, not the server, is implemented in Net::SFTP.

Because it is built upon SSH, SFTP inherits all of the built-in functionality provided by Net::SSH::Perl: encrypted communications between client and server, multiple supported authentication methods (eg. password, public key, etc.).

This class extends from Net::SFTP and inherents all the methods from it, plus more methods: rget, rput, and local_ls.

new ($host, %args)

Input variables:

$host - ftp host name or IP address 
%args - configuration parameters 

Variables used or routines called:

None

How to use:

my $obj = new Net::SFTP::Recursive;      # or
my $obj = Net::SFTP::Recursive->new;     # or
my $svr = 'ftp.mydomain.com'; 
my $obj = Net::SFTP::Recursive->new($svr,
   user=>'usr',password=>'pwd'); 

Return: new empty or initialized Net::SFTP::Recursive object.

Opens a new SFTP connection with a remote host $host, and returns a Net::SFTP object representing that open connection.

%args can contain:

• user

  The username to use to log in to the remote server. This should be your SSH login, and can be empty, in which case the username is drawn from the user executing the process.

  See the login method in Net::SSH::Perl for more details.

• password

  The password to use to log in to the remote server. This should be your SSH password, if you use password authentication in SSH; if you use public key authentication, this argument is unused.

  See the login method in Net::SSH::Perl for more details.

• debug

  If set to a true value, debugging messages will be printed out for both the SSH and SFTP protocols. This automatically turns on the debug parameter in Net::SSH::Perl.

  The default is false.

• warn

  If given a sub ref, the sub is called with $self and any warning message; if set to false, warnings are supressed; otherwise they are output with 'warn' (default).

• ssh_args

  Specifies a reference to a list of named arguments that should be given to the constructor of the Net::SSH::Perl object underlying the Net::SFTP connection.

  For example, you could use this to set up your authentication identity files, to set a specific cipher for encryption, etc.

  See the new method in Net::SSH::Perl for more details.

METHODS

The following are the common methods, routines, and functions defined in this classes.

Exported Tag: All

The :all tag includes all the methods or sub-rountines defined in this class.

use Net::SFTP::Recursive qw(:all);

It includes the following sub-routines:

rget ($remote, $local, \&callback, $ar)

Input variables:

 $remote - remote path on ftp server
 $local  - local path for storing the files and directories
 \&callback - a sub routine to process the intermediate information
 $ar     - hash ref for additional parameters 
     file_pat - pattern for filtering file name such as
       .txt$ - all the files with .txt extension 
     dir_pat  - pattern for filtering directory name 
       ^F   - all the dir starting with F
     cb4get - sub ref for passing to get method. See callback 
              in get method in Net::SFTP

Variables used or routines called:

None

How to use:

my $svt = 'ftp.mydomain.com';
my %cfg = (user=>'test_user', password => 'secure', debug=>1);
my $sftp = Net::SFTP::Recursive->new($svr, %cfg);
   $sftp->rget('/pub/mydir', '/local/dir', \&my_cb);
# with file and dir filters
   $sftp->rget('/pub/mydir', '/local/dir', \&my_cb,
      {file_pat=>'pdf$', dir_pat=>'^f', cb4get=>\&myget_cb});

Return: $msg - number of files transferred

Downloads files and/or sub-directory from $remote to $local. If $local is specified, it is opened/created, and the contents of the remote file $remote are written to $local. In addition, its filesystem attributes (atime, mtime, permissions, etc.) will be set to those of the remote file.

If rget is called in a non-void context, returns the contents of $remote (as well as writing them to $local, if $local is provided. Undef is returned on failure.

$local is default to the current directory if it is not specified.

If \&callback is specified, it should be a reference to a subroutine. The subroutine will be executed at each iteration of transfering a file. The callback function will receive as arguments: a Net::SFTP object with an open SFTP connection; the remote file path and name; the local file path and name and the hash reference containing atime, mtime, flags, uid, gid, perm, and size in bytes). You can use this mechanism to provide status messages, download progress meters, etc.:

sub callback {
    my($sftp, $remote, $local, $ar) = @_;
    print "Copied from $remote to $local ($ar->{size} Bytes)\n";
}

rput ($local, $remote, \&callback, $ar)

Input variables:

 $local  - local path for storing the files and directories
 $remote - remote path on ftp server
 \&callback - a sub routine to process the intermediate information
 $ar     - hash ref for additional parameters 
     file_pat - pattern for filtering file name such as
       .txt$ - all the files with .txt extension 
     dir_pat  - pattern for filtering directory name 
       ^F   - all the dir starting with F
     cb4put - sub ref for passing to get method. See callback 
              in put method in Net::SFTP

Variables used or routines called:

None

How to use:

my $svt = 'ftp.mydomain.com';
my %cfg = (user=>'test_user', password => 'secure', debug=>1);
my $sftp = Net::SFTP::Recursive->new($svr, %cfg);
   $sftp->rput('/local/mydir', '/remote/dir', \&my_cb);
# with file and dir filters
   $sftp->rput('/local/mydir', '/remote/dir', \&my_cb,
      {file_pat=>'pdf$', dir_pat=>'^f', cb4put=>\&myput_cb});

Return: $msg - number of files transferred

Downloads files and/or sub-directory from $remote to $local. If $local is specified, it is opened/created, and the contents of the remote file $remote are written to $local. In addition, its filesystem attributes (atime, mtime, permissions, etc.) will be set to those of the remote file.

If rget is called in a non-void context, returns the contents of $remote (as well as writing them to $local, if $local is provided. Undef is returned on failure.

$local is default to the current directory if it is not specified.

If \&callback is specified, it should be a reference to a subroutine. The subroutine will be executed at each iteration of transfering a file. The callback function will receive as arguments: a Net::SFTP object with an open SFTP connection; the remote file path and name; the local file path and name and the hash reference containing atime, mtime, flags, uid, gid, perm, and size in bytes). You can use this mechanism to provide status messages, download progress meters, etc.:

sub callback {
    my($sftp, $local, $remote, $ar) = @_;
    print "Copied from $remote to $local ($ar->{size} Bytes)\n";
}

local_ls ($ldr[,$sr[,$hr]])

Input variables:

 $ldr    - local path for files and sub-directories to be listed
 $sr     - sub ref for processing each file stat
 $hr     - hash ref for passing any additional parameters 
     file_pat - pattern for filtering file name such as
       .txt$ - all the files with .txt extension 
     dir_pat  - pattern for filtering directory name 
       ^F   - all the dir starting with F
     cb4put - sub ref for passing to get method. See callback 
              in put method in Net::SFTP

Variables used or routines called:

None

How to use:

my $svt = 'ftp.mydomain.com';
my %cfg = (user=>'test_user', password => 'secure', debug=>1);
my $sftp = Net::SFTP::Recursive->new($svr, %cfg);
# just get the result in list
my @dir = $sftp->local_ls('/local/dir');
# pass additional parameters and get the result as scalar (array ref) 
my $ar2 = $sftp->local_ls('/local/dir',undef,
      {file_pat=>'pdf$', dir_pat=>'^f'}
   );
# process the file in proc_file sub routine
$sftp->local_ls('/local/dir',\&proc_file);

Return: @r or \@r depends on the caller subroutine.

This methods fetches a directory listing of $ldr.

If $sr is specified, for each entry in the directory, $sr will be called and given a reference to a hash with three keys: filename, the name of the entry in the directory listing; longname, an entry in a "long" listing like ls -l; and a, a Net::SFTP::Attributes object, which contains the file attributes of the entry (atime, mtime, permissions, etc.).

If $subref is not specified, returns a list of directory entries, each of which is a reference to a hash as described in the previous paragraph.

HISTORY

• Version 0.10

  This version includes the rget, rput and local_ls methods. It is released on 07/12/2005.

  07/13/2005 (htu) - changed rput so that it is passing a Net::SFTP::Attributes object to do_mkdir. Changed version to 0.11.

SEE ALSO (some of docs that I check often)

Data::Describe, Oracle::Loader, CGI::Getopt, File::Xcopy

AUTHOR

Copyright (c) 2005 Hanming Tu. All rights reserved.

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)

cpanm Net::SFTP::Recursive

perl -MCPAN -e shell
install Net::SFTP::Recursive