From eb06fa95e422822e67e986e5e9c3818afbba45bb Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Tue, 18 Dec 2001 06:45:28 +0000 Subject: [PATCH] Documentation fixes based on mail from Edward Welbourne, and an attempted explanation of rsync's symbolic-link handling. --- rsync.yo | 103 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 64 insertions(+), 39 deletions(-) diff --git a/rsync.yo b/rsync.yo index 4b4b03ef..c53aaaf6 100644 --- a/rsync.yo +++ b/rsync.yo @@ -19,7 +19,7 @@ manpagedescription() rsync is a program that behaves in much the same way that rcp does, but has many more options and uses the rsync remote-update protocol to -greatly speedup file transfers when the destination file already +greatly speed up file transfers when the destination file already exists. The rsync remote-update protocol allows rsync to transfer just the @@ -81,7 +81,7 @@ Once installed you can use rsync to any machine that you can use rsh to. rsync uses rsh for its communications, unless both the source and destination are local. -You can also specify an alternative to rsh, by either using the -e +You can also specify an alternative to rsh, either by using the -e command line option, or by setting the RSYNC_RSH environment variable. One common substitute is to use ssh, which offers a high degree of @@ -139,10 +139,10 @@ It is also possible to use rsync without using rsh or ssh as the transport. In this case you will connect to a remote rsync server running on TCP port 873. -You may establish the connetcion via a web proxy by setting the +You may establish the connection via a web proxy by setting the environment variable RSYNC_PROXY to a hostname:port pair pointing to -your web proxy. Note that your web proxy must allow proxying to port -873, this must be configured in your proxy servers ruleset. +your web proxy. Note that your web proxy's configuration must allow +proxying to port 873. Using rsync in this way is the same as using it with rsh or ssh except that: @@ -226,8 +226,8 @@ verb( --backup-dir make backups into this directory --suffix=SUFFIX override backup suffix -u, --update update only (don't overwrite newer files) - -l, --links preserve soft links - -L, --copy-links treat soft links like regular files + -l, --links copy symlinks as symlinks + -L, --copy-links copy the referent of symlinks --copy-unsafe-links copy links outside the source tree --safe-links ignore links outside the destination tree -H, --hard-links preserve hard links @@ -378,17 +378,16 @@ dit(bf(-u, --update)) This forces rsync to skip any files for which the destination file already exists and has a date later than the source file. -dit(bf(-l, --links)) This tells rsync to recreate symbolic links on the -remote system to be the same as the local system. Without this -option, all symbolic links are skipped. +dit(bf(-l, --links)) When symlinks are encountered, recreate the +symlink on the destination. -dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just -like ordinary files. +dit(bf(-L, --copy-links)) When symlinks are encountered, the file that +they point to is copied, rather than the symlink. -dit(bf(--copy-unsafe-links)) This tells rsync to treat symbolic links that -point outside the source tree like ordinary files. Absolute symlinks are -also treated like ordinary files, and so are any symlinks in the source -path itself when --relative is used. +dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of +symbolic links that point outside the source tree. Absolute symlinks +are also treated like ordinary files, and so are any symlinks in the +source path itself when --relative is used. dit(bf(--safe-links)) This tells rsync to ignore any symbolic links which point outside the destination tree. All absolute symlinks are @@ -414,16 +413,15 @@ the source and target are on the local machine. dit(bf(-p, --perms)) This option causes rsync to update the remote permissions to be the same as the local permissions. -dit(bf(-o, --owner)) This option causes rsync to update the remote owner -of the file to be the same as the local owner. This is only available -to the super-user. Note that if the source system is a daemon using chroot, -the --numeric-ids option is implied because the source system cannot get -access to the usernames. +dit(bf(-o, --owner)) This option causes rsync to set the owner of the +destination file to be the same as the source file. On most systems, +only the super-user can set file ownership. -dit(bf(-g, --group)) This option causes rsync to update the remote group -of the file to be the same as the local group. If the receving system is -not running as the super-user, only groups that the receiver is a member of -will be preserved (by group name, not group id number). +dit(bf(-g, --group)) This option causes rsync to set the group of the +destination file to be the same as the source file. If the receiving +program is not running as the super-user, only groups that the +receiver is a member of will be preserved (by group name, not group id +number). dit(bf(-D, --devices)) This option causes rsync to transfer character and block device information to the remote system to recreate these @@ -551,8 +549,9 @@ quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state then files listed in a $HOME/.cvsignore are added to the list and any files listed in the CVSIGNORE environment variable (space delimited). -Finally in each directory any files listed in the .cvsignore file in -that directory are added to the list. +Finally, any file is ignored if it is in the same directory as a +.cvsignore file and matches one of the patterns listed therein. See +the bf(cvs(1)) manual for more information. dit(bf(--csum-length=LENGTH)) By default the primary checksum used in rsync is a very strong 16 byte MD4 checksum. In most cases you will @@ -609,21 +608,24 @@ what ownership to give files. The special uid 0 and the special group 0 are never mapped via user/group names even if the --numeric-ids option is not specified. -If the source system is a daemon using chroot, or if a user or group name -does not exist on the destination system, then the numeric id from the -source system is used instead. +If the source system is a daemon using chroot, or if a user or group +name does not exist on the destination system, then the numeric id +from the source system is used instead. dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO timeout in seconds. If no data is transferred for the specified time then rsync will exit. The default is 0, which means no timeout. -dit(bf(--daemon)) This tells rsync that it is to run as a rsync -daemon. If standard input is a socket then rsync will assume that it -is being run via inetd, otherwise it will detach from the current -terminal and become a background daemon. The daemon will read the -config file (/etc/rsyncd.conf) on each connect made by a client and -respond to requests accordingly. See the rsyncd.conf(5) man page for more -details. +dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The +daemon may be accessed using the bf(host::module) or +bf(rsync://host/module/) syntax. + +If standard input is a socket then rsync will assume that it is being +run via inetd, otherwise it will detach from the current terminal and +become a background daemon. The daemon will read the config file +(/etc/rsyncd.conf) on each connect made by a client and respond to +requests accordingly. See the rsyncd.conf(5) man page for more +details. dit(bf(--no-detach)) When running as a daemon, this option instructs rsync to not detach itself and become a background process. This @@ -706,7 +708,7 @@ manpagesection(EXCLUDE PATTERNS) The exclude and include patterns specified to rsync allow for flexible selection of which files to transfer and which files to skip. -rsync builds a ordered list of include/exclude options as specified on +rsync builds an ordered list of include/exclude options as specified on the command line. When a filename is encountered, rsync checks the name against each exclude/include pattern in turn. The first matching pattern is acted on. If it is an exclude pattern, then that file is @@ -759,7 +761,7 @@ itemize( part of an include option. The "- " part is discarded before matching. it() if the pattern is a single exclamation mark ! then the current - exclude list is reset, removing all previous exclude patterns. + include/exclude list is reset, removing all previously defined patterns. ) The +/- rules are most useful in exclude lists, allowing you to have a @@ -812,6 +814,29 @@ it() bf(rsync_delta.) data blocks for file update & change See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical reports. +manpagesection(SYMBOLIC LINKS) + +Three basic behaviours are possible when rsync encounters a symbolic +link in the source directory. + +By default, symbolic links are not transferred at all. A message +"skipping non-regular" file is emitted for any symlinks that exist. + +If bf(--links) is specified, then symlinks are recreated with the same +target on the destination. Note that bf(--archive) implies +bf(--links). + +If bf(--copy-links) is specified, then symlinks are "collapsed" by +copying their referent, rather than the symlink. + +rsync also distinguishes "safe" and "unsafe" symbolic links. An +example where this might be used is a web site mirror that wishes +ensure the rsync module they copy does not include symbolic links to +bf(/etc/passwd) in the public section of the site. Using +bf(--copy-unsafe-links) will cause any links to be copied as the file +they point to on the destination. Using bf(--safe-links) will cause +unsafe links to be ommitted altogether. + manpagesection(DIAGNOSTICS) rsync occasionally produces error messages that may seem a little -- 2.34.1