X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/786c36876b9f0853063856974762e24fcc9e5cb5..ea5164d18118edc0d980795bfa760e5384c8d286:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 017fb26e..bc3b713f 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(25 Jan 2002)()() +manpage(rsync)(1)(26 Jan 2003)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -15,6 +15,8 @@ rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] +rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST + manpagedescription() rsync is a program that behaves in much the same way that rcp does, @@ -23,7 +25,7 @@ greatly speed up file transfers when the destination file already exists. The rsync remote-update protocol allows rsync to transfer just the -differences between two sets of files across the network link, using +differences between two sets of files across the network connection, using an efficient checksum-search algorithm described in the technical report that accompanies this package. @@ -42,7 +44,7 @@ itemize( manpagesection(GENERAL) -There are six different ways of using rsync. They are: +There are eight different ways of using rsync. They are: itemize( it() for copying local files. This is invoked when neither @@ -63,7 +65,19 @@ itemize( it() for copying from the local machine to a remote rsync server. This is invoked when the destination path contains a :: - separator. + separator or a rsync:// URL. + + it() for copying from a remote machine using a remote shell + program as the transport, using rsync server on the remote + machine. This is invoked when the source path contains a :: + separator and the --rsh=COMMAND (aka "-e COMMAND") option is + also provided. + + it() for copying from the local machine to a remote machine + using a remote shell program as the transport, using rsync + server on the remote machine. This is invoked when the + destination path contains a :: separator and the + --rsh=COMMMAND option is also provided. it() for listing files on a remote machine. This is done the same way as rsync transfers except that you leave off the @@ -77,11 +91,13 @@ manpagesection(SETUP) See the file README for installation instructions. -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. +Once installed, you can use rsync to any machine that you can access via +a remote shell (as well as some that you can access using the rsync +daemon-mode protocol). For remote transfers, rsync typically uses rsh +for its communications, but it may have been configured to use a +different remote shell by default, such as ssh. -You can also specify an alternative to rsh, either by using the -e +You can also specify any remote shell you like, 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 @@ -135,7 +151,7 @@ somehost.mydomain.com. (See the following section for more details.) manpagesection(CONNECTING TO AN RSYNC SERVER) -It is also possible to use rsync without using rsh or ssh as the +It is also possible to use rsync without a remote shell as the transport. In this case you will connect to a remote rsync server running on TCP port 873. @@ -144,12 +160,12 @@ environment variable RSYNC_PROXY to a hostname:port pair pointing to 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 +Using rsync in this way is the same as using it with a remote shell except that: itemize( it() you use a double colon :: instead of a single colon to - separate the hostname from the path. + separate the hostname from the path or a rsync:// URL. it() the remote server may print a message of the day when you connect. @@ -170,11 +186,61 @@ may be useful when scripting rsync. WARNING: On some systems environment variables are visible to all users. On those systems using --password-file is recommended. +manpagesection(CONNECTING TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM) + +It is sometimes useful to be able to set up file transfers using rsync +server capabilities on the remote machine, while still using rsh or +ssh for transport. This is especially useful when you want to connect +to a remote machine via ssh (for encryption or to get through a +firewall), but you still want to have access to the rsync server +features (see RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM, +below). + +From the user's perspective, using rsync in this way is the same as +using it to connect to an rsync server, except that you must +explicitly set the remote shell program on the command line with +--rsh=COMMAND. (Setting RSYNC_RSH in the environment will not turn on +this functionality.) + +In order to distinguish between the remote-shell user and the rsync +server user, you can use '-l user' on your remote-shell command: + +quote(rsync -av --rsh="ssh -l ssh-user" rsync-user@host::module[/path] local-path) + +The "ssh-user" will be used at the ssh level; the "rsync-user" will be +used to check against the rsyncd.conf on the remote host. + manpagesection(RUNNING AN RSYNC SERVER) -An rsync server is configured using a config file which by default is -called /etc/rsyncd.conf. Please see the rsyncd.conf(5) man page for more -information. +An rsync server is configured using a config file. Please see the +rsyncd.conf(5) man page for more information. By default the configuration +file is called /etc/rsyncd.conf, unless rsync is running over a remote +shell program and is not running as root; in that case, the default name +is rsyncd.conf in the current directory on the remote computer +(typically $HOME). + +manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM) + +See the rsyncd.conf(5) man page for full information on the rsync +server configuration file. + +Several configuration options will not be available unless the remote +user is root (e.g. chroot, setuid/setgid, etc.). There is no need to +configure inetd or the services map to include the rsync server port +if you run an rsync server only via a remote shell program. + +To run an rsync server out of a single-use ssh key, use the +"command=em(COMMAND)" syntax in the remote user's +authorized_keys entry, where command would be + +quote(rsync --server --daemon .) + +NOTE: rsync's argument parsing expects the trailing ".", so make sure +that it's there. If you want to use a rsyncd.conf(5)-style +configuration file other than the default, you can added a +--config option to the em(command): + +quote(rsync --server --daemon --config=em(file) .) manpagesection(EXAMPLES) @@ -185,7 +251,7 @@ files and mail folders, I use a cron job that runs quote(rsync -Cavz . arvidsjaur:backup) -each night over a PPP link to a duplicate directory on my machine +each night over a PPP connection to a duplicate directory on my machine "arvidsjaur". To synchronize my samba source trees I use the following Makefile @@ -200,7 +266,7 @@ quote( get:nl() sync: get put) this allows me to sync with a CVS directory at the other end of the -link. I then do cvs operations on the remote machine, which saves a +connection. I then do cvs operations on the remote machine, which saves a lot of time as the remote cvs protocol isn't very efficient. I mirror a directory between my "old" and "new" ftp sites with the @@ -219,12 +285,12 @@ verb( -v, --verbose increase verbosity -q, --quiet decrease verbosity -c, --checksum always checksum - -a, --archive archive mode + -a, --archive archive mode, equivalent to -rlptgoD -r, --recursive recurse into directories -R, --relative use relative path names -b, --backup make backups (default ~ suffix) --backup-dir make backups into this directory - --suffix=SUFFIX override backup suffix + --suffix=SUFFIX define backup suffix -u, --update update only (don't overwrite newer files) -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of symlinks @@ -242,7 +308,7 @@ verb( --no-whole-file turn off --whole-file -x, --one-file-system don't cross filesystem boundaries -B, --block-size=SIZE checksum blocking size (default 700) - -e, --rsh=COMMAND specify rsh replacement + -e, --rsh=COMMAND specify the remote shell to use --rsync-path=PATH specify path to rsync on the remote machine -C, --cvs-exclude auto ignore files in the same way CVS does --existing only update files that already exist @@ -261,6 +327,7 @@ verb( --modify-window=NUM Timestamp window (seconds) for file match (default=0) -T --temp-dir=DIR create temporary files in directory DIR --compare-dest=DIR also compare destination files relative to DIR + --link-dest=DIR create hardlinks to DIR for unchanged files -P equivalent to --partial --progress -z, --compress compress file data --exclude=PATTERN exclude files matching PATTERN @@ -329,8 +396,8 @@ dit(bf(--modify-window)) When comparing two timestamps rsync treats the timestamps as being equal if they are within the value of modify_window. This is normally zero, but you may find it useful to set this to a larger value in some situations. In particular, when -transferring to/from FAT filesystems which cannot represent times with -a 1 second resolution this option is useful. +transferring to Windows FAT filesystems which cannot represent times +with a 1 second resolution --modify-window=1 is useful. dit(bf(-c, --checksum)) This forces the sender to checksum all files using a 128-bit MD4 checksum before transfer. The checksum is then @@ -372,10 +439,15 @@ control the backup suffix using the --suffix option. dit(bf(--backup-dir=DIR)) In combination with the --backup option, this tells rsync to store all backups in the specified directory. This is -very useful for incremental backups. +very useful for incremental backups. You can additionally +specify a backup suffix using the --suffix option +(otherwise the files backed up in the specified directory +will keep their original filenames). dit(bf(--suffix=SUFFIX)) This option allows you to override the default backup suffix used with the -b option. The default is a ~. +If --backup-dir and --suffix are both specified, +the SUFFIX is appended to the filename even in the backup directory. 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 @@ -421,7 +493,9 @@ permissions to be the same as the local permissions. 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. +only the super-user can set file ownership. Note that if the remote system +is a daemon using chroot, the --numeric-ids option is implied because the +remote system cannot get access to the usernames from /etc/passwd. 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 @@ -505,11 +579,26 @@ the rsync algorithm. See the technical report for details. dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative remote shell program to use for communication between the local and -remote copies of rsync. By default, rsync will use rsh, but you may -like to instead use ssh because of its high security. +remote copies of rsync. Typically, rsync is configured to use rsh by +default, but you may prefer to use ssh because of its high security. + +If this option is used with bf([user@]host::module/path), then the +remote shell em(COMMMAND) will be used to run an rsync server on the +remote host, and all data will be transmitted through that remote +shell connection, rather than through a direct socket connection to a +running rsync server on the remote host. See the section "CONNECTING +TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM" above. + +Command-line arguments are permitted in COMMAND provided that COMMAND is +presented to rsync as a single argument. For example: + +quote(-e "ssh -p 2234") + +(Note that ssh users can alternately customize site-specific connect +options in their .ssh/config file.) You can also choose the remote shell program using the RSYNC_RSH -environment variable. +environment variable, which accepts the same range of values as -e. See also the --blocking-io option which is affected by this option. @@ -532,6 +621,8 @@ dit(bf(--exclude-from=FILE)) This option is similar to the --exclude option, but instead it adds all exclude patterns listed in the file FILE to the exclude list. Blank lines in FILE and lines starting with ';' or '#' are ignored. +If em(FILE) is bf(-) the list will be read from standard input. + dit(bf(--include=PATTERN)) This option tells rsync to not exclude the specified pattern of filenames. This is useful as it allows you to @@ -542,6 +633,8 @@ this option. dit(bf(--include-from=FILE)) This specifies a list of include patterns from a file. +If em(FILE) is bf(-) the list will be read from standard input. + dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a broad range of files that you often don't want to transfer between @@ -550,7 +643,7 @@ a file should be ignored. The exclude list is initialized to: -quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state +quote(RCS/ SCCS/ CVS/ .svn/ CVS.adm RCSLOG cvslog.* tags TAGS .make.state .nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-* *.a *.o *.obj *.so *.Z *.elc *.ln core) @@ -561,25 +654,6 @@ 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 -find that a truncated version of this checksum is quite efficient, and -this will decrease the size of the checksum data sent over the link, -making things faster. - -You can choose the number of bytes in the truncated checksum using the ---csum-length option. Any value less than or equal to 16 is valid. - -Note that if you use this option then you run the risk of ending up -with an incorrect target file. The risk with a value of 16 is -microscopic and can be safely ignored (the universe will probably end -before it fails) but with smaller values the risk is higher. - -Current versions of rsync actually use an adaptive algorithm for the -checksum length by default, using a 16 byte file checksum to determine -if a 2nd pass is required with a longer block checksum. Only use this -option if you have read the source code and know what you are doing. - dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a scratch directory when creating temporary copies of the files transferred on the receiving side. The default behavior is to create @@ -587,19 +661,25 @@ the temporary files in the receiving directory. dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on the destination machine as an additional directory to compare destination -files against when doing transfers. This is useful for doing transfers to -a new destination while leaving existing files intact, and then doing a +files against when doing transfers if the files are missing in the +destination directory. This is useful for doing transfers to a new +destination while leaving existing files intact, and then doing a flash-cutover when all files have been successfully transferred (for example by moving directories around and removing the old directory, -although this requires also doing the transfer with -I to avoid skipping -files that haven't changed). This option increases the usefulness of ---partial because partially transferred files will remain in the new -temporary destination until they have a chance to be completed. If DIR is -a relative path, it is relative to the destination directory. +although this skips files that haven't changed; see also --link-dest). +This option increases the usefulness of --partial because partially +transferred files will remain in the new temporary destination until they +have a chance to be completed. If DIR is a relative path, it is relative +to the destination directory. + +dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but +also will create hard links from em(DIR) to the destination directory for +unchanged files. Files with changed ownership or permissions will not be +linked. dit(bf(-z, --compress)) With this option, rsync compresses any data from the files that it sends to the destination machine. This -option is useful on slow links. The compression method used is the +option is useful on slow connections. The compression method used is the same method that gzip uses. Note this this option typically achieves better compression ratios @@ -631,7 +711,7 @@ 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 +(rsyncd.conf) on each connect made by a client and respond to requests accordingly. See the rsyncd.conf(5) man page for more details. @@ -651,8 +731,10 @@ address (or hostname) to bind to. This makes virtual hosting possible in conjunction with the --config option. dit(bf(--config=FILE)) This specifies an alternate config file than -the default /etc/rsyncd.conf. This is only relevant when --daemon is -specified. +the default. This is only relevant when --daemon is specified. +The default is /etc/rsyncd.conf unless the daemon is running over +a remote shell program and the remote user is not root; in that case +the default is rsyncd.conf in the current directory (typically $HOME). dit(bf(--port=PORT)) This specifies an alternate TCP port number to use rather than the default port 873. @@ -661,7 +743,8 @@ dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching a remote shell transport. If -e or --rsh are not specified or are set to the default "rsh", this defaults to blocking IO, otherwise it defaults to non-blocking IO. You may find the --blocking-io option is needed for some -remote shells that can't handle non-blocking IO. Ssh prefers blocking IO. +remote shells that can't handle non-blocking IO. (Note that ssh prefers +non-blocking IO.) dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the default. @@ -974,8 +1057,8 @@ ignore patterns in .cvsignore files. See the --cvs-exclude option for more details. dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to -override the default shell used as the transport for rsync. This can -be used instead of the -e option. +override the default shell used as the transport for rsync. Command line +options are permitted after the command name, just as in the -e option. dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to redirect your rsync client to use a web proxy when connecting to a @@ -996,7 +1079,7 @@ enddit() manpagefiles() -/etc/rsyncd.conf +/etc/rsyncd.conf or rsyncd.conf manpageseealso() @@ -1008,16 +1091,17 @@ manpagebugs() times are transferred as unix time_t values +When transferring to FAT filesystmes rsync may resync +unmodified files. +See the comments on the --modify-window option. + file permissions, devices etc are transferred as native numerical values see also the comments on the --delete option -Please report bugs! The rsync bug tracking system is online at -url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/) - -manpagesection(VERSION) -This man page is current for version 2.0 of rsync +Please report bugs! See the website at +url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(CREDITS)