doc/rsync.sgml

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <book id="rsync">
   3   <bookinfo>
   4     <title>rsync</title>
   5     <copyright>
   6       <year>1996 -- 2002</year>
   7       <holder>Martin Pool</holder>
   8       <holder>Andrew Tridgell</holder>
   9     </copyright>
  10     <author>
  11       <firstname>Martin</firstname>
  12       <surname>Pool</surname>
  13     </author>
  14   </bookinfo>
  15
  16   <chapter>
  17     <title>Introduction</title>
  18
  19     <para>rsync is a flexible program for efficiently copying files or
  20       directory trees.
  21
  22     <para>rsync has many options to select which files will be copied
  23       and how they are to be transferred.  It may be used as an
  24       alternative to ftp, http, scp or rcp.
  25
  26     <para>The rsync remote-update protocol allows rsync to transfer just
  27       the differences between two sets of files across the network link,
  28       using an efficient checksum-search algorithm described in the
  29       technical report that accompanies this package.</para>
  30
  31     <para>Some of the additional features of rsync are:</para>
  32
  33     <itemizedlist>
  34
  35       <listitem>
  36         <para>support for copying links, devices, owners, groups and
  37           permissions
  38         </para>
  39       </listitem>
  40
  41       <listitem>
  42         <para>
  43           exclude and exclude-from options similar to GNU tar
  44         </para>
  45       </listitem>
  46
  47       <listitem>
  48         <para>
  49           a CVS exclude mode for ignoring the same files that CVS would ignore
  50       </listitem>
  51
  52       <listitem>
  53         <para>
  54           can use any transparent remote shell, including rsh or ssh
  55       </listitem>
  56
  57       <listitem>
  58         <para>
  59           does not require root privileges
  60       </listitem>
  61
  62       <listitem>
  63         <para>
  64           pipelining of file transfers to minimize latency costs
  65       </listitem>
  66
  67       <listitem>
  68         <para>
  69           support for anonymous or authenticated rsync servers (ideal for
  70           mirroring)
  71         </para>
  72       </listitem>
  73     </itemizedlist>
  74   </chapter>
  75
  76
  77
  78   <chapter>
  79     <title>Using rsync</title>
  80     <section>
  81       <title>
  82         Introductory example
  83       </title>
  84
  85       <para>
  86         Probably the most common case of rsync usage is to copy files
  87         to or from a remote machine using
  88         <application>ssh</application> as a network transport.  In
  89         this situation rsync is a good alternative to
  90         <application>scp</application>.
  91       </para>
  92
  93       <para>
  94         The most commonly used arguments for rsync are
  95       </para>
  96
  97       <variablelist>
  98         <varlistentry>
  99           <term><option>-v</term>
 100           <listitem>
 101             <para>Be verbose.  Primarily, display the name of each file as it is copied.</para>
 102           </listitem>
 103         </varlistentry>
 104
 105
 106         <varlistentry>
 107           <term><option>-a
 108           <listitem>
 109             <para>
 110               Reproduce the structure and attributes of the origin files as exactly
 111               as possible: this includes copying subdirectories, symlinks, special
 112               files, ownership and permissions.  (@xref{Attributes to
 113               copy}.)
 114             </para>
 115           </listitem>
 116         </varlistentry>
 117       </variablelist>
 118
 119
 120
 121       <para><option>-v </option>
 122
 123       <para><option>-z</option>
 124         Compress network traffic, using a modified version of the
 125         @command{zlib} library.</para>
 126
 127       <para><option>-P</option>
 128         Display a progress indicator while files are transferred.  This should
 129         normally be ommitted if rsync is not run on a terminal.
 130       </para>
 131     </section>
 132
 133
 134
 135
 136     <section>
 137       <title>Local and remote</title>
 138
 139       <para>There are six different ways of using rsync. They
 140       are:</para>
 141
 142
 143
 144       <!-- one of (CALLOUTLIST GLOSSLIST ITEMIZEDLIST ORDEREDLIST SEGMENTEDLIST SIMPLELIST VARIABLELIST CAUTION IMPORTANT NOTE TIP WARNING LITERALLAYOUT PROGRAMLISTING PROGRAMLISTINGCO SCREEN SCREENCO SCREENSHOT SYNOPSIS CMDSYNOPSIS FUNCSYNOPSIS CLASSSYNOPSIS FIELDSYNOPSIS CONSTRUCTORSYNOPSIS DESTRUCTORSYNOPSIS METHODSYNOPSIS FORMALPARA PARA SIMPARA ADDRESS BLOCKQUOTE GRAPHIC GRAPHICCO MEDIAOBJECT MEDIAOBJECTCO INFORMALEQUATION INFORMALEXAMPLE INFORMALFIGURE INFORMALTABLE EQUATION EXAMPLE FIGURE TABLE MSGSET PROCEDURE SIDEBAR QANDASET ANCHOR BRIDGEHEAD REMARK HIGHLIGHTS ABSTRACT AUTHORBLURB EPIGRAPH INDEXTERM REFENTRY SECTION) -->
 145       <orderedlist>
 146         <listitem>
 147           <para>
 148             for copying local files. This is invoked when neither
 149             source nor destination path contains a @code{:} separator
 150
 151         <listitem>
 152           <para>
 153             for copying from the local machine to a remote machine using
 154             a remote shell program as the transport (such as rsh or
 155             ssh). This is invoked when the destination path contains a
 156             single @code{:} separator.
 157
 158         <listitem>
 159           <para>
 160             for copying from a remote machine to the local machine
 161             using a remote shell program. This is invoked when the source
 162             contains a @code{:} separator.
 163
 164         <listitem>
 165           <para>
 166             for copying from a remote rsync server to the local
 167             machine. This is invoked when the source path contains a @code{::}
 168             separator or a @code{rsync://} URL.
 169
 170         <listitem>
 171           <para>
 172             for copying from the local machine to a remote rsync
 173             server. This is invoked when the destination path contains a @code{::}
 174             separator.
 175
 176         <listitem>
 177           <para>
 178             for listing files on a remote machine. This is done the
 179             same way as rsync transfers except that you leave off the
 180             local destination.
 181
 182         </listitem>
 183       </orderedlist>
 184           <para>
 185 Note that in all cases (other than listing) at least one of the source
 186 and destination paths must be local.
 187
 188           <para>
 189 Any one invocation of rsync makes a copy in a single direction.  rsync
 190 currently has no equivalent of @command{ftp}'s interactive mode.
 191
 192 @cindex @sc{nfs}
 193 @cindex network filesystems
 194 @cindex remote filesystems
 195
 196           <para>
 197 rsync's network protocol is generally faster at copying files than
 198 network filesystems such as @sc{nfs} or @sc{cifs}.  It is better to
 199 run rsync on the file server either as a daemon or over ssh than
 200 running rsync giving the network directory.
 201       </para>
 202     </section>
 203   </chapter>
 204 </book>