setrsh(prog) ; setrcp(prog) ; settmp(dir)close(HANDLE)touch(file)unlink(file)readlink(file)readfile(file) , writefile(file, @data)
File::Remote - Read/write/edit remote files transparently
# # Two ways to use File::Remote # First, the object-oriented style # use File::Remote; my $remote = new File::Remote;
# Standard filehandles $remote->open(FILE, '>>host:/remote/file') or die $!; print FILE "Here's a line that's added.\n"; $remote->close(FILE);
# Create a new file and change its permissions
$remote->mkdir('host:/remote/dir');
$remote->touch('host:/remote/dir/file');
$remote->chown('root', 'other', 'host:/remote/dir/file');
$remote->chmod('0600', 'host:/remote/dir/file');
# Move files around
$remote->copy('/local/file', 'host:/remote/file') or warn $!;
$remote->move('host:/remote/file', '/local/file');
# Read and write whole files
my @file = $remote->readfile('host:/remote/file');
$remote->writefile('/local/file', @file);
# Backup a file with a suffix
$remote->backup('host:/remote/oldfile', 'save');
# Use secure connection methods
my $secure = new File::Remote (rsh => '/usr/local/bin/ssh',
rcp => '/usr/local/bin/scp');
$secure->unlink('/local/file');
$secure->rmdir('host:/remote/dir');
# # Next, the function-based style. Here, we can use the # special :replace tag to overload Perl builtins! # use File::Remote qw(:replace); # special :replace tag
open(REMOTE, 'host:/remote/file') or die $!; print while (<REMOTE>); close(REMOTE);
open(LOCAL, '>>/local/file'); # still works! print LOCAL "This is a new line.\n"; close(LOCAL);
mkdir('host:/remote/dir', 0755);
unlink('host:/remote/file');
unlink('/local/file'); # still works too!
symlink('host:/remote/src', 'host:/remote/dest');
This module takes care of dealing with files regardless of whether they're local or remote. It allows you to create and edit files without having to worry about their physical location on the network. If a file passed into a function is of the form 'host:/path/to/file', then File::Remote uses rsh/rcp (or ssh/scp, depending on how you configure it) to edit the file remotely. Otherwise, it assumes the file is local and passes calls directly through to Perl's core functions.
The nice thing about this module is that you can use it for all your
file calls, since it handles both remote and local files transparently.
This means you don't have to put a whole bunch of checks for remote files
in your code. Plus, if you use the function-oriented interface along with
the :replace tag, you can actually redefine the Perl builtin file
functions so that your existing Perl scripts can automatically handle
remote files with no re-engineering!
There are two ways to program with File::Remote, an object-oriented style and a function-oriented style. Both methods work equally well, it's just a matter of taste. One advantage of the object-oriented method is that this allows you to read and write from different servers using different methods (eg, rsh vs. ssh) simultaneously:
# Object-oriented method use File::Remote; my $remote = new File::Remote; my $secure = new File::Remote (rsh => '/bin/ssh', rcp => '/bin/scp');
# Securely copy, write, and remove a file in one swoop... $remote->open(LOCAL, '/local/file') or die "Open failed: $!\n"; $secure->open(REMOTE, 'host:/remote/file') or die "Open failed: $!\n"; print REMOTE "$_" while (<LOCAL>);
$remote->close(LOCAL); $secure->close(REMOTE);
# And let's move some files around securely
$secure->move('/local/file', 'host:/remote/file');
$secure->copy('host:/remote/file', '/local/file');
Because the names for the File::Remote methods clash with the Perl builtins, if you use the function-oriented style with the :standard tag there is an extra 'r' added to the front of the function names. Thus, '$remote->open' becomes 'ropen' in the function-oriented version:
# Function-oriented method
use File::Remote qw(:standard); # use standard functions
setrsh('/local/bin/ssh');
setrcp('/local/bin/scp');
ropen(FILE, 'host:/remote/file') or die "Open failed: $!\n"; print while (<FILE>); rclose(FILE) or die "Close failed: $!\n";
runlink('host:/remote/file');
rmkdir('host:/remote/dir');
rchmod('0700', 'host:/remote/dir');
With the function-oriented interface there is also a special tag
called :replace which will actually replace the Perl builtin
functions:
# Replace Perl's file methods with File::Remote's use File::Remote qw(:replace);
open(FILE, '>host:/remote/file') or die "Open failed: $!\n"; print FILE "Hello, world!\n"; close(FILE) or die "Close failed: $!\n";
mkdir('/local/new/dir', '2775');
mkdir('host:/remote/new/dir');
chown('root', 'other', '/local/new/dir');
unlink('host:/remote/file');
This is pretty neat; since File::Remote will pass calls to local files straight through to Perl's core functions, you'll be able to do all this ``transparently'' and not care about the locations of the files. Plus, this has the big advantage of making your existing Perl scripts capable of dealing with remote files without having to rewrite any code.
Below are each of the functions you can make use of with File::Remote.
Remember, for the function-oriented style, unless you use the :replace
tag you'll have to add an extra 'r' to the start of each function name.
For all functions, the file arg can be either local or remote.
This is the main constructor when you're using the object-oriented method of calling. You can pass it three arguments which change how it works:
rsh - path to your rsh or ssh program rcp - path to your rcp or scp program tmp - path to your tmp directory
So, for example:
use File::Remote;
my $secure = File::Remote->new(rsh => '/usr/local/bin/ssh',
rcp => '/usr/local/bin/scp',
tmp => '/var/run');
$secure->copy($src, $dest);
The above would setup your $secure object so that calls to methods on it would use ssh and scp for connections.
setrsh(prog) ; setrcp(prog) ; settmp(dir)These perform the equivalent functionality to setting the above flags, for use in the function-oriented method of calling. So, if you were to decide you didn't want to use the OO method, but instead wanted to use the drop-in replacement function method (which I prefer):
use File::Remote qw(:replace);
setrsh('/usr/local/bin/ssh');
setrcp('/usr/local/bin/scp');
settmp('/var/run');
copy($src, $dest);
That chain of calls would have the exact same effect, only using the function-oriented format instead of the object-oriented format.
close(HANDLE)Used to open and close files just like the Perl builtins. These functions accept both string filehandles and typeglob references.
touch(file)Updates the modification time on a file, or creates it if it doesn't exist.
Create a dir with optional octal mode [mode]; remove a dir tree optionally recursively. By default, rmdir works recursively, and the mode of the new dir from mkdir depends on your umask.
Simply copies a file, just like File::Copy's function of the same name. You can also address it as 'cp' (if you import the :aliases tag).
Moves a file ala File::Copy. You can also address it as 'mv' (if you import the :aliases tag).
Change the permissions or the owner of a file.
unlink(file)Remove a file. You can also address it as 'rm' (if you import the :aliases tag).
Create a hard link between two files. The caveat to this function is that both files must be local, or both files must be remote.
Works just like link only creates symbolic instead of hard links.
readlink(file)This reads what a symbolic link points to, just like the Perl builtin.
This backs up a file, useful if you're going to be manipulating it. If you just call it without the optional second filename or suffix, the suffix 'bkup' will be added to the file. Either file can be local or remote; this is really just a front-end to File::Remote::copy().
readfile(file) , writefile(file, @data)These read and write whole files in one swoop, just like File::Slurp.
readfile() returns an array of the file, and writefile just returns
success or failure.
Similar to writefile(), only these don't overwrite the file, these either append or prepend the data to the file.
Here's some more examples of how to use this module:
This might be useful if you've got some type of web-based newuser program that runs on a host other than the one you have to edit /etc/passwd on:
# Function-oriented method use File::Remote qw(:replace);
$passwd = "server:/etc/passwd"; backup($passwd, 'old'); # back it up to be safe open(PASSWD, ">>$passwd") or die "Couldn't write $passwd: $!\n"; print PASSWD "$newuser_entry\n"; close(PASSWD);
Hopefully you would use loops and variable names to make any actual code look much cleaner...
# Object-oriented method
use File::Remote
my $secure = File::Remote->new(rsh => '/share/bin/ssh',
rcp => '/share/bin/scp',
tmp => '/var/tmp');
# Move files
$secure->move('client:/home/bob/.cshrc', 'client:/home/bob/.cshrc.old');
$secure->copy('/etc/skel/cshrc.user', 'client:/home/bob/.cshrc');
$secure->copy('/etc/skel/kshrc.user', 'client:/home/bob/.kshrc');
Here we're assuming we're getting some huge datastream from some
other process and having to dump it into a file in realtime.
Note that the remote file won't be updated until close() is called.
# Function-oriented, no :replace tag, so all functions # will be prefixed with an 'r' use File::Remote qw(:standard);
setrsh('/local/bin/ssh');
setrcp('/local/bin/rsync -z -e /local/bin/ssh');
settmp('/var/stmp');
$file = "server:/local/dir/some/huge/file";
ropen(REMOTE, ">>$file") or die "Couldn't write $file: $!\n";
while(<DATASTREAM>) {
print REMOTE $_;
}
rclose(REMOTE); # file is finally updated
File::Remote only works on UNIX systems.
The main caveat to File::Remote is that you have to have rsh/rcp or ssh/scp access to the hosts you want to manipulate files on. Make sure you consider the security implications of this, especially if you live outside a firewall.
Enabling autoflush ($|) won't have any effect on remote filehandles, since
the remote file is not synched until close() is called on the filehandle.
File::Remote does not support writing to remote pipes.
Because of speed, by default no checks are made as to whether or not rsh/rcp or their equivalents are executable. To change this, see the source.
Because of the internal implementation of open() on remote files, it
is not possible to read from an ever-growing remote file (``tail'' it).
Basically, a snapshot of the remote file is taken when you open it
for reading. Patches to overcome this limitation are welcomed.
Perl scripts that are tainted or setuid might not work with File::Remote
because of its reliance on system() calls, depending on your %ENV. To
work around this, simply add an ``undef %ENV'' statement to the top of
your script, which you should be doing anyways.
If you have a bug report or suggestion, please direct them to me (see below). Please be specific and include the version of File::Remote you're using.
$Id: Remote.pm,v 1.12 2000/11/30 00:29:53 nwiger Exp $
Copyright (c) 1998-2000 Nathan Wiger <nate@nateware.com>. All Rights Reserved.
This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.