MAN page from Old RedHat 7.X perl-File-Remote-1.10-8.i386.rpm

Remote

Section: User Contributed Perl Documentation (3)
Updated: perl v5.6.0
Index

NAME

File::Remote - Read/write/edit remote files transparently

SYNOPSIS

   #     # Two ways to use File::Remote   # First, the object-oriented style   #     use File::Remote;   my $remote = new File::Remote;   $remote->settmp('/var/tmp');         # custom tmp dir

   # Standard filehandles   $remote->open(FILE, '>>host:/remote/file') or die "Open: $!\n";   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 "Copy: $!\n";   $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 methods   my $secure = new File::Remote;   $secure->setrsh('/local/bin/ssh');   # for secure   $secure->setscp('/local/bin/scp');   # connections

   $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 "Open: $!\n";   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!

DESCRIPTION

This module takes care of dealing with files regardless of whetherthey're local or remote. It allows you to create and edit files withouthaving to worry about their physical location on the network. If a filepassed into a function is of the form 'host:/path/to/file', thenFile::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 andpasses calls directly through to Perl's core functions.

The nice thing about this module is that you can use it for all yourfile 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 filesin your code. Plus, if you use the function-oriented interface along withthe :replace tag, you can actually redefine the Perl builtin filefunctions so that your existing Perl scripts can automatically handleremote files with no re-engineering!

There are two ways to program with File::Remote, an object-orientedstyle and a function-oriented style. Both methods work equally well,it's just a matter of taste. One advantage of the object-orientedmethod is that this allows you to read and write from different serversusing different methods (eg, rsh vs. ssh) simultaneously:

   # Object-oriented method   use File::Remote;   my $remote = new File::Remote;   my $secure = new File::Remote;   $secure->setrsh('/local/bin/ssh');   $secure->setrcp('/local/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 isan 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 tagcalled :replace which will actually replace the Perl builtinfunctions:

   # 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');

Since File::Remote will pass calls to local files straight throughto Perl's core functions, you'll be able to do all this ``transparently''and not care about the locations of the files. Plus, as mentioned above,this has the big advantage of making your existing Perl scripts capableof dealing with remote files without having to rewrite any code.

FUNCTIONS

Below are each of the functions you can make use of with File::Remote.Remember, for the function-oriented style, unless you use the :replacetag 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.

setrsh(prog) ; setrcp(prog)

These set what to use for remote shell and copy calls, needed tomanipulate remote files. The defaults are /usr/bin/rsh and /usr/bin/rcp.For security, you can use ssh and scp (if you have them). In both cases,you need to make sure you have passwordless access to the remote hostsholding the files to be manipulated.

settmp(dir)

This sets the directory to use for temporary files. This is needed asa repository during remote reads and writes.

open(handle, file) ; close(handle)

Used to open and close files just like the Perl builtins. These functionsaccept both string filehandles and typeglob references.

touch(file)

Updates the modification time on a file, or creates it if it doesn't exist.

mkdir(dir [, mode]) ; rmdir(dir [, recurse])

Create a dir with optional octal mode [mode]; remove a dir tree optionallyrecursively. By default, rmdir works recursively, and the mode of the newdir from mkdir depends on your umask.

copy(file1, file2)

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).

move(file1, file2)

Moves a file ala File::Copy. You can also address it as 'mv'(if you import the :aliases tag).

chmod(mode, file) ; chown(owner, group, file)

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).

backup(file, [file|suffix])

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 localor 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 returnssuccess or failure.

append(file, `@data`) , prepend(file, `@data`)

Similar to writefile(), only these don't overwrite the file, theseeither append or prepend the data to the file.

EXAMPLES

Here's some more examples of how to use this module:

1. Add a new user to /etc/passwd on your server

This might be useful if you've got some type of web-based newuserprogram 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);

2. Securely copy over a bunch of files

Hopefully you would use loops and variable names to make any actual code lookmuch cleaner...

   # Object-oriented method   use File::Remote   my $secure = new File::Remote;

   # Setup secure connections and tmpdir   $secure->setrsh('/local/bin/ssh');   $secure->setrcp('/local/bin/scp');   $secure->settmp('/var/stmp');

   # 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');

3. Use rsync w/ ssh for really fast transfers

Here we're assuming we're getting some huge datastream from someother 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   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

NOTES

File::Remote only works on UNIX systems.

The main caveat to File::Remote is that you have to have rsh/rcp or ssh/scpaccess to the hosts you want to manipulate files on. Make sure you considerthe security implications of this, especially if you live outside a firewall.

Enabling autoflush ($|) won't have any effect on remote filehandles, sincethe 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/rcpor their equivalents are executable. To change this, see the source.

BUGS

Perl scripts that are tainted or setuid might not work with File::Remotebecause of its reliance on system() calls, depending on your %ENV. Towork around this, simply add an ``undef %ENV'' statement to the top ofyour 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.

AUTHOR

This module is free software; you may copy this under the terms ofthe GNU General Public License, or the Artistic License, copies ofwhich should have accompanied your Perl kit.

Index

NAME
SYNOPSIS
DESCRIPTION
FUNCTIONS
setrsh(prog) ; setrcp(prog)
settmp(dir)
open(handle, file) ; close(handle)
touch(file)
mkdir(dir [, mode]) ; rmdir(dir [, recurse])
copy(file1, file2)
move(file1, file2)
chmod(mode, file) ; chown(owner, group, file)
unlink(file)
backup(file, [file|suffix])
readfile(file) , writefile(file, @data)
append(file, @data) , prepend(file, @data)
EXAMPLES
1. Add a new user to /etc/passwd on your server
2. Securely copy over a bunch of files
3. Use rsync w/ ssh for really fast transfers
NOTES
BUGS
AUTHOR

This document was created byman2html,using the manual pages.