From 2d5707c7479eacb3b1ad98e01b53f56a88f8fb78 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 18:14:31 +0200 Subject: Adding upstream version 3.2.7. Signed-off-by: Daniel Baumann --- doc/rsync.sgml | 351 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 351 insertions(+) create mode 100644 doc/rsync.sgml (limited to 'doc/rsync.sgml') diff --git a/doc/rsync.sgml b/doc/rsync.sgml new file mode 100644 index 0000000..0f90059 --- /dev/null +++ b/doc/rsync.sgml @@ -0,0 +1,351 @@ + + + + rsync + + 1996 -- 2002 + Martin Pool + Andrew Tridgell + + + Martin + Pool + + + + + Introduction + + rsync is a flexible program for efficiently copying files or + directory trees. + + rsync has many options to select which files will be copied + and how they are to be transferred. It may be used as an + alternative to ftp, http, scp or rcp. + + The rsync remote-update protocol allows rsync to transfer just + the differences between two sets of files across the network link, + using an efficient checksum-search algorithm described in the + technical report that accompanies this package. + + Some of the additional features of rsync are: + + + + + support for copying links, devices, owners, groups and + permissions + + + + + + exclude and exclude-from options similar to GNU tar + + + + + + a CVS exclude mode for ignoring the same files that CVS would ignore + + + + + can use any transparent remote shell, including rsh or ssh + + + + + does not require root privileges + + + + + pipelining of file transfers to minimize latency costs + + + + + support for anonymous or authenticated rsync servers (ideal for + mirroring) + + + + + + + + + Using rsync +
+ + Introductory example + + + + Probably the most common case of rsync usage is to copy files + to or from a remote machine using + ssh as a network transport. In + this situation rsync is a good alternative to + scp. + + + + The most commonly used arguments for rsync are + + + + + + + Be verbose. Primarily, display the name of each file as it is copied. + + + + + + + + + Reproduce the structure and attributes of the origin files as exactly + as possible: this includes copying subdirectories, symlinks, special + files, ownership and permissions. (@xref{Attributes to + copy}.) + + + + + + + + + + + Compress network traffic, using a modified version of the + @command{zlib} library. + + + Display a progress indicator while files are transferred. This should + normally be omitted if rsync is not run on a terminal. + +
+ + + + +
+ Local and remote + + There are six different ways of using rsync. They + are: + + + + + + + + for copying local files. This is invoked when neither + source nor destination path contains a @code{:} separator + + + + for copying from the local machine to a remote machine using + a remote shell program as the transport (such as rsh or + ssh). This is invoked when the destination path contains a + single @code{:} separator. + + + + for copying from a remote machine to the local machine + using a remote shell program. This is invoked when the source + contains a @code{:} separator. + + + + for copying from a remote rsync server to the local + machine. This is invoked when the source path contains a @code{::} + separator or a @code{rsync://} URL. + + + + for copying from the local machine to a remote rsync + server. This is invoked when the destination path contains a @code{::} + separator. + + + + for listing files on a remote machine. This is done the + same way as rsync transfers except that you leave off the + local destination. + + + + +Note that in all cases (other than listing) at least one of the source +and destination paths must be local. + + +Any one invocation of rsync makes a copy in a single direction. rsync +currently has no equivalent of @command{ftp}'s interactive mode. + +@cindex @sc{nfs} +@cindex network filesystems +@cindex remote filesystems + + +rsync's network protocol is generally faster at copying files than +network filesystems such as @sc{nfs} or @sc{cifs}. It is better to +run rsync on the file server either as a daemon or over ssh than +running rsync giving the network directory. + +
+ + + + + + Frequently asked questions + + + + + + + + + + Are there mailing lists for rsync? + + + + Yes, and you can subscribe and unsubscribe through a + web interface at + http://lists.samba.org/ + + + + If you are having trouble with the mailing list, please + send mail to the administrator + + rsync-admin@lists.samba.org + + not to the list itself. + + + + The mailing list archives are searchable. Use + Google and prepend + the search with site:lists.samba.org + rsync, plus relevant keywords. + + + + + + + + + Why is rsync so much bigger when I build it with + gcc? + + + + + On gcc, rsync builds by default with debug symbols + included. If you strip both executables, they should end + up about the same size. (Use make + install-strip.) + + + + + + + + Is rsync useful for a single large file like an ISO image? + + + + Yes, but note the following: + + + Background: A common use of rsync is to update a file (or set of files) in one location from a more + correct or up-to-date copy in another location, taking advantage of portions of the files that are + identical to speed up the process. (Note that rsync will transfer a file in its entirety if no copy + exists at the destination.) + + + (This discussion is written in terms of updating a local copy of a file from a correct file in a + remote location, although rsync can work in either direction.) + + + The file to be updated (the local file) must be in a destination directory that has enough space for + two copies of the file. (In addition, keep an extra copy of the file to be updated in a different + location for safety -- see the discussion (below) about rsync's behavior when the rsync process is + interrupted before completion.) + + + The local file must have the same name as the remote file being sync'd to (I think?). If you are + trying to upgrade an iso from, for example, beta1 to beta2, rename the local file to the same name + as the beta2 file. *(This is a useful thing to do -- only the changed portions will be + transmitted.)* + + + The extra copy of the local file kept in a different location is because of rsync's behavior if + interrupted before completion: + + + * If you specify the --partial option and rsync is interrupted, rsync will save the partially + rsync'd file and throw away the original local copy. (The partially rsync'd file is correct but + truncated.) If rsync is restarted, it will not have a local copy of the file to check for duplicate + blocks beyond the section of the file that has already been rsync'd, thus the remainder of the rsync + process will be a "pure transfer" of the file rather than taking advantage of the rsync algorithm. + + + * If you don't specify the --partial option and rsync is interrupted, rsync will throw away the + partially rsync'd file, and, when rsync is restarted starts the rsync process over from the + beginning. + + + Which of these is most desirable depends on the degree of commonality between the local and remote + copies of the file *and how much progress was made before the interruption*. + + + The ideal approach after an interruption would be to create a new file by taking the original file + and deleting a portion equal in size to the portion already rsync'd and then appending *the + remaining* portion to the portion of the file that has already been rsync'd. (There has been some + discussion about creating an option to do this automatically.) + + The --compare-dest option is useful when transferring multiple files, but is of no benefit in + transferring a single file. (AFAIK) + + *Other potentially useful information can be found at: + -[3]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFile + + This answer, formatted with "real" bullets, can be found at: + -[4]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFileFAQ* + + + + + + + + + + Other Resources + + + + -- cgit v1.2.3