X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/786c36876b9f0853063856974762e24fcc9e5cb5..59c95e4243749273fe91f8197a39f89e4d905cb8:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 017fb26e..21d69624 100644 --- a/rsync.yo +++ b/rsync.yo @@ -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, @@ -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,12 +186,59 @@ 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. +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 /etc/rsyncd.conf, you can added a +--config-file option to the em(command): + +quote(rsync --server --daemon --config-file=em(file) .) + manpagesection(EXAMPLES) Here are some examples of how I use rsync. @@ -224,7 +287,7 @@ verb( -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 +305,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 +324,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 @@ -372,10 +436,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 +490,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 +576,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 +618,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 +630,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 @@ -597,6 +687,11 @@ files that haven't changed). This option increases the usefulness of 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 @@ -661,7 +756,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 +1070,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