File::RsyncP(3pm)

1File::RsyncP(3)       User Contributed Perl Documentation      File::RsyncP(3)
2
3
4

NAME

6       File::RsyncP - Perl Rsync client
7

SYNOPSIS

9           use File::RsyncP;
10
11           my $rs = File::RsyncP->new({
12                       logLevel   => 1,
13                       rsyncCmd   => "/bin/rsync",
14                       rsyncArgs  => [
15                               "--numeric-ids",
16                               "--perms",
17                               "--owner",
18                               "--group",
19                               "--devices",
20                               "--links",
21                               "--ignore-times",
22                               "--block-size=700",
23                               "--relative",
24                               "--recursive",
25                               "-v",
26                           ],
27                   });
28
29           #
30           # Receive files from remote srcDirectory to local destDirectory
31           # by running rsyncCmd with rsyncArgs.
32           #
33           $rs->remoteStart(1, srcDirectory);
34           $rs->go(destDirectory);
35           $rs->serverClose;
36
37           #
38           # Send files to remote destDirectory from local srcDirectory
39           # by running rsyncCmd with rsyncArgs.
40           #
41           $rs->remoteStart(0, destDirectory);
42           $rs->go(srcDirectory);
43           $rs->serverClose;
44
45           #
46           # Receive files from a remote module to local destDirectory by
47           # connecting to an rsyncd server.  ($module is the name from
48           # /etc/rsyncd.conf.)
49           #
50           my $port = 873;
51           $rs->serverConnect($host, $port);
52           $rs->serverService($module, $authUser, $authPasswd, 0);
53           $rs->serverStart(1, ".");
54           $rs->go(destDirectory);
55           $rs->serverClose;
56
57           #
58           # Get finals stats.  This is a hashref containing elements
59           # totalRead, totalWritten, totalSize, plus whatever the FileIO
60           # module might add.
61           #
62           my $stats = $rs->statsFinal;
63

DESCRIPTION

