X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/41059f75b5e1c18235dd8c2f54aad5cef24bb83d..298c10d5bb83a6c3fc1ee6583383c6ae26e12751:/rsync.yo diff --git a/rsync.yo b/rsync.yo index f49fa2aa..9847ac90 100644 --- a/rsync.yo +++ b/rsync.yo @@ -81,6 +81,9 @@ command line option, or by setting the RSYNC_RSH environment variable. One common substitute is to use ssh, which offers a high degree of security. +Note that rsync must be installed on both the source and destination +machines. + manpagesection(USAGE) You use rsync in the same way you use rcp. You must specify a source @@ -139,6 +142,11 @@ itemize( list of accessible paths on the server will be shown. ) +Some paths on the remote server may require authentication. If so then +you will receive a password prompt when you connect. You can avoid the +password prompt by setting the environment variable RSYNC_PASSWORD to +the password you want to use. This may be useful when scripting rsync. + manpagesection(RUNNING AN RSYNC SERVER) An rsync server is configured using a config file which by default is @@ -179,6 +187,57 @@ quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba") this is launched from cron every few hours. +manpagesection(OPTIONS SUMMARY) + +Here is a short summary of the options avalable in rsync. Please refer +to the detailed description below for a complete description. + +verb( + -v, --verbose increase verbosity + -c, --checksum always checksum + -a, --archive archive mode + -r, --recursive recurse into directories + -R, --relative use relative path names + -b, --backup make backups (default ~ extension) + -u, --update update only (don't overwrite newer files) + -l, --links preserve soft links + -L, --copy-links treat soft links like regular files + -H, --hard-links preserve hard links + -p, --perms preserve permissions + -o, --owner preserve owner (root only) + -g, --group preserve group + -D, --devices preserve devices (root only) + -t, --times preserve times + -S, --sparse handle sparse files efficiently + -n, --dry-run show what would have been transferred + -W, --whole-file copy whole files, no incremental checks + -x, --one-file-system don't cross filesystem boundaries + -B, --block-size=SIZE checksum blocking size + -e, --rsh=COMMAND specify rsh replacement + --rsync-path=PATH specify path to rsync on the remote machine + -C, --cvs-exclude auto ignore files in the same way CVS does + --delete delete files that don't exist on the sending side + --partial keep partially transferred files + --force force deletion of directories even if not empty + --numeric-ids don't map uid/gid values by user/group name + --timeout=TIME set IO timeout in seconds + -I, --ignore-times don't exclude files that match length and time + -T --temp-dir=DIR create temporary files in directory DIR + -z, --compress compress file data + --exclude=PATTERN exclude file FILE + --exclude-from=PATTERN exclude files listed in FILE + --include=PATTERN don't exclude file FILE + --include-from=PATTERN don't exclude files listed in FILE + --suffix=SUFFIX override backup suffix + --version print version number + --daemon run as a rsync daemon + --config=FILE specify alternate rsyncd.conf file + --port=PORT specify alternate rsyncd port number + --stats give some file transfer stats + --progress show progress during transfer + -h, --help show this help screen +) + manpageoptions() rsync uses the GNU long options package. Many of the command line @@ -209,9 +268,12 @@ explicitly checked on the receiver and any files of the same name which already exist and have the same checksum and size on the receiver are skipped. This option can be quite slow. -dit(bf(-a, --archive)) This is equivalent to -rlptDog. It is a quick way +dit(bf(-a, --archive)) This is equivalent to -rlptDg. It is a quick way of saying I want recursion and want to preserve everything. +Note: if the user launching rsync is root then the -o option (preserve +uid) is also implied. + dit(bf(-r, --recursive)) This tells rsync to copy directories recursively dit(bf(-R, --relative)) Use relative paths. This means that the full path @@ -258,6 +320,12 @@ dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm is not used and the whole file is sent as-is instead. This may be useful when using rsync with a local machine. +dit(bf(--partial)) By default rsync will delete any partially +transferred file if the transfer is interrupted. In some circumstances +it is more desirable to keep partially transferred files. Using the +--partial option tells rsync to keep the partial file which should +make a subsequent transfer of the rest of the file much faster. + dit(bf(-p, --perms)) This option causes rsync to update the remote permissions to be the same as the local permissions. @@ -329,23 +397,30 @@ environment variable. dit(bf(--rsync-path PATH)) Use this to specify the path to the copy of rsync on the remote machine. Useful when its not in your path. -dit(bf(--exclude FILE)) This option allows you to selectively exclude +dit(bf(--exclude pattern)) This option allows you to selectively exclude certain files from the list of files to be transferred. This is most useful in combination with a recursive transfer. -The option FILE can either be a file name or a shell wildcard -expression. If it is a directory name then rsync will not recurse into -directories of that name. - You may use as many --exclude options on the command line as you like to build up the list of files to exclude. -If the filename is a single ! then the exclude list is reset. +See the section of exclude patterns for information on the syntax of +this option. dit(bf(--exclude-from FILE)) This option is similar to the --exclude option, but instead it adds all filenames listed in the file FILE to the exclude list. +dit(bf(--include pattern)) This option tells rsync to not exclude the +specified pattern of filenames. This is useful as it allows you to +build up quite complex exclude/include rules. + +See the section of exclude patterns for information on the syntax of +this option. + +dit(bf(--include-from FILE)) This specifies a list of include patterns +from a file. + 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 systems. It uses the same algorithm that CVS uses to determine if @@ -370,7 +445,7 @@ 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. +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. @@ -380,6 +455,11 @@ 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 options instructs rsync to use DIR as a scratch directory when creating a temporary copies of the files transferred on the receiving side. The default behavior is to create @@ -407,25 +487,119 @@ option is not specified. 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)) 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(--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 dameon will read the +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(--config FILE)) This specifies an alternate config file than -the default /etc/rsyncd.conf. This is only relevent when --daemon is +the default /etc/rsyncd.conf. This is only relevant when --daemon is specified. dit(bf(--port PORT)) This specifies an alternate TCP port number to use rather than the default port 873. +dit(bf(--stats)) This tells rsync to print a verbose set of statistics +on the file transfer, allowing you to tell how effective the rsync +algorithm is for your data. This option only works in conjunction with +the -v (verbose) option. + +dit(bf(--progress)) This option tells rsync to print information +showing the progress of the transfer. This gives a bored user +something to watch. + +enddit() + +manpagesection(EXCLUDE PATTERNS) + +The exclude and include patterns specified to rsync allow for flexible +selection of what files to transfer and what files to skip. + +rsync build a ordered list of include/exclude options as specified on +the command line. When a filename is encountered rsync then checks the +name against each exclude/include pattern in turn. The first matching +pattern is acted on. If it is an exclude pattern than that file is +skipped. If it is an include pattern then that filename is not +skipped. If no matching include/exclude pattern is found then the +filename is not skipped. + +The patterns themselves can take several forms. The rules are: + +itemize( + it() if the pattern starts with a / then it is matched against the + start of the filename, otherwise it is matched against the end of + the filename. Thus /foo would match a file called foo + at the base of the tree whereas foo would match any file + called foo anywhere in the tree. + + it() if the pattern ends with a / then it will only match a + directory, not a file, link or device. + + it() if the pattern contains a wildcard character from the set + *?[ then regular expression matching is applied using the + normal shell filename matching rules. Otherwise a simple string + match is used. + + it() if the pattern contains a / (not counting a trailing /) then it + is matched against the full filename, including any leading + directory. If the pattern doesn't contain a / then it is matched + only against the final component of the filename. + + it() if the pattern starts with "+ " (a plus followed by a space) + then it is always considered a include pattern, even if specified as + part of an exclude option. The "+ " part is discarded before matching. + + it() if the pattern starts with "- " (a minus followed by a space) + then it is always considered a exclude pattern, even if specified as + 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. +) + +The +/- rules are most useful in exclude lists, allowing you to have a +single exclude list that contains both include and exclude options. + +Here are some examples: + +itemize( + it() --exclude "*.o" would exclude all filenames matching *.o + it() --exclude "/foo" would exclude a file in the base directory called foo + it() --exclude "foo/" would exclude any directory called foo + it() --include "*/" --include "*.c" --exclude "*" would include all + directories and C source files. +) + +manpagesection(ENVIRONMENT VARIABLES) + +startdit() + +dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any +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. + +dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required +password allows you to run authenticated rsync connections to a rsync +daemon without user intervention. Note that this does not supply a +password to a shell transport such as ssh. + +dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables +are used to determine the default username sent to a rsync server. + +dit(bf(HOME)) The HOME environment variable is used to find the users +default .cvsignore file. + enddit() manpagefiles() @@ -445,7 +619,7 @@ times are transferred as unix time_t values file permissions, devices etc are transferred as native numerical values -see also the comments on the -delete option +see also the comments on the --delete option Please report bugs! The rsync bug tracking system is online at url(http://samba.anu.edu.au/rsync/)(http://samba.anu.edu.au/rsync/)