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)