Annotation of embedaddon/rsync/doc/rsync.sgml, revision 1.1.1.2

1.1       misho       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</option></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</option></term>
                    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
1.1.1.2 ! misho     129:        normally be omitted if rsync is not run on a terminal.
1.1       misho     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: 
                    205: 
                    206: 
                    207:   <chapter>
                    208:     <title>Frequently asked questions</title>
                    209: 
                    210:     
                    211:     <!-- 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 SECTION SIMPLESECT REFENTRY SECT1) -->
                    212:     <qandaset>
                    213:       <!-- one of (QANDADIV QANDAENTRY) -->
                    214: 
                    215:       <qandaentry>
                    216:        <question>
                    217:          <!-- one of (CALLOUTLIST GLOSSLIST ITEMIZEDLIST ORDEREDLIST
                    218:          SEGMENTEDLIST SIMPLELIST VARIABLELIST CAUTION IMPORTANT NOTE
                    219:          TIP WARNING LITERALLAYOUT PROGRAMLISTING PROGRAMLISTINGCO
                    220:          SCREEN SCREENCO SCREENSHOT SYNOPSIS CMDSYNOPSIS FUNCSYNOPSIS
                    221:          CLASSSYNOPSIS FIELDSYNOPSIS CONSTRUCTORSYNOPSIS
                    222:          DESTRUCTORSYNOPSIS METHODSYNOPSIS FORMALPARA PARA SIMPARA
                    223:          ADDRESS BLOCKQUOTE GRAPHIC GRAPHICCO MEDIAOBJECT
                    224:          MEDIAOBJECTCO INFORMALEQUATION INFORMALEXAMPLE
                    225:          INFORMALFIGURE INFORMALTABLE EQUATION EXAMPLE FIGURE TABLE
                    226:          PROCEDURE ANCHOR BRIDGEHEAD REMARK HIGHLIGHTS INDEXTERM) -->
                    227:          <para>Are there mailing lists for rsync?
                    228:        </question>
                    229: 
                    230:        <answer>
                    231:          <para>Yes, and you can subscribe and unsubscribe through a
                    232:          web interface at
                    233:            <ulink
                    234:              url="http://lists.samba.org/">http://lists.samba.org/</ulink>
                    235:          </para>
                    236: 
                    237:          <para>
                    238:            If you are having trouble with the mailing list, please
                    239:            send mail to the administrator
                    240:            
                    241:            <email>rsync-admin@lists.samba.org</email>
                    242: 
                    243:            not to the list itself.
                    244:          </para>
                    245: 
                    246:          <para>
                    247:            The mailing list archives are searchable.  Use 
                    248:            <ulink url="http://google.com/">Google</ulink> and prepend
                    249:            the search with <userinput>site:lists.samba.org
                    250:            rsync</userinput>, plus relevant keywords.
                    251:          </para>
                    252:        </answer>
                    253:       </qandaentry>
                    254: 
                    255: 
                    256:       <qandaentry>
                    257:        <question>
                    258:          <para>
                    259:            Why is rsync so much bigger when I build it with
                    260:            <command>gcc</command>?
                    261:          </para>
                    262:        </question>
                    263:        <answer>
                    264:          <para>
                    265:            On gcc, rsync builds by default with debug symbols
                    266:            included.  If you strip both executables, they should end
                    267:            up about the same size.  (Use <command>make
                    268:            install-strip</command>.)
                    269:          </para>
                    270:        </answer>
                    271:       </qandaentry>
                    272: 
                    273:       
                    274:       <qandaentry>
                    275:        <question>
                    276:          <para>Is rsync useful for a single large file like an ISO image?</para>
                    277:        </question>
                    278:        <answer>
                    279:          <para>
                    280:            Yes, but note the following:
                    281: 
                    282:          <para>
                    283:    Background: A common use of rsync is to update a file (or set of files) in one location from a more
                    284:    correct or up-to-date copy in another location, taking advantage of portions of the files that are
                    285:    identical to speed up the process. (Note that rsync will transfer a file in its entirety if no copy
                    286:    exists at the destination.)
                    287: 
                    288:          <para>
                    289:    (This discussion is written in terms of updating a local copy of a file from a correct file in a
                    290:    remote location, although rsync can work in either direction.)
                    291: 
                    292:          <para>
                    293:    The file to be updated (the local file) must be in a destination directory that has enough space for
                    294:    two copies of the file. (In addition, keep an extra copy of the file to be updated in a different
                    295:    location for safety -- see the discussion (below) about rsync's behavior when the rsync process is
                    296:    interrupted before completion.)
                    297: 
                    298:          <para>
                    299:    The local file must have the same name as the remote file being sync'd to (I think?). If you are
                    300:    trying to upgrade an iso from, for example, beta1 to beta2, rename the local file to the same name
                    301:    as the beta2 file. *(This is a useful thing to do -- only the changed portions will be
                    302:    transmitted.)*
                    303: 
                    304:          <para>
                    305:    The extra copy of the local file kept in a different location is because of rsync's behavior if
                    306:    interrupted before completion:
                    307: 
                    308:          <para>
                    309:    * If you specify the --partial option and rsync is interrupted, rsync will save the partially
                    310:    rsync'd file and throw away the original local copy. (The partially rsync'd file is correct but
                    311:    truncated.) If rsync is restarted, it will not have a local copy of the file to check for duplicate
                    312:    blocks beyond the section of the file that has already been rsync'd, thus the remainder of the rsync
                    313:    process will be a "pure transfer" of the file rather than taking advantage of the rsync algorithm.
                    314: 
                    315:          <para>
                    316:    * If you don't specify the --partial option and rsync is interrupted, rsync will throw away the
                    317:    partially rsync'd file, and, when rsync is restarted starts the rsync process over from the
                    318:    beginning.
                    319: 
                    320:          <para>
                    321:    Which of these is most desirable depends on the degree of commonality between the local and remote
                    322:    copies of the file *and how much progress was made before the interruption*.
                    323: 
                    324:          <para>
                    325:    The ideal approach after an interruption would be to create a new file by taking the original file
                    326:    and deleting a portion equal in size to the portion already rsync'd and then appending *the
                    327:    remaining* portion to the portion of the file that has already been rsync'd. (There has been some
                    328:    discussion about creating an option to do this automatically.)
                    329: 
                    330:    The --compare-dest option is useful when transferring multiple files, but is of no benefit in
                    331:    transferring a single file. (AFAIK)
                    332: 
                    333:    *Other potentially useful information can be found at:
                    334:    -[3]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFile
                    335: 
                    336:    This answer, formatted with "real" bullets, can be found at:
                    337:    -[4]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFileFAQ*
                    338: 
                    339:          </para>
                    340:        </answer>
                    341:       </qandaentry>
                    342:     </qandaset>
                    343:   </chapter>
                    344: 
                    345: 
                    346:   <appendix>
                    347:     <title>Other Resources</title>
                    348:     
                    349:     <para><ulink url="http://www.ccp14.ac.uk/ccp14admin/rsync/"></ulink></para>
                    350:   </appendix>
1.1.1.2 ! misho     351: </book>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>