65       File::RsyncP is a perl implementation of an Rsync client.  It is
66       compatible with Rsync 2.5.5 - 2.6.3 (protocol versions 26-28).  It can
67       send or receive files, either by running rsync on the remote machine,
68       or connecting to an rsyncd deamon on the remote machine.
69
70       What use is File::RsyncP?  The main purpose is that File::RsyncP
71       separates all file system I/O into a separate module, which can be
72       replaced by any module of your own design.  This allows rsync
73       interfaces to non-filesystem data types (eg: databases) to be developed
74       with relative ease.
75
76       File::RsyncP was initially written to provide an Rsync interface for
77       BackupPC, <http://backuppc.sourceforge.net>.  See BackupPC for
78       programming examples.
79
80       File::RsyncP does not yet provide a command-line interface that mimics
81       native Rsync.  Instead it provides an API that makes it possible to
82       write simple scripts that talk to rsync or rsyncd.
83
84       The File::RsyncP::FileIO module contains the default file system access
85       functions.  File::RsyncP::FileIO may be subclassed or replaced by a
86       custom module to provide access to non-filesystem data types.
87
88   Getting Started
89       First some background.  When you run rsync is parses its command-line
90       arguments, then it either connects to a remote rsyncd daemon, or runs
91       an rsync on the remote machine via ssh or rsh.  At this point there are
92       two rsync processes: the one you invoked and the one on the remote
93       machine.  The one on the local machine is called the client, and the
94       one on the remote machine is the server.  One side (either the client
95       or server) will send files and the other will receive files.  The
96       sending rsync generates a file list and sends it to the receiving side.
97       The receiving rsync will fork a child process.
98
99       File::RsyncP does not (yet) have a command-line script that mimics
100       rsync's startup processing.  Think of File::RsyncP as one level below
101       the command-line rsync.  File::RsyncP implements the client side of the
102       connection, and File::RsyncP knows how to run the remote side (eg, via
103       rsh or ssh) or to connect to a remote rsyncd daemon.  File::RsyncP
104       automatically adds the internal --server and --sender options (if
105       necessary) to the options passed to the remote rsync.
106
107       To initiate any rsync session the File::RsyncP->new function should be
108       called.  It takes a hashref of parameters:
109
110       logLevel
111           An integer level of verbosity.  Zero means be quiet, 1 will give
112           some general information, 2 will some output per file, higher
113           values give more output.  10 will include byte dumps of all data
114           read/written, which will make the log output huge.
115
116       rsyncCmd
117           The command to run the remote peer of rsync.  By default the
118           rsyncArgs are appended to the rsyncCmd to create the complete
119           command before it is run.  This behavior is affected by
120           rsyncCmdType.
121
122           rsyncCmd can either be a single string giving the path of the rsync
123           command to run (eg: /bin/rsync) or a list containing the command
124           and arguments, eg:
125
126               rsyncCmd => [qw(
127                   /bin/ssh -l user host /bin/rsync
128               )],
129
130           or:
131
132               rsyncCmd => ["/bin/ssh", "-l", $user, $host, "/bin/rsync"],
133
134           Also, rsyncCmd can also be set to a code reference (ie: a perl
135           sub).  In this case the code is called without arguments or other
136           processing.  It is up to the perl code you supply to exec() the
137           remote rsync.
138
139           This option is ignored if you are connecting to an rsyncd daemon.
140
141       rsyncCmdType
142           By default the complete remote rsync command is created by taking
143           rsyncCmd and appending rsyncArgs.  This beavhior can be modified by
144           specifying certain values for rsyncCmdType:
145
146           'full'
147               rsyncCmd is taken to be the complete command, including all
148               rsync arguments.  It is the caller's responsibility to build
149               the correct remote rsync command, togheter will all the rsync
150               arguments.  You still need to specify rsyncArgs, so the local
151               File::RsyncP knows how to behave.
152
153           'shell'
154               rsyncArgs are shell escaped before appending to rsyncCmd.
155
156           This option is ignored if you are connecting to an rsyncd daemon.
157
158       rsyncArgs
159           A list of rsync arguments.  The full remote rsync command that is
160           run will be rsyncCmd appended with --server (and optionally
161           --sender if the remote is a sender) and finally all of rsyncArgs.
162
163       protocol_version
164           What we advertize our protocol version to be.  Default is 28.
165
166       logHandler
167           A subroutine reference to a function that handles all the log
168           messages.  The default is a subroutine that prints the messages to
169           STDERR.
170
171       pidHandler
172           An optional subroutine reference to a function that expects two
173           integers: the pid of the rsync process (ie: the pid on the local
174           machine that is likely ssh) and the child pid when we are receiving
175           files.  If defined, this function is called once when the rsync
176           process is forked, and again when the child is forked during
177           receive.
178
179       fio The file IO object that will handle all the file system IO.  The
180           default is File::RsyncP::FileIO->new.
181
182           This can be replaced with a new module of your choice, or you can
183           subclass File::RsyncP::FileIO.
184
185       timeout
186           Timeout in seconds for IO.  Default is 0, meaning no timeout.  Uses
187           alarm() and it is the caller's responsbility to catch the alarm
188           signal.
189
190       doPartial
191           If set, a partial rsync is done.  This is to support resuming full
192           backups in BackupPC.  When doPartial is set, the --ignore-times
193           option can be set on a per-file basis.  On each file in the file
194           list, File::RsyncP::FileIO->ignoreAttrOnFile() is called on each
195           file, and this returns whether or not attributes should be ignored
196           on that file.  If ignoreAttrOnFile() returns 1 then it's as though
197           --ignore-times was set for that file.
198
199       An example of calling File::RsyncP->new is:
200
201           my $rs = File::RsyncP->new({
202                       logLevel   => 1,
203                       rsyncCmd => ["/bin/rsh", $host,  "-l", $user, "/bin/rsync"],
204                       rsyncArgs  => [
205                               "--numeric-ids",
206                               "--perms",
207                               "--owner",
208                               "--group",
209                               "--devices",
210                               "--links",
211                               "--ignore-times",
212                               "--block-size=700",
213                               "--relative",
214                               "--recursive",
215                               "-v",
216                           ],
217                   });
218
219       A fuller example showing most of the parameters and qw() for the
220       rsyncArgs is:
221
222           my $rs = File::RsyncP->new({
223                       logLevel   => 1,
224                       rsyncCmd => ["/bin/rsh", $host,  "-l", $user, "/bin/rsync"],
225                       rsyncArgs  => [qw(
226                               --numeric-ids
227                               --perms
228                               --owner
229                               --group
230                               --devices
231                               --links
232                               --ignore-times
233                               --block-size=700
234                               --relative
235                               --recursive
236                               -v
237                           )],
238                       logHandler => sub {
239                               my($str) = @_;
240                               print MyHandler "log: $str\n";
241                           };
242                       fio        => File::RsyncP::FileIO->new({
243                                       logLevel   => 1,
244                                   });
245
246                   });
247
248   Talking to a remote Rsync
249       File::RsyncP can talk to a remote rsync using this sequence of
250       functions:
251
252       remoteStart(remoteSend, remoteDir)
253           Starts the remote server by executing the command specified in the
254           rsyncCmd parameter to File::RsyncP->new, together with the
255           rsyncArgs.
256
257           If the client is receiving files from the server then remoteSend
258           should be non-zero and remoteDir is the source directory on the
259           remote machine.  If the client is sending files to the remote
260           server then remoteSend should be zero and remoteDir is the
261           destination directory on the remote machine.  Returns undef on
262           success and non-zero on error.
263
264       go(localDir)
265           Run the client rsync.  localDir is the source directory on the
266           local machine if the client is sending files, or it is the
267           destination directory on the local machine if the client is
268           receiving files.  Returns undef on success.
269
270       serverClose()
271           Call this after go() to finish up.  Returns undef on success.
272
273       statsFinal()
274           This can be optionally called to pickup the transfer stats.  It
275           returns a hashref containing elements totalRead, totalWritten,
276           totalSize, plus whatever the FileIO module might add.
277
278       abort()
279           Call this function to abort the transfer.
280
281       An example of sending files to a remote rsync is:
282
283           #
284           # Send files to remote destDirectory from local srcDirectory
285           # by running rsyncCmd with rsyncArgs.
286           #
287           $rs->remoteStart(0, destDirectory);
288           $rs->go(srcDirectory);
289           $rs->serverClose;
290
291       An example of receiving files from a remote rsync is:
292
293           #
294           # Receive files from remote srcDirectory to local destDirectory
295           # by running rsyncCmd with rsyncArgs.
296           #
297           $rs->remoteStart(1, srcDirectory);
298           $rs->go(destDirectory);
299           $rs->serverClose;
300
301   Talking to a remote Rsync daemon
302       File::RsyncP can connect to a remote Rsync daemon using this sequence
303       of functions:
304
305       serverConnect(host, port)
306           Connect to the Rsync daemon on the given string host and integer
307           port. The port argument is optional and it defaults to 873. On
308           error serverConnect returns a string error message. On success it
309           returns undef.
310
311       serverService(module, authUser, authPasswd, authRequired)
312           Specify which module to use (a "module" is the symbolic name that
313           appears inside "[...]" /etc/rsyncd.conf), the user's credentials
314           (authUser and authPasswd) and whether authorization is mandatory
315           (authRequired). If set to a non-zero value, authRequired ensures
316           that the remote Rsync daemon requires authentication.  If
317           necessary, this is to ensure that you don't connect to an insecure
318           Rsync daemon.  The auth arguments are optional if the selected
319           rsyncd module doesn't require authentication.
320
321           See the rsyncd.conf manual page for more information.  For example,
322           if a host called navajo had a /etc/rsyncd.conf contains these
323           lines:
324
325              [test]
326                      path = /data/test
327                      comment = test module
328                      auth users = craig, celia
329                      secrets file = /etc/rsyncd.secrets
330
331           and /etc/rsyncd.secrets contained:
332
333               craig:xxx
334
335           then you could connect to this rsyncd using:
336
337               $rs->serverConnect("navajo", 873);
338               $rs->serverService("test", "craig", "xxx", 0);
339
340           The value of the authRequired argument doesn't matter in this case.
341
342           On error serverService returns a string error message.  On success
343           it returns undef.
344
345       serverStart(remoteSend, remoteDir)
346           Starts the remote server.  If the client is receiving files from
347           the server then remoteSend should be non-zero.  If the client is
348           sending files to the remote server then remoteSend should be zero.
349           The remoteDir typically starts with the module name, followed by
350           any directory below the module.  Or remoteDir can be just "."  to
351           refer to the top-level module directory.  Returns undef on success.
352
353       go(localDir)
354           Run the client rsync.  localDir is the source directory on the
355           local machine if the client is sending files, or it is the
356           destination directory on the local machine if the client is
357           receiving files.  Returns undef on success.
358
359       serverClose()
360           Call this after go() to finish up.  Returns undef on success.
361
362       abort()
363           Call this function to abort the transfer.
364
365       An example of sending files to a remote rsyncd daemon is:
366
367           #
368           # Send files to a remote module from a local srcDirectory by
369           # connecting to an rsyncd server.  ($module is the name from
370           # /etc/rsyncd.conf.)
371           #
372           my $port = 873;
373           $rs->serverConnect($host, $port);
374           $rs->serverService($module, $authUser, $authPasswd);
375           $rs->serverStart(0, ".");
376           $rs->go(srcDirectory);
377           $rs->serverClose;
378
379       An example of receiving files from a remote rsyncd daemon is:
380
381           #
382           # Receive files from a remote module to local destDirectory by
383           # connecting to an rsyncd server.  ($module is the name from
384           # /etc/rsyncd.conf.)
385           #
386           my $port = 873;
387           $rs->serverConnect($host, $port);
388           $rs->serverService($module, $authUser, $authPasswd);
389           $rs->serverStart(1, ".");
390           $rs->go(destDirectory);
391           $rs->serverClose;
392

