Merge Texinfo onto head.

doc/rsync.texinfo

+\input texinfo
+@setfilename rsync.info
+@settitle rsync
+@c %** end of header
+
+@titlepage
+@sp 10
+@title rsync - fast, flexible file transfer program
+
+@c The copyright page
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2002 by Martin Pool @email{mbp@@samba.org}
+
+Copyright @copyright{} 1996--2001 by Andrew Tridgell @email{tridge@@samba.org}
+@end titlepage
+
+@iftex
+@contents
+@end iftex
+
+@ifnottex
+@node Top, Overview, (dir), (dir)
+@top rsync
+
+rsync is a flexible program for efficiently copying files or directory
+trees.
+
+This manual documents rsync 2.5.  It is not yet complete and should be
+consulted in conjunction with the rsync manual page.
+
+Copyright @copyright{} 2002 by Martin Pool @email{mbp@@samba.org}.
+
+Copyright @copyright{} 1996--2001 by Andrew Tridgell @email{tridge@@samba.org}.
+
+@menu
+* Overview::                    Tutorial section
+* Invoking rsync::              
+* Daemon mode::                 rsync listens for connections on its own socket
+
+* Concept Index::               
+* Option Index::                
+@end menu
+
+@end ifnottex
+
+@node Overview, Invoking rsync, Top, Top
+@chapter Overview
+
+rsync is a program for efficiently copying files or directory trees.
+rsync has many options to select which files will be copied and how
+they are to be transferred.  It may be used as an alternative to @sc{ftp},
+@sc{http}, @command{scp} or @command{rcp}.
+
+The rsync remote-update protocol allows rsync to transfer just the
+differences between two sets of files across the network link, using
+an efficient checksum-search algorithm described in the technical
+report that accompanies this package.
+
+rsync's command line syntax is analogous to @command{cp},
+@command{rcp} and @command{scp}:
+
+@example
+rsync [@var{options}] @var{source} @var{destination}
+@end example
+
+Filenames may be prefixed by a hostname to indicate a remote file.
+(@xref{Local and remote}.)
+
+Some of the additional features of rsync are:
+
+@itemize @bullet
+
+@item support for copying links, devices, owners, groups and permissions
+
+@item exclude and exclude-from options similar to GNU tar
+
+@item a CVS exclude mode for ignoring the same files that CVS would ignore
+
+@item can use any transparent remote shell, including rsh or ssh
+
+@item does not require root privileges
+
+@item pipelining of file transfers to minimize latency costs
+
+@item support for anonymous or authenticated rsync servers (ideal for
+mirroring)
+
+@end itemize
+
+@menu
+* Introductory example::        60-second guide to rsync      
+* Local and remote::            Local, remote, and server mode
+* Setting up rsync::            
+@end menu
+
+
+
+@node Introductory example, Local and remote, Overview, Overview
+@section Introductory example
+
+Probably the most common case of rsync usage is to copy files to or
+from a remote machine using @command{ssh} as a network transport.  In
+this situation rsync is a good alternative to @command{scp}.
+
+The most commonly used arguments for rsync are
+
+@table @code
+
+@item -a 
+Reproduce the structure and attributes of the origin files as exactly
+as possible: this includes copying subdirectories, symlinks, special
+files, ownership and permissions.  (@xref{Attributes to copy}.)
+
+@item -v 
+Be verbose.  Primarily, display the name of each file as it is copied.
+
+@item -z 
+Compress network traffic, using a modified version of the
+@command{zlib} library.
+
+@item -P
+Display a progress indicator while files are transferred.  This should
+normally be ommitted if rsync is not run on a terminal.
+
+@end table
+
+To make a backup of your home directory to the @file{/bkup/mbp/}
+remote machine @file{foo.example.org}, preserving the directory
+structure, use this command:
+
+@example
+rsync -avP ~ foo.example.org:/bkup/mbp/
+@end example
+
+
+
+@node Local and remote, Setting up rsync, Introductory example, Overview
+@comment  node-name,  next,  previous,  up
+@section Local and remote
+
+There are six different ways of using rsync. They are:
+
+@enumerate
+
+@item for copying local files. This is invoked when neither
+source nor destination path contains a @code{:} separator
+
+@item for copying from the local machine to a remote machine using
+a remote shell program as the transport (such as rsh or
+ssh). This is invoked when the destination path contains a
+single @code{:} separator.
+
+@item for copying from a remote machine to the local machine
+using a remote shell program. This is invoked when the source
+contains a @code{:} separator.
+
+@item for copying from a remote rsync server to the local
+machine. This is invoked when the source path contains a @code{::}
+separator or a @code{rsync://} URL.
+
+@item for copying from the local machine to a remote rsync
+server. This is invoked when the destination path contains a @code{::}
+separator.
+
+@item for listing files on a remote machine. This is done the
+same way as rsync transfers except that you leave off the
+local destination.  
+@cindex listing files
+@end enumerate
+
+Note that in all cases (other than listing) at least one of the source
+and destination paths must be local.
+
+Any one invocation of rsync makes a copy in a single direction.  rsync
+currently has no equivalent of @command{ftp}'s interactive mode.
+
+@cindex @sc{nfs}
+@cindex network filesystems
+@cindex remote filesystems
+
+rsync's network protocol is generally faster at copying files than
+network filesystems such as @sc{nfs} or @sc{cifs}.  It is better to
+run rsync on the file server either as a daemon or over ssh than
+running rsync giving the network directory.
+
+
+@node Setting up rsync,  , Local and remote, Overview
+@comment  node-name,  next,  previous,  up
+@section Setting up rsync
+
+@cindex installation
+See the file @sc{install} that comes with the distribution for installation
+instructions.
+
+@cindex @command{rsh}
+@cindex @command{rsh}, alternatives to
+@cindex @command{ssh} 
+
+Once installed you can use rsync to any machine that you can use
+@command{rsh} to.  rsync uses @command{rsh} for its communications,
+unless both the source and destination are local.
+
+You can also specify an alternative to rsh, either by using the
+@option{-e} command line option, or by setting the
+@var{@sc{rsync_rsh}} environment variable.
+
+One common substitute is to use @command{ssh}, which offers a high
+degree of security.
+
+Note that rsync must be installed on both the source and destination
+machines. 
+
+
+
+@node Invoking rsync, Daemon mode, Overview, Top
+@comment  node-name,  next,  previous,  up
+@chapter Invoking rsync
+
+
+@menu
+* Controlling rsync messages::  
+* Attributes to copy::          
+* Exit values::                 
+@end menu
+
+
+
+@node  Controlling rsync messages, Attributes to copy, Invoking rsync, Invoking rsync
+@comment  node-name,  next,  previous,  up
+@section Controlling rsync messages
+
+@table @option
+
+@item --version
+@vindex --version
+Print the rsync version number and compilation information and exit
+
+@item --help
+@vindex --help
+Print a short help page describing the options available and exit.
+
+@item --stats
+@vindex --stats
+Print statistics about rsync perfomance.
+
+@item -v
+@itemx --verbose
+@vindex -v
+@vindex --verbose
+This option increases the amount of information you are given during
+the transfer.  By default, rsync works silently.  A single -v will
+give you information about what files are being transferred and a
+brief summary at the end.  Two -v flags will give you information on
+network connections, files skipped, and slightly more information at
+the end.  More than two -v flags should only be used if you are
+debugging rsync.
+@end table
+
+
+@node Attributes to copy, Exit values, Controlling rsync messages, Invoking rsync
+@comment  node-name,  next,  previous,  up
+@section Attributes to copy
+
+@table @option
+
+@item -a
+@vindex -a
+@vindex --archive
+@cindex archive mode
+
+Preserve as much as possible of the structure and attributes of the
+origin directory.
+
+On many systems, only the superuser can set the ownership of files,
+and users can only put files into a group to which that user belongs.
+rsync works within the operating system security model.  So on such a
+system, if you copy a file which you can read but that does not belong
+to you, the destination file will be owned by you.  The only way to
+change this behaviour is to copy the file as the superuser, or to
+adjust your operating system's security model if that is possible.
+
+@quotation
+@strong{Please note:} @option{--archive} does not detect files with
+multiple names.  If any exist, they will become multiple identical
+files on the destination.  To make the names all refer to the same
+file, use @option{--hard-links}.
+@end quotation     
+
+@end table
+
+
+
+@node  Exit values,  , Attributes to copy, Invoking rsync
+@comment  node-name,  next,  previous,  up
+@section Exit values
+
+@cindex exit code
+@cindex return code
+
+rsync's exit code may be examined by shell scripts to determine
+whether the transfer completed successfully or not.
+
+@table @code
+
+@item RERR_SYNTAX     1
+Syntax or usage error 
+
+@item RERR_PROTOCOL   2
+Protocol incompatibility 
+
+@item RERR_FILESELECT 3
+Errors selecting input/output files, dirs
+
+@item RERR_UNSUPPORTED 4
+Requested action not supported: an attempt
+was made to manipulate 64-bit files on a platform that cannot support
+them; or an option was speciifed that is supported by the client and
+not by the server.
+
+@item RERR_SOCKETIO   10
+Error in socket IO 
+
+@item RERR_FILEIO     11
+Error in file IO 
+
+@item RERR_STREAMIO   12
+Error in rsync protocol data stream 
+
+@item RERR_MESSAGEIO  13
+Errors with program diagnostics 
+
+@item RERR_IPC        14
+Error in @sc{ipc} code 
+
+@item RERR_SIGNAL     20
+Received @sc{sigusr1} or @sc{sigint}
+
+@item RERR_WAITCHILD  21
+Some error returned by @code{waitpid()}
+
+@item RERR_MALLOC     22
+Error allocating core memory buffers 
+
+@item RERR_TIMEOUT    30
+Timeout in data send/receive 
+
+@end table
+
+
+
+@node Daemon mode, Concept Index, Invoking rsync, Top
+@chapter Daemon mode
+
+@cindex daemon mode
+@cindex demon mode
+@cindex @command{rsyncd}
+@vindex --daemon
+
+Configuring rsync as a server is entirely optional.  If you just want
+to copy your own files between local directories or machines, then
+using rsync over @command{ssh} may well be sufficient.  Daemon mode
+may be useful if you wish to distribute files to a number of machines
+on a network, or to the public.
+
+@vindex --port
+@cindex port 873
+@cindex @sc{tcp} port 873
+
+@sc{Tcp} port 873 is reserved for rsync by the Internet Assigned
+Numbers Authority (@sc{iana}) and has the service name @code{rsync}.
+However, rsync may be run on any other port using the @option{--port}
+option.
+
+@menu
+* Daemon mode security::        
+@end menu
+
+@node  Daemon mode security,  , Daemon mode, Daemon mode
+@section Daemon mode security
+
+@node     Concept Index, Option Index, Daemon mode, Top
+@comment      node-name, next,       previous, up
+@unnumbered Concept Index
+
+@printindex cp
+
+
+
+@node  Option Index,  , Concept Index, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Option Index
+
+@printindex vr
+
+@bye