EditPageHistoryDiffInfoLikePages

Annotated edit history of rsync(1) version 1, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	rsync
		2	!!!rsync
		3	NAME
		4	SYNOPSIS
		5	DESCRIPTION
		6	GENERAL
		7	SETUP
		8	USAGE
		9	CONNECTING TO AN RSYNC SERVER
		10	RUNNING AN RSYNC SERVER
		11	EXAMPLES
		12	OPTIONS SUMMARY
		13	OPTIONS
		14	EXCLUDE PATTERNS
		15	BATCH MODE
		16	SYMBOLIC LINKS
		17	DIAGNOSTICS
		18	EXIT VALUES
		19	ENVIRONMENT VARIABLES
		20	FILES
		21	SEE ALSO
		22	DIAGNOSTICS
		23	BUGS
		24	VERSION
		25	CREDITS
		26	THANKS
		27	AUTHOR
		28	----
		29	!!NAME
		30
		31
		32	rsync - faster, flexible replacement for rcp
		33	!!SYNOPSIS
		34
		35
		36	rsync [[OPTION]... SRC [[SRC]... [[USER@]HOST:DEST
		37
		38
		39	rsync [[OPTION]... [[USER@]HOST:SRC DEST
		40
		41
		42	rsync [[OPTION]... SRC [[SRC]... DEST
		43
		44
		45	rsync [[OPTION]... [[USER@]HOST::SRC [[DEST]
		46
		47
		48	rsync [[OPTION]... SRC [[SRC]...
		49	[[USER@]HOST::DEST
		50
		51
		52	rsync [[OPTION]... rsync://[[USER@]HOST[[:PORT]/SRC
		53	[[DEST]
		54	!!DESCRIPTION
		55
		56
		57	rsync is a program that behaves in much the same way that
		58	rcp does, but has many more options and uses the rsync
		59	remote-update protocol to greatly speed up file transfers
		60	when the destination file already exists.
		61
		62
		63	The rsync remote-update protocol allows rsync to transfer
		64	just the differences between two sets of files across the
		65	network link, using an efficient checksum-search algorithm
		66	described in the technical report that accompanies this
		67	package.
		68
		69
		70	Some of the additional features of rsync are:
		71
		72
		73	o
		74
		75
		76	support for copying links, devices, owners, groups and
		77	permissions
		78
		79
		80	o
		81
		82
		83	exclude and exclude-from options similar to GNU
		84	tar
		85
		86
		87	o
		88
		89
		90	a CVS exclude mode for ignoring the same files that CVS
		91	would ignore
		92
		93
		94	o
		95
		96
		97	can use any transparent remote shell, including rsh or
		98	ssh
		99
		100
		101	o
		102
		103
		104	does not require root privileges
		105
		106
		107	o
		108
		109
		110	pipelining of file transfers to minimize latency
		111	costs
		112
		113
		114	o
		115
		116
		117	support for anonymous or authenticated rsync servers (ideal
		118	for mirroring)
		119	!!GENERAL
		120
		121
		122	There are six different ways of using rsync. They
		123	are:
		124
		125
		126	o
		127
		128
		129	for copying local files. This is invoked when neither source
		130	nor destination path contains a : separator
		131
		132
		133	o
		134
		135
		136	for copying from the local machine to a remote machine using
		137	a remote shell program as the transport (such as rsh or
		138	ssh). This is invoked when the destination path contains a
		139	single : separator.
		140
		141
		142	o
		143
		144
		145	for copying from a remote machine to the local machine using
		146	a remote shell program. This is invoked when the source
		147	contains a : separator.
		148
		149
		150	o
		151
		152
		153	for copying from a remote rsync server to the local machine.
		154	This is invoked when the source path contains a :: separator
		155	or a rsync:// URL.
		156
		157
		158	o
		159
		160
		161	for copying from the local machine to a remote rsync server.
		162	This is invoked when the destination path contains a ::
		163	separator.
		164
		165
		166	o
		167
		168
		169	for listing files on a remote machine. This is done the same
		170	way as rsync transfers except that you leave off the local
		171	destination.
		172
		173
		174	Note that in all cases (other than listing) at least one of
		175	the source and destination paths must be local.
		176	!!SETUP
		177
		178
		179	See the file README for installation
		180	instructions.
		181
		182
		183	Once installed you can use rsync to any machine that you can
		184	use rsh to. rsync uses rsh for its communications, unless
		185	both the source and destination are local.
		186
		187
		188	You can also specify an alternative to rsh, either by using
		189	the -e command line option, or by setting the RSYNC_RSH
		190	environment variable.
		191
		192
		193	One common substitute is to use ssh, which offers a high
		194	degree of security.
		195
		196
		197	Note that rsync must be installed on both the source and
		198	destination machines.
		199	!!USAGE
		200
		201
		202	You use rsync in the same way you use rcp. You must specify
		203	a source and a destination, one of which may be
		204	remote.
		205
		206
		207	Perhaps the best way to explain the syntax is some
		208	examples:
		209
		210
		211	rsync *.c foo:src/
		212
		213
		214	this would transfer all files matching the pattern *.c from
		215	the current directory to the directory src on the machine
		216	foo. If any of the files already exist on the remote system
		217	then the rsync remote-update protocol is used to update the
		218	file by sending only the differences. See the tech report
		219	for details.
		220
		221
		222	rsync -avz foo:src/bar /data/tmp
		223
		224
		225	this would recursively transfer all files from the directory
		226	src/bar on the machine foo into the /data/tmp/bar directory
		227	on the local machine. The files are transferred in
		228
		229
		230	rsync -avz foo:src/bar/ /data/tmp
		231
		232
		233	a trailing slash on the source changes this behavior to
		234	transfer all files from the directory src/bar on the machine
		235	foo into the /data/tmp/. A trailing / on a source name means
		236
		237
		238	You can also use rsync in local-only mode, where both the
		239	source and destination dont have a : in the name. In this
		240	case it behaves like an improved copy command.
		241
		242
		243	rsync somehost.mydomain.com::
		244
		245
		246	this would list all the anonymous rsync modules available on
		247	the host somehost.mydomain.com. (See the following section
		248	for more details.)
		249	!!CONNECTING TO AN RSYNC SERVER
		250
		251
		252	It is also possible to use rsync without using rsh or ssh as
		253	the transport. In this case you will connect to a remote
		254	rsync server running on TCP port 873.
		255
		256
		257	You may establish the connection via a web proxy by setting
		258	the environment variable RSYNC_PROXY to a hostname:port pair
		259	pointing to your web proxy. Note that your web proxys
		260	configuration must allow proxying to port 873.
		261
		262
		263	Using rsync in this way is the same as using it with rsh or
		264	ssh except that:
		265
		266
		267	o
		268
		269
		270	you use a double colon :: instead of a single colon to
		271	separate the hostname from the path.
		272
		273
		274	o
		275
		276
		277	the remote server may print a message of the day when you
		278	connect.
		279
		280
		281	o
		282
		283
		284	if you specify no path name on the remote server then the
		285	list of accessible paths on the server will be
		286	shown.
		287
		288
		289	o
		290
		291
		292	if you specify no local destination then a listing of the
		293	specified files on the remote server is
		294	provided.
		295
		296
		297	Some paths on the remote server may require authentication.
		298	If so then you will receive a password prompt when you
		299	connect. You can avoid the password prompt by setting the
		300	environment variable RSYNC_PASSWORD to the password you want
		301	to use or using the --password-file option. This may be
		302	useful when scripting rsync.
		303
		304
		305	WARNING: On some systems environment variables are visible
		306	to all users. On those systems using --password-file is
		307	recommended.
		308	!!RUNNING AN RSYNC SERVER
		309
		310
		311	An rsync server is configured using a config file which by
		312	default is called /etc/rsyncd.conf. Please see the
		313	rsyncd.conf(5) man page for more information.
		314	!!EXAMPLES
		315
		316
		317	Here are some examples of how I use rsync.
		318
		319
		320	To backup my wifes home directory, which consists of large
		321	MS Word files and mail folders, I use a cron job that
		322	runs
		323
		324
		325	rsync -Cavz . arvidsjaur:backup
		326
		327
		328	each night over a PPP link to a duplicate directory on my
		329	machine
		330
		331
		332	To synchronize my samba source trees I use the following
		333	Makefile targets:
		334
		335
		336	get:
		337	rsync -avuzb --exclude *~ samba:samba/ .
		338
		339
		340	put:
		341	rsync -Cavuzb . samba:samba/
		342
		343
		344	sync: get put
		345
		346
		347	this allows me to sync with a CVS directory at the other end
		348	of the link. I then do cvs operations on the remote machine,
		349	which saves a lot of time as the remote cvs protocol isnt
		350	very efficient.
		351
		352
		353	I mirror a directory between my
		354
		355
		356	rsync -az -e ssh --delete ~ftp/pub/samba/
		357	nimbus:
		358
		359
		360	this is launched from cron every few hours.
		361	!!OPTIONS SUMMARY
		362
		363
		364	Here is a short summary of the options available in rsync.
		365	Please refer to the detailed description below for a
		366	complete description.
		367
		368
		369	-v, --verbose increase verbosity
		370	-q, --quiet decrease verbosity
		371	-c, --checksum always checksum
		372	-a, --archive archive mode
		373	-r, --recursive recurse into directories
		374	-R, --relative use relative path names
		375	-b, --backup make backups (default ~ suffix)
		376	--backup-dir make backups into this directory
		377	--suffix=SUFFIX override backup suffix
		378	-u, --update update only (dont overwrite newer files)
		379	-l, --links copy symlinks as symlinks
		380	-L, --copy-links copy the referent of symlinks
		381	--copy-unsafe-links copy links outside the source tree
		382	--safe-links ignore links outside the destination tree
		383	-H, --hard-links preserve hard links
		384	-p, --perms preserve permissions
		385	-o, --owner preserve owner (root only)
		386	-g, --group preserve group
		387	-D, --devices preserve devices (root only)
		388	-t, --times preserve times
		389	-S, --sparse handle sparse files efficiently
		390	-n, --dry-run show what would have been transferred
		391	-W, --whole-file copy whole files, no incremental checks
		392	--no-whole-file turn off --whole-file
		393	-x, --one-file-system dont cross filesystem boundaries
		394	-B, --block-size=SIZE checksum blocking size (default 700)
		395	-e, --rsh=COMMAND specify rsh replacement
		396	--rsync-path=PATH specify path to rsync on the remote machine
		397	-C, --cvs-exclude auto ignore files in the same way CVS does
		398	--existing only update files that already exist
		399	--ignore-existing ignore files that already exist on the receiving side
		400	--delete delete files that dont exist on the sending side
		401	--delete-excluded also delete excluded files on the receiving side
		402	--delete-after delete after transferring, not before
		403	--ignore-errors delete even if there are IO errors
		404	--max-delete=NUM dont delete more than NUM files
		405	--partial keep partially transferred files
		406	--force force deletion of directories even if not empty
		407	--numeric-ids dont map uid/gid values by user/group name
		408	--timeout=TIME set IO timeout in seconds
		409	-I, --ignore-times dont exclude files that match length and time
		410	--size-only only use file size when determining if a file should be transferred
		411	--modify-window=NUM Timestamp window (seconds) for file match (default=0)
		412	-T --temp-dir=DIR create temporary files in directory DIR
		413	--compare-dest=DIR also compare destination files relative to DIR
		414	-P equivalent to --partial --progress
		415	-z, --compress compress file data
		416	--exclude=PATTERN exclude files matching PATTERN
		417	--exclude-from=FILE exclude patterns listed in FILE
		418	--include=PATTERN dont exclude files matching PATTERN
		419	--include-from=FILE dont exclude patterns listed in FILE
		420	--version print version number
		421	--daemon run as a rsync daemon
		422	--no-detach do not detach from the parent
		423	--address=ADDRESS bind to the specified address
		424	--config=FILE specify alternate rsyncd.conf file
		425	--port=PORT specify alternate rsyncd port number
		426	--blocking-io use blocking IO for the remote shell
		427	--no-blocking-io turn off --blocking-io
		428	--stats give some file transfer stats
		429	--progress show progress during transfer
		430	--log-format=FORMAT log file transfers using specified format
		431	--password-file=FILE get password from FILE
		432	--bwlimit=KBPS limit I/O bandwidth, KBytes per second
		433	--read-batch=PREFIX read batch fileset starting with PREFIX
		434	--write-batch=PREFIX write batch fileset starting with PREFIX
		435	-h, --help show this help screen
		436	!!OPTIONS
		437
		438
		439	rsync uses the GNU long options package. Many of the command
		440	line options have two variants, one short and one long.
		441	These are shown below, separated by commas. Some options
		442	only have a long variant. The = for options that take a
		443	parameter is optional; whitespace can be used
		444	instead.
		445
		446
		447	__-h, --help__
		448
		449
		450	Print a short help page describing the options available in
		451	rsync
		452
		453
		454	__--version__
		455
		456
		457	print the rsync version number and exit
		458
		459
		460	__-v, --verbose__
		461
		462
		463	This option increases the amount of information you are
		464	given during the transfer. By default, rsync works silently.
		465	A single -v will give you information about what files are
		466	being transferred and a brief summary at the end. Two -v
		467	flags will give you information on what files are being
		468	skipped and slightly more information at the end. More than
		469	two -v flags should only be used if you are debugging
		470	rsync.
		471
		472
		473	__-q, --quiet__
		474
		475
		476	This option decreases the amount of information you are
		477	given during the transfer, notably suppressing information
		478	messages from the remote server. This flag is useful when
		479	invoking rsync from cron.
		480
		481
		482	__-I, --ignore-times__
		483
		484
		485	Normally rsync will skip any files that are already the same
		486	length and have the same time-stamp. This option turns off
		487	this behavior.
		488
		489
		490	__--size-only__
		491
		492
		493	Normally rsync will skip any files that are already the same
		494	length and have the same time-stamp. With the --size-only
		495	option files will be skipped if they have the same size,
		496	regardless of timestamp. This is useful when starting to use
		497	rsync after using another mirroring system which may not
		498	preserve timestamps exactly.
		499
		500
		501	__--modify-window__
		502
		503
		504	When comparing two timestamps rsync treats the timestamps as
		505	being equal if they are within the value of modify_window.
		506	This is normally zero, but you may find it useful to set
		507	this to a larger value in some situations. In particular,
		508	when transferring to/from FAT filesystems which cannot
		509	represent times with a 1 second resolution this option is
		510	useful.
		511
		512
		513	__-c, --checksum__
		514
		515
		516	This forces the sender to checksum all files using a 128-bit
		517	MD4 checksum before transfer. The checksum is then
		518	explicitly checked on the receiver and any files of the same
		519	name which already exist and have the same checksum and size
		520	on the receiver are skipped. This option can be quite
		521	slow.
		522
		523
		524	__-a, --archive__
		525
		526
		527	This is equivalent to -rlptgoD. It is a quick way of saying
		528	you want recursion and want to preserve almost
		529	everything.
		530
		531
		532	Note however that __-a does not preserve hardlinks__,
		533	because finding multiply-linked files is expensive. You must
		534	separately specify __-H__.
		535
		536
		537	__-r, --recursive__
		538
		539
		540	This tells rsync to copy directories recursively. If you
		541	dont specify this then rsync wont copy directories at
		542	all.
		543
		544
		545	__-R, --relative__
		546
		547
		548	Use relative paths. This means that the full path names
		549	specified on the command line are sent to the server rather
		550	than just the last parts of the filenames. This is
		551	particularly useful when you want to send several different
		552	directories at the same time. For example, if you used the
		553	command
		554
		555
		556	rsync foo/bar/foo.c remote:/tmp/
		557
		558
		559	then this would create a file called foo.c in /tmp/ on the
		560	remote machine. If instead you used
		561
		562
		563	rsync -R foo/bar/foo.c remote:/tmp/
		564
		565
		566	then a file called /tmp/foo/bar/foo.c would be created on
		567	the remote machine. The full path name is
		568	preserved.
		569
		570
		571	__-b, --backup__
		572
		573
		574	With this option preexisting destination files are renamed
		575	with a ~ extension as each file is transferred. You can
		576	control the backup suffix using the --suffix
		577	option.
		578
		579
		580	__--backup-dir=DIR__
		581
		582
		583	In combination with the --backup option, this tells rsync to
		584	store all backups in the specified directory. This is very
		585	useful for incremental backups.
		586
		587
		588	__--suffix=SUFFIX__
		589
		590
		591	This option allows you to override the default backup suffix
		592	used with the -b option. The default is a ~.
		593
		594
		595	__-u, --update__
		596
		597
		598	This forces rsync to skip any files for which the
		599	destination file already exists and has a date later than
		600	the source file.
		601
		602
		603	__-l, --links__
		604
		605
		606	When symlinks are encountered, recreate the symlink on the
		607	destination.
		608
		609
		610	__-L, --copy-links__
		611
		612
		613	When symlinks are encountered, the file that they point to
		614	is copied, rather than the symlink.
		615
		616
		617	__--copy-unsafe-links__
		618
		619
		620	This tells rsync to copy the referent of symbolic links that
		621	point outside the source tree. Absolute symlinks are also
		622	treated like ordinary files, and so are any symlinks in the
		623	source path itself when --relative is used.
		624
		625
		626	__--safe-links__
		627
		628
		629	This tells rsync to ignore any symbolic links which point
		630	outside the destination tree. All absolute symlinks are also
		631	ignored. Using this option in conjunction with --relative
		632	may give unexpected results.
		633
		634
		635	__-H, --hard-links__
		636
		637
		638	This tells rsync to recreate hard links on the remote system
		639	to be the same as the local system. Without this option hard
		640	links are treated like regular files.
		641
		642
		643	Note that rsync can only detect hard links if both parts of
		644	the link are in the list of files being sent.
		645
		646
		647	This option can be quite slow, so only use it if you need
		648	it.
		649
		650
		651	__-W, --whole-file__
		652
		653
		654	With this option the incremental rsync algorithm is not used
		655	and the whole file is sent as-is instead. The transfer may
		656	be faster if this option is used when the bandwidth between
		657	the source and target machines is higher than the bandwidth
		658	to disk (especially when the
		659
		660
		661	__--no-whole-file__
		662
		663
		664	Turn off --whole-file, for use when it is the
		665	default.
		666
		667
		668	__-p, --perms__
		669
		670
		671	This option causes rsync to update the remote permissions to
		672	be the same as the local permissions.
		673
		674
		675	__-o, --owner__
		676
		677
		678	This option causes rsync to set the owner of the destination
		679	file to be the same as the source file. On most systems,
		680	only the super-user can set file ownership.
		681
		682
		683	__-g, --group__
		684
		685
		686	This option causes rsync to set the group of the destination
		687	file to be the same as the source file. If the receiving
		688	program is not running as the super-user, only groups that
		689	the receiver is a member of will be preserved (by group
		690	name, not group id number).
		691
		692
		693	__-D, --devices__
		694
		695
		696	This option causes rsync to transfer character and block
		697	device information to the remote system to recreate these
		698	devices. This option is only available to the
		699	super-user.
		700
		701
		702	__-t, --times__
		703
		704
		705	This tells rsync to transfer modification times along with
		706	the files and update them on the remote system. Note that if
		707	this option is not used, the optimization that excludes
		708	files that have not been modified cannot be effective; in
		709	other words, a missing -t or -a will cause the next transfer
		710	to behave as if it used -I, and all files will have their
		711	checksums compared and show up in log messages even if they
		712	havent changed.
		713
		714
		715	__-n, --dry-run__
		716
		717
		718	This tells rsync to not do any file transfers, instead it
		719	will just report the actions it would have
		720	taken.
		721
		722
		723	__-S, --sparse__
		724
		725
		726	Try to handle sparse files efficiently so they take up less
		727	space on the destination.
		728
		729
		730	NOTE: Dont use this option when the destination is a Solaris
		731
		732
		733	__-x, --one-file-system__
		734
		735
		736	This tells rsync not to cross filesystem boundaries when
		737	recursing. This is useful for transferring the contents of
		738	only one filesystem.
		739
		740
		741	__--existing__
		742
		743
		744	This tells rsync not to create any new files - only update
		745	files that already exist on the destination.
		746
		747
		748	__--ignore-existing__
		749
		750
		751	This tells rsync not to update files that already exist on
		752	the destination.
		753
		754
		755	__--max-delete=NUM__
		756
		757
		758	This tells rsync not to delete more than NUM files or
		759	directories. This is useful when mirroring very large trees
		760	to prevent disasters.
		761
		762
		763	__--delete__
		764
		765
		766	This tells rsync to delete any files on the receiving side
		767	that arent on the sending side. Files that are excluded from
		768	transfer are excluded from being deleted unless you use
		769	--delete-excluded.
		770
		771
		772	This option has no effect if directory recursion is not
		773	selected.
		774
		775
		776	This option can be dangerous if used incorrectly! It is a
		777	very good idea to run first using the dry run option (-n) to
		778	see what files would be deleted to make sure important files
		779	arent listed.
		780
		781
		782	If the sending side detects any IO errors then the deletion
		783	of any files at the destination will be automatically
		784	disabled. This is to prevent temporary filesystem failures
		785	(such as NFS errors) on the sending side causing a massive
		786	deletion of files on the destination. You can override this
		787	with the --ignore-errors option.
		788
		789
		790	__--delete-excluded__
		791
		792
		793	In addition to deleting the files on the receiving side that
		794	are not on the sending side, this tells rsync to also delete
		795	any files on the receiving side that are excluded (see
		796	--exclude).
		797
		798
		799	__--delete-after__
		800
		801
		802	By default rsync does file deletions before transferring
		803	files to try to ensure that there is sufficient space on the
		804	receiving filesystem. If you want to delete after
		805	transferring then use the --delete-after
		806	switch.
		807
		808
		809	__--ignore-errors__
		810
		811
		812	Tells --delete to go ahead and delete files even when there
		813	are IO errors.
		814
		815
		816	__--force__
		817
		818
		819	This options tells rsync to delete directories even if they
		820	are not empty when they are to be replaced by
		821	non-directories. This is only relevant without --delete
		822	because deletions are now done depth-first. Requires the
		823	--recursive option (which is implied by -a) to have any
		824	effect.
		825
		826
		827	__-B , --block-size=BLOCKSIZE__
		828
		829
		830	This controls the block size used in the rsync algorithm.
		831	See the technical report for details.
		832
		833
		834	__-e, --rsh=COMMAND__
		835
		836
		837	This option allows you to choose an alternative remote shell
		838	program to use for communication between the local and
		839	remote copies of rsync. By default, rsync will use rsh, but
		840	you may like to instead use ssh because of its high
		841	security.
		842
		843
		844	You can also choose the remote shell program using the
		845	RSYNC_RSH environment variable.
		846
		847
		848	See also the --blocking-io option which is affected by this
		849	option.
		850
		851
		852	__--rsync-path=PATH__
		853
		854
		855	Use this to specify the path to the copy of rsync on the
		856	remote machine. Useful when its not in your path. Note that
		857	this is the full path to the binary, not just the directory
		858	that the binary is in.
		859
		860
		861	__--exclude=PATTERN__
		862
		863
		864	This option allows you to selectively exclude certain files
		865	from the list of files to be transferred. This is most
		866	useful in combination with a recursive
		867	transfer.
		868
		869
		870	You may use as many --exclude options on the command line as
		871	you like to build up the list of files to
		872	exclude.
		873
		874
		875	See the section on exclude patterns for information on the
		876	syntax of this option.
		877
		878
		879	__--exclude-from=FILE__
		880
		881
		882	This option is similar to the --exclude option, but instead
		883	it adds all exclude patterns listed in the file FILE to the
		884	exclude list. Blank lines in FILE and lines starting with ;
		885	or # are ignored.
		886
		887
		888	__--include=PATTERN__
		889
		890
		891	This option tells rsync to not exclude the specified pattern
		892	of filenames. This is useful as it allows you to build up
		893	quite complex exclude/include rules.
		894
		895
		896	See the section of exclude patterns for information on the
		897	syntax of this option.
		898
		899
		900	__--include-from=FILE__
		901
		902
		903	This specifies a list of include patterns from a
		904	file.
		905
		906
		907	__-C, --cvs-exclude__
		908
		909
		910	This is a useful shorthand for excluding a broad range of
		911	files that you often dont want to transfer between systems.
		912	It uses the same algorithm that CVS uses to determine if a
		913	file should be ignored.
		914
		915
		916	The exclude list is initialized to:
		917
		918
		919	RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
		920	.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej
		921	.del-* *.a *.o *.obj *.so *.Z *.elc *.ln core
		922
		923
		924	then files listed in a $HOME/.cvsignore are added to the
		925	list and any files listed in the CVSIGNORE environment
		926	variable (space delimited).
		927
		928
		929	Finally, any file is ignored if it is in the same directory
		930	as a .cvsignore file and matches one of the patterns listed
		931	therein. See the __cvs(1)__ manual for more
		932	information.
		933
		934
		935	__--csum-length=LENGTH__
		936
		937
		938	By default the primary checksum used in rsync is a very
		939	strong 16 byte MD4 checksum. In most cases you will find
		940	that a truncated version of this checksum is quite
		941	efficient, and this will decrease the size of the checksum
		942	data sent over the link, making things faster.
		943
		944
		945	You can choose the number of bytes in the truncated checksum
		946	using the --csum-length option. Any value less than or equal
		947	to 16 is valid.
		948
		949
		950	Note that if you use this option then you run the risk of
		951	ending up with an incorrect target file. The risk with a
		952	value of 16 is microscopic and can be safely ignored (the
		953	universe will probably end before it fails) but with smaller
		954	values the risk is higher.
		955
		956
		957	Current versions of rsync actually use an adaptive algorithm
		958	for the checksum length by default, using a 16 byte file
		959	checksum to determine if a 2nd pass is required with a
		960	longer block checksum. Only use this option if you have read
		961	the source code and know what you are doing.
		962
		963
		964	__-T, --temp-dir=DIR__
		965
		966
		967	This option instructs rsync to use DIR as a scratch
		968	directory when creating temporary copies of the files
		969	transferred on the receiving side. The default behavior is
		970	to create the temporary files in the receiving
		971	directory.
		972
		973
		974	__--compare-dest=DIR__
		975
		976
		977	This option instructs rsync to use DIR on the destination
		978	machine as an additional directory to compare destination
		979	files against when doing transfers. This is useful for doing
		980	transfers to a new destination while leaving existing files
		981	intact, and then doing a flash-cutover when all files have
		982	been successfully transferred (for example by moving
		983	directories around and removing the old directory, although
		984	this requires also doing the transfer with -I to avoid
		985	skipping files that havent changed). This option increases
		986	the usefulness of --partial because partially transferred
		987	files will remain in the new temporary destination until
		988	they have a chance to be completed. If DIR is a relative
		989	path, it is relative to the destination
		990	directory.
		991
		992
		993	__-z, --compress__
		994
		995
		996	With this option, rsync compresses any data from the files
		997	that it sends to the destination machine. This option is
		998	useful on slow links. The compression method used is the
		999	same method that gzip uses.
		1000
		1001
		1002	Note this this option typically achieves better compression
		1003	ratios that can be achieved by using a compressing remote
		1004	shell, or a compressing transport, as it takes advantage of
		1005	the implicit information sent for matching data
		1006	blocks.
		1007
		1008
		1009	__--numeric-ids__
		1010
		1011
		1012	With this option rsync will transfer numeric group and user
		1013	ids rather than using user and group names and mapping them
		1014	at both ends.
		1015
		1016
		1017	By default rsync will use the user name and group name to
		1018	determine what ownership to give files. The special uid 0
		1019	and the special group 0 are never mapped via user/group
		1020	names even if the --numeric-ids option is not
		1021	specified.
		1022
		1023
		1024	If the source system is a daemon using chroot, or if a user
		1025	or group name does not exist on the destination system, then
		1026	the numeric id from the source system is used
		1027	instead.
		1028
		1029
		1030	__--timeout=TIMEOUT__
		1031
		1032
		1033	This option allows you to set a maximum IO timeout in
		1034	seconds. If no data is transferred for the specified time
		1035	then rsync will exit. The default is 0, which means no
		1036	timeout.
		1037
		1038
		1039	__--daemon__
		1040
		1041
		1042	This tells rsync that it is to run as a daemon. The daemon
		1043	may be accessed using the __host::module__ or
		1044	__rsync://host/module/__ syntax.
		1045
		1046
		1047	If standard input is a socket then rsync will assume that it
		1048	is being run via inetd, otherwise it will detach from the
		1049	current terminal and become a background daemon. The daemon
		1050	will read the config file (/etc/rsyncd.conf) on each connect
		1051	made by a client and respond to requests accordingly. See
		1052	the rsyncd.conf(5) man page for more details.
		1053
		1054
		1055	__--no-detach__
		1056
		1057
		1058	When running as a daemon, this option instructs rsync to not
		1059	detach itself and become a background process. This option
		1060	is required when running as a service on Cygwin, and may
		1061	also be useful when rsync is supervised by a program such as
		1062	__daemontools__ or AIXs __System Resource
		1063	Controller__. __--no-detach__ is also recommended when
		1064	rsync is run under a debugger. This option has no effect if
		1065	rsync is run from inetd or sshd.
		1066
		1067
		1068	__--address__
		1069
		1070
		1071	By default rsync will bind to the wildcard address when run
		1072	as a daemon with the --daemon option or when connecting to a
		1073	rsync server. The --address option allows you to specify a
		1074	specific IP address (or hostname) to bind to. This makes
		1075	virtual hosting possible in conjunction with the --config
		1076	option.
		1077
		1078
		1079	__--config=FILE__
		1080
		1081
		1082	This specifies an alternate config file than the default
		1083	/etc/rsyncd.conf. This is only relevant when --daemon is
		1084	specified.
		1085
		1086
		1087	__--port=PORT__
		1088
		1089
		1090	This specifies an alternate TCP port number to use rather
		1091	than the default port 873.
		1092
		1093
		1094	__--blocking-io__
		1095
		1096
		1097	This tells rsync to use blocking IO when launching a remote
		1098	shell transport. If -e or --rsh are not specified or are set
		1099	to the default
		1100
		1101
		1102	__--no-blocking-io__
		1103
		1104
		1105	Turn off --blocking-io, for use when it is the
		1106	default.
		1107
		1108
		1109	__--log-format=FORMAT__
		1110
		1111
		1112	This allows you to specify exactly what the rsync client
		1113	logs to stdout on a per-file basis. The log format is
		1114	specified using the same format conventions as the log
		1115	format option in rsyncd.conf.
		1116
		1117
		1118	__--stats__
		1119
		1120
		1121	This tells rsync to print a verbose set of statistics on the
		1122	file transfer, allowing you to tell how effective the rsync
		1123	algorithm is for your data.
		1124
		1125
		1126	__--partial__
		1127
		1128
		1129	By default, rsync will delete any partially transferred file
		1130	if the transfer is interrupted. In some circumstances it is
		1131	more desirable to keep partially transferred files. Using
		1132	the --partial option tells rsync to keep the partial file
		1133	which should make a subsequent transfer of the rest of the
		1134	file much faster.
		1135
		1136
		1137	__--progress__
		1138
		1139
		1140	This option tells rsync to print information showing the
		1141	progress of the transfer. This gives a bored user something
		1142	to watch.
		1143
		1144
		1145	This option is normally combined with -v. Using this option
		1146	without the -v option will produce weird results on your
		1147	display.
		1148
		1149
		1150	__-P__
		1151
		1152
		1153	The -P option is equivalent to --partial --progress. I found
		1154	myself typing that combination quite often so I created an
		1155	option to make it easier.
		1156
		1157
		1158	__--password-file__
		1159
		1160
		1161	This option allows you to provide a password in a file for
		1162	accessing a remote rsync server. Note that this option is
		1163	only useful when accessing a rsync server using the built in
		1164	transport, not when using a remote shell as the transport.
		1165	The file must not be world readable. It should contain just
		1166	the password as a single line.
		1167
		1168
		1169	__--bwlimit=KBPS__
		1170
		1171
		1172	This option allows you to specify a maximum transfer rate in
		1173	kilobytes per second. This option is most effective when
		1174	using rsync with large files (several megabytes and up). Due
		1175	to the nature of rsync transfers, blocks of data are sent,
		1176	then if rsync determines the transfer was too fast, it will
		1177	wait before sending the next data block. The result is an
		1178	average transfer rate equalling the specified limit. A value
		1179	of zero specifies no limit.
		1180
		1181
		1182	__--write-batch=PREFIX__
		1183
		1184
		1185	Generate a set of files that can be transferred as a batch
		1186	update. Each filename in the set starts with PREFIX. See the
		1187
		1188
		1189	__--read-batch=PREFIX__
		1190
		1191
		1192	Apply a previously generated change batch, using the fileset
		1193	whose filenames start with PREFIX. See the
		1194	!!EXCLUDE PATTERNS
		1195
		1196
		1197	The exclude and include patterns specified to rsync allow
		1198	for flexible selection of which files to transfer and which
		1199	files to skip.
		1200
		1201
		1202	rsync builds an ordered list of include/exclude options as
		1203	specified on the command line. When a filename is
		1204	encountered, rsync checks the name against each
		1205	exclude/include pattern in turn. The first matching pattern
		1206	is acted on. If it is an exclude pattern, then that file is
		1207	skipped. If it is an include pattern then that filename is
		1208	not skipped. If no matching include/exclude pattern is found
		1209	then the filename is not skipped.
		1210
		1211
		1212	Note that when used with -r (which is implied by -a), every
		1213	subcomponent of every path is visited from top down, so
		1214	include/exclude patterns get applied recursively to each
		1215	subcomponent.
		1216
		1217
		1218	Note also that the --include and --exclude options take one
		1219	pattern each. To add multiple patterns use the
		1220	--include-from and --exclude-from options or multiple
		1221	--include and --exclude options.
		1222
		1223
		1224	The patterns can take several forms. The rules
		1225	are:
		1226
		1227
		1228	o
		1229
		1230
		1231	if the pattern starts with a / then it is matched against
		1232	the start of the filename, otherwise it is matched against
		1233	the end of the filename. Thus
		1234
		1235
		1236	o
		1237
		1238
		1239	if the pattern ends with a / then it will only match a
		1240	directory, not a file, link or device.
		1241
		1242
		1243	o
		1244
		1245
		1246	if the pattern contains a wildcard character from the set
		1247	*?[[ then expression matching is applied using the shell
		1248	filename matching rules. Otherwise a simple string match is
		1249	used.
		1250
		1251
		1252	o
		1253
		1254
		1255	if the pattern includes a double asterisk
		1256
		1257
		1258	o
		1259
		1260
		1261	if the pattern contains a / (not counting a trailing /) then
		1262	it is matched against the full filename, including any
		1263	leading directory. If the pattern doesnt contain a / then it
		1264	is matched only against the final component of the filename.
		1265	Again, remember that the algorithm is applied recursively so
		1266
		1267
		1268	o
		1269
		1270
		1271	if the pattern starts with
		1272
		1273
		1274	o
		1275
		1276
		1277	if the pattern starts with
		1278
		1279
		1280	o
		1281
		1282
		1283	if the pattern is a single exclamation mark ! then the
		1284	current include/exclude list is reset, removing all
		1285	previously defined patterns.
		1286
		1287
		1288	The +/- rules are most useful in exclude lists, allowing you
		1289	to have a single exclude list that contains both include and
		1290	exclude options.
		1291
		1292
		1293	If you end an exclude list with --exclude *, note that since
		1294	the algorithm is applied recursively that unless you
		1295	explicitly include parent directories of files you want to
		1296	include then the algorithm will stop at the parent
		1297	directories and never see the files below them. To include
		1298	all directories, use --include */ before the --exclude
		1299	*.
		1300
		1301
		1302	Here are some exclude/include examples:
		1303
		1304
		1305	o
		1306
		1307
		1308	--exclude
		1309
		1310
		1311	o
		1312
		1313
		1314	--exclude
		1315
		1316
		1317	o
		1318
		1319
		1320	--exclude
		1321
		1322
		1323	o
		1324
		1325
		1326	--exclude
		1327
		1328
		1329	o
		1330
		1331
		1332	--exclude
		1333
		1334
		1335	o
		1336
		1337
		1338	--include
		1339
		1340
		1341	o
		1342
		1343
		1344	--include
		1345	!!BATCH MODE
		1346
		1347
		1348	__Note:__ Batch mode should be considered experimental in
		1349	this version of rsync. The interface or behaviour may change
		1350	before it stabilizes.
		1351
		1352
		1353	Batch mode can be used to apply the same set of updates to
		1354	many identical systems. Suppose one has a tree which is
		1355	replicated on a number of hosts. Now suppose some changes
		1356	have been made to this source tree and those changes need to
		1357	be propagated to the other hosts. In order to do this using
		1358	batch mode, rsync is run with the write-batch option to
		1359	apply the changes made to the source tree to one of the
		1360	destination trees. The write-batch option causes the rsync
		1361	client to store the information needed to repeat this
		1362	operation against other destination trees in a batch update
		1363	fileset (see below). The filename of each file in the
		1364	fileset starts with a prefix specified by the user as an
		1365	argument to the write-batch option. This fileset is then
		1366	copied to each remote host, where rsync is run with the
		1367	read-batch option, again specifying the same prefix, and the
		1368	destination tree. Rsync updates the destination tree using
		1369	the information stored in the batch update
		1370	fileset.
		1371
		1372
		1373	The fileset consists of 4 files:
		1374
		1375
		1376	o
		1377
		1378
		1379	____ command-line
		1380	arguments
		1381
		1382
		1383	o
		1384
		1385
		1386	____ rsync internal file
		1387	metadata
		1388
		1389
		1390	o
		1391
		1392
		1393	____ rsync
		1394	checksums
		1395
		1396
		1397	o
		1398
		1399
		1400	____ data blocks for file
		1401	update __
		1402
		1403
		1404	The .rsync_argvs file contains a command-line suitable for
		1405	updating a destination tree using that batch update fileset.
		1406	It can be executed using a Bourne(-like) shell, optionally
		1407	passing in an alternate destination tree pathname which is
		1408	then used instead of the original path. This is useful when
		1409	the destination tree path differs from the original
		1410	destination tree path.
		1411
		1412
		1413	Generating the batch update fileset once saves having to
		1414	perform the file status, checksum and data block generation
		1415	more than once when updating multiple destination trees.
		1416	Multicast transport protocols can be used to transfer the
		1417	batch update files in parallel to many hosts at once,
		1418	instead of sending the same data to every host
		1419	individually.
		1420
		1421
		1422	Example:
		1423
		1424
		1425	$ rsync --write_batch=pfx -a /source/dir/ /adest/dir/
		1426	$ rcp pfx.rsync_* remote:
		1427	$ rsh remote rsync --read_batch=pfx -a /bdest/dir/
		1428	# or alternatively
		1429	$ rsh remote ./pfx.rsync_argvs /bdest/dir/
		1430
		1431
		1432	In this example, rsync is used to update /adest/dir/ with
		1433	/source/dir/ and the information to repeat this operation is
		1434	stored in the files pfx.rsync_*. These files are then copied
		1435	to the machine named
		1436
		1437
		1438	Caveats:
		1439
		1440
		1441	The read-batch option expects the destination tree it is
		1442	meant to update to be identical to the destination tree that
		1443	was used to create the batch update fileset. When a
		1444	difference between the destination trees is encountered the
		1445	update will fail at that point, leaving the destination tree
		1446	in a partially updated state. In that case, rsync can be
		1447	used in its regular (non-batch) mode of operation to fix up
		1448	the destination tree.
		1449
		1450
		1451	The rsync version used on all destinations should be
		1452	identical to the one used on the original
		1453	destination.
		1454
		1455
		1456	The -z/--compress option does not work in batch mode and
		1457	yields a usage error. A separate compression tool can be
		1458	used instead to reduce the size of the batch update files
		1459	for transport to the destination.
		1460
		1461
		1462	The -n/--dryrun option does not work in batch mode and
		1463	yields a runtime error.
		1464
		1465
		1466	See __http://www.ils.unc.edu/i2dsi/unc_rsync+.html__ for
		1467	papers and technical reports.
		1468	!!SYMBOLIC LINKS
		1469
		1470
		1471	Three basic behaviours are possible when rsync encounters a
		1472	symbolic link in the source directory.
		1473
		1474
		1475	By default, symbolic links are not transferred at all. A
		1476	message
		1477
		1478
		1479	If __--links__ is specified, then symlinks are recreated
		1480	with the same target on the destination. Note that
		1481	__--archive__ implies __--links__.
		1482
		1483
		1484	If __--copy-links__ is specified, then symlinks are
		1485	__
		1486
		1487
		1488	rsync also distinguishes
		1489	/etc/passwd__ in the public section of the site. Using
		1490	__--copy-unsafe-links__ will cause any links to be copied
		1491	as the file they point to on the destination. Using
		1492	__--safe-links__ will cause unsafe links to be ommitted
		1493	altogether.
		1494	!!DIAGNOSTICS
		1495
		1496
		1497	rsync occasionally produces error messages that may seem a
		1498	little cryptic. The one that seems to cause the most
		1499	confusion is
		1500
		1501
		1502	This message is usually caused by your startup scripts or
		1503	remote shell facility producing unwanted garbage on the
		1504	stream that rsync is using for its transport. The way to
		1505	diagnose this problem is to run your remote shell like
		1506	this:
		1507
		1508
		1509	rsh remotehost /bin/true
		1510
		1511
		1512	then look at out.dat. If everything is working correctly
		1513	then out.dat should be a zero length file. If you are
		1514	getting the above error from rsync then you will probably
		1515	find that out.dat contains some text or data. Look at the
		1516	contents and try to work out what is producing it. The most
		1517	common cause is incorrectly configured shell startup scripts
		1518	(such as .cshrc or .profile) that contain output statements
		1519	for non-interactive logins.
		1520
		1521
		1522	If you are having trouble debugging include and exclude
		1523	patterns, then try specifying the -vv option. At this level
		1524	of verbosity rsync will show why each individual file is
		1525	included or excluded.
		1526	!!EXIT VALUES
		1527
		1528
		1529	__RERR_SYNTAX 1__
		1530
		1531
		1532	Syntax or usage error
		1533
		1534
		1535	__RERR_PROTOCOL 2__
		1536
		1537
		1538	Protocol incompatibility
		1539
		1540
		1541	__RERR_FILESELECT 3__
		1542
		1543
		1544	Errors selecting input/output files, dirs
		1545
		1546
		1547	__RERR_UNSUPPORTED 4__
		1548
		1549
		1550	Requested action not supported: an attempt was made to
		1551	manipulate 64-bit files on a platform that cannot support
		1552	them; or an option was speciifed that is supported by the
		1553	client and not by the server.
		1554
		1555
		1556	__RERR_SOCKETIO 10__
		1557
		1558
		1559	Error in socket IO
		1560
		1561
		1562	__RERR_FILEIO 11__
		1563
		1564
		1565	Error in file IO
		1566
		1567
		1568	__RERR_STREAMIO 12__
		1569
		1570
		1571	Error in rsync protocol data stream
		1572
		1573
		1574	__RERR_MESSAGEIO 13__
		1575
		1576
		1577	Errors with program diagnostics
		1578
		1579
		1580	__RERR_IPC 14__
		1581
		1582
		1583	Error in IPC code
		1584
		1585
		1586	__RERR_SIGNAL 20__
		1587
		1588
		1589	Received SIGUSR1 or SIGINT
		1590
		1591
		1592	__RERR_WAITCHILD 21__
		1593
		1594
		1595	Some error returned by waitpid()
		1596
		1597
		1598	__RERR_MALLOC 22__
		1599
		1600
		1601	Error allocating core memory buffers
		1602
		1603
		1604	__RERR_TIMEOUT 30__
		1605
		1606
		1607	Timeout in data send/receive
		1608	!!ENVIRONMENT VARIABLES
		1609
		1610
		1611	__CVSIGNORE__
		1612
		1613
		1614	The CVSIGNORE environment variable supplements any ignore
		1615	patterns in .cvsignore files. See the --cvs-exclude option
		1616	for more details.
		1617
		1618
		1619	__RSYNC_RSH__
		1620
		1621
		1622	The RSYNC_RSH environment variable allows you to override
		1623	the default shell used as the transport for rsync. This can
		1624	be used instead of the -e option.
		1625
		1626
		1627	__RSYNC_PROXY__
		1628
		1629
		1630	The RSYNC_PROXY environment variable allows you to redirect
		1631	your rsync client to use a web proxy when connecting to a
		1632	rsync daemon. You should set RSYNC_PROXY to a hostname:port
		1633	pair.
		1634
		1635
		1636	__RSYNC_PASSWORD__
		1637
		1638
		1639	Setting RSYNC_PASSWORD to the required password allows you
		1640	to run authenticated rsync connections to a rsync daemon
		1641	without user intervention. Note that this does not supply a
		1642	password to a shell transport such as ssh.
		1643
		1644
		1645	__USER__ or __LOGNAME__
		1646
		1647
		1648	The USER or LOGNAME environment variables are used to
		1649	determine the default username sent to a rsync
		1650	server.
		1651
		1652
		1653	__HOME__
		1654
		1655
		1656	The HOME environment variable is used to find the users
		1657	default .cvsignore file.
		1658	!!FILES
		1659
		1660
		1661	/etc/rsyncd.conf
		1662	!!SEE ALSO
		1663
		1664
		1665	rsyncd.conf(5)
		1666	!!DIAGNOSTICS
		1667	!!BUGS
		1668
		1669
		1670	times are transferred as unix time_t values
		1671
		1672
		1673	file permissions, devices etc are transferred as native
		1674	numerical values
		1675
		1676
		1677	see also the comments on the --delete option
		1678
		1679
		1680	Please report bugs! The rsync bug tracking system is online
		1681	at http://rsync.samba.org/rsync/
		1682	!!VERSION
		1683
		1684
		1685	This man page is current for version 2.0 of
		1686	rsync
		1687	!!CREDITS
		1688
		1689
		1690	rsync is distributed under the GNU public license. See the
		1691	file COPYING for details.
		1692
		1693
		1694	A WEB site is available at http://rsync.samba.org/. The site
		1695	includes an FAQ-O-Matic which may cover questions unanswered
		1696	by this manual page.
		1697
		1698
		1699	The primary ftp site for rsync is
		1700	ftp://rsync.samba.org/pub/rsync.
		1701
		1702
		1703	We would be delighted to hear from you if you like this
		1704	program.
		1705
		1706
		1707	This program uses the excellent zlib compression library
		1708	written by Jean-loup Gailly and Mark Adler.
		1709	!!THANKS
		1710
		1711
		1712	Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen
		1713	Rothwell and David Bell for helpful suggestions, patches and
		1714	testing of rsync. Ive probably missed some people, my
		1715	apologies if I have.
		1716
		1717
		1718	Especial thanks also to: David Dykstra, Jos Backus,
		1719	Sebastian Krahmer.
		1720	!!AUTHOR
		1721
		1722
		1723	rsync was written by Andrew Tridgell
		1724
		1725
		1726	rsync is now maintained by Martin Pool
		1727
		1728
		1729	Mailing lists for support and development are available at
		1730	http://lists.samba.org
		1731
		1732
		1733	If you suspect you have found a security vulnerability in
		1734	rsync, please send it directly to Martin Pool and Andrew
		1735	Tridgell. For other enquiries, please use the mailing
		1736	list.
		1737	----