LIMITATIONS

394       The initial version of File::RsyncP (0.10) has a number of limitations:
395
396       ·   File::RsyncP only implements a modest subset of Rsync options and
397           features.  In particular, as of 0.10 only these options are
398           supported:
399
400                   --numeric-ids
401                   --perms|-p
402                   --owner|-o
403                   --group|-g
404                   --devices|D
405                   --links|-l
406                   --ignore-times|I
407                   --block-size=i
408                   --verbose|-v
409                   --recursive|-r
410                   --relative|-R
411
412           Hardlinks are currently not supported.  Other options that only
413           affect the remote side will work correctly since they are passed to
414           the remote Rsync unchanged.
415
416       ·   Also, --relative semantics are not implemented to match rsync, and
417           the trailing "/" behavior of rsync (meaning directory contents, not
418           the directory itself) are not implemented in File::RsyncP.
419
420       ·   File::RsyncP does not yet provide a command-line interface that
421           mimics native Rsync.
422
423       ·   File::RsyncP might work with slightly earlier versions of Rsync but
424           has not been tested.  It certainly will not work with antique
425           versions of Rsync.
426
427       ·   File::RsyncP does not compute file deltas (ie: it behaves as though
428           --whole-file is specified) or implement exclude or include options
429           when sending files.  File::RsyncP does handle file deltas and
430           exclude and include options when receiving files.
431
432       ·   File::RsyncP does not yet implement server functionality (acting
433           like the remote end of a connection or a daemon).  Since the
434           protocol is relatively symmetric this is not difficult to add, so
435           it should appear in a future version.
436

AUTHOR

438       File::RsyncP::FileList was written by Craig Barratt
439       <cbarratt@users.sourceforge.net> based on rsync 2.5.5.
440
441       Rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
442       Mackerras.  It is available under a GPL license.  See
443       http://rsync.samba.org.
444

LICENSE

446       This program is free software; you can redistribute it and/or modify it
447       under the terms of the GNU General Public License as published by the
448       Free Software Foundation; either version 2 of the License, or (at your
449       option) any later version.
450
451       This program is distributed in the hope that it will be useful, but
452       WITHOUT ANY WARRANTY; without even the implied warranty of
453       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
454       General Public License for more details.
455
456       You should have received a copy of the GNU General Public License in
457       the LICENSE file along with this program; if not, write to the Free
458       Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
459       02111-1307 USA.
460

NAME

SYNOPSIS

DESCRIPTION

LIMITATIONS

AUTHOR

LICENSE

SEE ALSO