home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / rsync221.zip / rsync.man < prev    next >
Text File  |  1999-03-12  |  43KB  |  1,255 lines

  1.  
  2.  
  3.  
  4. rsync(1)                                                 rsync(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        rsync - faster, flexible replacement for rcp
  9.  
  10. SSYYNNOOPPSSIISS
  11.        rsync [options] [user@]host:path path
  12.  
  13.        rsync [options] path [user@]host:path
  14.  
  15.        rsync [options] path path
  16.  
  17.        rsync [options] [user@]host::module[/path] path
  18.  
  19.        rsync [options] path [user@]host::module[/path]
  20.  
  21.        rsync   [options]   rsync://[user@]host[:port]/module/path
  22.        path
  23.  
  24.  
  25. DDEESSCCRRIIPPTTIIOONN
  26.        rsync is a program that behaves in much the same way  that
  27.        rcp  does,  but  has  many more options and uses the rsync
  28.        remote-update protocol to greatly speedup  file  transfers
  29.        when the destination file already exists.
  30.  
  31.        The  rsync remote-update protocol allows rsync to transfer
  32.        just the differences between two sets of files across  the
  33.        network link, using an efficient checksum-search algorithm
  34.        described in the technical report  that  accompanies  this
  35.        package.
  36.  
  37.        Some of the additional features of rsync are:
  38.  
  39.  
  40.        o      support  for copying links, devices, owners, groups
  41.               and permissions
  42.  
  43.        o      exclude and exclude-from options similar to GNU tar
  44.  
  45.        o      a CVS exclude mode for ignoring the same files that
  46.               CVS would ignore
  47.  
  48.        o      can use any transparent remote shell, including rsh
  49.               or ssh
  50.  
  51.        o      does not require root privileges
  52.  
  53.        o      pipelining  of  file  transfers to minimize latency
  54.               costs
  55.  
  56.        o      support  for  anonymous  or   authenticated   rsync
  57.               servers (ideal for mirroring)
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                            24 Nov 1998                          1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. rsync(1)                                                 rsync(1)
  71.  
  72.  
  73. GGEENNEERRAALL
  74.        There are six different ways of using rsync. They are:
  75.  
  76.  
  77.        o      for  copying local files. This is invoked when nei-
  78.               ther source nor destination path contains a : sepa-
  79.               rator
  80.  
  81.  
  82.        o      for  copying  from  the  local  machine to a remote
  83.               machine using a remote shell program as the  trans-
  84.               port (such as rsh or ssh). This is invoked when the
  85.               destination path contains a single : separator.
  86.  
  87.  
  88.        o      for copying from a  remote  machine  to  the  local
  89.               machine  using  a  remote  shell  program.  This is
  90.               invoked when the local path contains a : separator.
  91.  
  92.  
  93.        o      for copying from a remote rsync server to the local
  94.               machine. This is invoked when the source path  con-
  95.               tains a :: separator or a rsync:// URL.
  96.  
  97.  
  98.        o      for  copying  from  the  local  machine to a remote
  99.               rsync server. This is invoked when the  destination
  100.               path contains a :: separator.
  101.  
  102.  
  103.        o      for listing files on a remote machine. This is done
  104.               the same way as rsync  transfers  except  that  you
  105.               leave off the local destination.
  106.  
  107.        Note that in all cases at least one of the source and des-
  108.        tination paths must be local.
  109.  
  110.  
  111. SSEETTUUPP
  112.        See the file README for installation instructions.
  113.  
  114.        Once installed you can use rsync to any machine  that  you
  115.        can  use  rsh  to.  rsync uses rsh for its communications,
  116.        unless both the source and destination are local.
  117.  
  118.        You can also specify a alternative to rsh, by either using
  119.        the  -e  command  line option, or by setting the RSYNC_RSH
  120.        environment variable.
  121.  
  122.        One common substitute is to use ssh, which offers  a  high
  123.        degree of security.
  124.  
  125.        Note  that  rsync must be installed on both the source and
  126.        destination machines.
  127.  
  128.  
  129.  
  130.                            24 Nov 1998                          2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. rsync(1)                                                 rsync(1)
  137.  
  138.  
  139. UUSSAAGGEE
  140.        You use rsync in the same way you use rcp. You must  spec-
  141.        ify  a  source  and  a  destination,  one  of which may be
  142.        remote.
  143.  
  144.        Perhaps the best way to explain the syntax is  some  exam-
  145.        ples:
  146.  
  147.               rsync *.c foo:src/
  148.  
  149.        this  would  transfer  all  files matching the pattern *.c
  150.        from the current directory to the  directory  src  on  the
  151.        machine  foo.  If  any  of  the files already exist on the
  152.        remote system then the  rsync  remote-update  protocol  is
  153.        used  to  update the file by sending only the differences.
  154.        See the tech report for details.
  155.  
  156.               rsync -avz foo:src/bar /data/tmp
  157.  
  158.        recursively transfer all files from the directory  src/bar
  159.        on the machine foo into the /data/tmp/bar directory on the
  160.        local machine. The  files  are  transferred  in  "archive"
  161.        mode,   which   ensures   that  symbolic  links,  devices,
  162.        attributes, permissions, ownerships etc are  preserved  in
  163.        the  transfer.   Additionally  compression will be used to
  164.        reduce the size of data portions of the transfer.
  165.  
  166.               rsync -avz foo:src/bar/ /data/tmp
  167.  
  168.        a trailing slash on the source changes  this  behavior  to
  169.        transfer  all  files  from  the  directory  src/bar on the
  170.        machine foo into the /data/tmp/.  A trailing / on a source
  171.        name means "copy the contents of this directory".  Without
  172.        a trailing slash it means "copy the directory". This  dif-
  173.        ference  becomes  particularly  important  when  using the
  174.        --delete option.
  175.  
  176.        You can also use rsync in local-only mode, where both  the
  177.        source  and  destination  don't have a ':' in the name. In
  178.        this case it behaves like an improved copy command.
  179.  
  180.  
  181. CCOONNNNEECCTTIINNGG TTOO AANN RRSSYYNNCC SSEERRVVEERR
  182.        It is also possible to use rsync without using rsh or  ssh
  183.        as  the  transport.  In  this  case  you will connect to a
  184.        remote rsync server running on TCP port 873.
  185.  
  186.        Using rsync in this was is the same as using it  with  rsh
  187.        or ssh except that:
  188.  
  189.  
  190.        o      you use a double colon :: instead of a single colon
  191.               to separate the hostname from the path.
  192.  
  193.  
  194.  
  195.  
  196.                            24 Nov 1998                          3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. rsync(1)                                                 rsync(1)
  203.  
  204.  
  205.        o      the remote server may print a message  of  the  day
  206.               when you connect
  207.  
  208.  
  209.        o      if  you  specify  no path name on the remote server
  210.               then the list of accessible  paths  on  the  server
  211.               will be shown.
  212.  
  213.  
  214.        o      if  you specify no local destination then a listing
  215.               of the specified files on the remote server is pro-
  216.               vided
  217.  
  218.        Some  paths  on  the remote server may require authentica-
  219.        tion. If so then you will receive a password  prompt  when
  220.        you  connect. You can avoid the password prompt by setting
  221.        the environment variable RSYNC_PASSWORD  to  the  password
  222.        you  want to use. This may be useful when scripting rsync.
  223.  
  224.  
  225. RRUUNNNNIINNGG AANN RRSSYYNNCC SSEERRVVEERR
  226.        An rsync server is configured using a config file which by
  227.        default   is   called  /etc/rsyncd.conf.  Please  see  the
  228.        rsyncd.conf(5) man page for more information.
  229.  
  230.  
  231. EEXXAAMMPPLLEESS
  232.        Here are some examples of how I use rsync.
  233.  
  234.        To backup my wife's  home  directory,  which  consists  of
  235.        large MS word files and mail folders I use a cron job that
  236.        runs
  237.  
  238.               rsync -Cavz . arvidsjaur:backup
  239.  
  240.        each night over a PPP link to a duplicate directory on  my
  241.        machine "arvidsjaur".
  242.  
  243.        To  synchronize  my samba source trees I use the following
  244.        Makefile targets:
  245.  
  246.               get:
  247.               rsync -avuzb --exclude '*~' samba:samba/ .
  248.  
  249.               put:
  250.               rsync -Cavuzb . samba:samba/
  251.  
  252.               sync: get put
  253.  
  254.        this allows me to sync with a CVS directory at  the  other
  255.        end  of  the  link. I then do cvs operations on the remote
  256.        machine, which saves a lot of time as the remote cvs  pro-
  257.        tocol isn't very efficient.
  258.  
  259.  
  260.  
  261.  
  262.                            24 Nov 1998                          4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. rsync(1)                                                 rsync(1)
  269.  
  270.  
  271.        I  mirror a directory between my "old" and "new" ftp sites
  272.        with the command
  273.  
  274.               rsync -az  -e  ssh  --delete  ~ftp/pub/samba/  nim-
  275.               bus:"~ftp/pub/tridge/samba"
  276.  
  277.        this is launched from cron every few hours.
  278.  
  279.  
  280. OOPPTTIIOONNSS SSUUMMMMAARRYY
  281.        Here  is a short summary of the options avalable in rsync.
  282.        Please refer to the detailed description below for a  com-
  283.        plete description.
  284.  
  285.  
  286.  
  287.  
  288.        Usage: rsync [OPTION]... SRC [USER@]HOST:DEST
  289.          or   rsync [OPTION]... [USER@]HOST:SRC DEST
  290.          or   rsync [OPTION]... SRC DEST
  291.          or   rsync [OPTION]... [USER@]HOST::SRC DEST
  292.          or   rsync [OPTION]... SRC [USER@]HOST::DEST
  293.          or    rsync  [OPTION]...  rsync://[USER@]HOST[:PORT]/SRC
  294.        DEST
  295.  
  296.        Options
  297.         -v, --verbose               increase verbosity
  298.         -c, --checksum              always checksum
  299.         -a, --archive               archive mode
  300.         -r, --recursive             recurse into directories
  301.         -R, --relative              use relative path names
  302.         -b,  --backup                 make  backups  (default   ~
  303.        extension)
  304.         -u,  --update                update only (don't overwrite
  305.        newer files)
  306.         -l, --links                 preserve soft links
  307.         -L, --copy-links            treat soft links like regular
  308.        files
  309.             --safe-links            ignore links outside the des-
  310.        tination tree
  311.         -H, --hard-links            preserve hard links
  312.         -p, --perms                 preserve permissions
  313.         -o, --owner                 preserve owner (root only)
  314.         -g, --group                 preserve group
  315.         -D, --devices               preserve devices (root only)
  316.         -t, --times                 preserve times
  317.         -S, --sparse                 handle  sparse  files  effi-
  318.        ciently
  319.         -n,  --dry-run                show  what  would have been
  320.        transferred
  321.         -W, --whole-file            copy whole files,  no  incre-
  322.        mental checks
  323.         -x, --one-file-system       don't cross filesystem bound-
  324.        aries
  325.  
  326.  
  327.  
  328.                            24 Nov 1998                          5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. rsync(1)                                                 rsync(1)
  335.  
  336.  
  337.         -B, --block-size=SIZE       checksum blocking size
  338.         -e, --rsh=COMMAND           specify rsh replacement
  339.             --rsync-path=PATH       specify path to rsync on  the
  340.        remote machine
  341.         -C, --cvs-exclude           auto ignore files in the same
  342.        way CVS does
  343.             --delete                delete files that don't exist
  344.        on the sending side
  345.             --partial                keep  partially  transferred
  346.        files
  347.             --force                 force deletion of directories
  348.        even if not empty
  349.             --numeric-ids            don't  map uid/gid values by
  350.        user/group name
  351.             --timeout=TIME          set IO timeout in seconds
  352.         -I,  --ignore-times           don't  exclude  files  that
  353.        match length and time
  354.         -T   --temp-dir=DIR           create  temporary  files in
  355.        directory DIR
  356.             --compare-dest=DIR       also   compare   destination
  357.        files relative to DIR
  358.         -z, --compress              compress file data
  359.             --exclude=PATTERN        exclude  files matching PAT-
  360.        TERN
  361.             --exclude-from=FILE     exclude files listed in FILE
  362.             --include=PATTERN       don't exclude files  matching
  363.        PATTERN
  364.             --include-from=FILE     don't exclude files listed in
  365.        FILE
  366.             --suffix=SUFFIX         override backup suffix
  367.             --version               print version number
  368.             --daemon                run as a rsync daemon
  369.             --config=FILE           specify alternate rsyncd.conf
  370.        file
  371.             --port=PORT             specify alternate rsyncd port
  372.        number
  373.             --stats                 give some file transfer stats
  374.             --progress              show progress during transfer
  375.             --log-format=FORMAT      log  file  transfers   using
  376.        specified format
  377.         -h, --help                  show this help screen
  378.  
  379.  
  380.  
  381.  
  382.  
  383. OOPPTTIIOONNSS
  384.        rsync  uses the GNU long options package. Many of the com-
  385.        mand line options have two variants,  one  short  and  one
  386.        long.   These  are  shown  below separated by commas. Some
  387.        options only have a long variant.
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                            24 Nov 1998                          6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. rsync(1)                                                 rsync(1)
  401.  
  402.  
  403.        --hh,, ----hheellpp
  404.               Print a short  help  page  describing  the  options
  405.               available in rsync
  406.  
  407.  
  408.        ----vveerrssiioonn
  409.               print the rsync version number and exit
  410.  
  411.  
  412.        --vv,, ----vveerrbboossee
  413.               This option increases the amount of information you
  414.               are given during the transfer.   By  default  rsync
  415.               works  silently. A single -v will give you informa-
  416.               tion about what files are being transferred  and  a
  417.               brief  summary  at  the end. Two -v flags will give
  418.               you information on what files are being skipped and
  419.               slightly more information at the end. More than two
  420.               -v flags should only be used if you  are  debugging
  421.               rsync
  422.  
  423.  
  424.        --II,, ----iiggnnoorree--ttiimmeess
  425.               Normally rsync will skip any files that are already
  426.               the same length and have the same time-stamp.  This
  427.               option turns off this behavior.
  428.  
  429.  
  430.        --cc,, ----cchheecckkssuumm
  431.               This  forces the sender to checksum all files using
  432.               a 128-bit MD4 checksum before transfer. The  check-
  433.               sum  is then explicitly checked on the receiver and
  434.               any files of the same name which already exist  and
  435.               have the same checksum and size on the receiver are
  436.               skipped.  This option can be quite slow.
  437.  
  438.  
  439.        --aa,, ----aarrcchhiivvee
  440.               This is equivalent to -rlptDg. It is a quick way of
  441.               saying  you  want  recursion  and  want to preserve
  442.               everything.
  443.  
  444.               Note: if the user launching rsync is root then  the
  445.               -o option (preserve uid) is also implied.
  446.  
  447.  
  448.        --rr,, ----rreeccuurrssiivvee
  449.               This tells rsync to copy directories recursively
  450.  
  451.  
  452.        --RR,, ----rreellaattiivvee
  453.               Use  relative  paths. This means that the full path
  454.               names specified on the command line are sent to the
  455.               server rather than just the last parts of the file-
  456.               names. This is particularly useful when you want to
  457.  
  458.  
  459.  
  460.                            24 Nov 1998                          7
  461.  
  462.  
  463.  
  464.  
  465.  
  466. rsync(1)                                                 rsync(1)
  467.  
  468.  
  469.               sent  several  different  directories  at  the same
  470.               time. For example, if you used the command
  471.  
  472.  
  473.  
  474.               rsync foo/bar/foo.c remote:/tmp/
  475.  
  476.  
  477.  
  478.               then this would create a file called foo.c in /tmp/
  479.               on the remote machine. If instead you used
  480.  
  481.  
  482.  
  483.               rsync -R foo/bar/foo.c remote:/tmp/
  484.  
  485.  
  486.  
  487.               then a file called /tmp/foo/bar/foo.c would be cre-
  488.               ated on the remote machine. The full path  name  is
  489.               preserved.
  490.  
  491.  
  492.        --bb,, ----bbaacckkuupp
  493.               With  this option preexisting destination files are
  494.               renamed with a ~ extension as each file  is  trans-
  495.               ferred.   You  can  control the backup suffix using
  496.               the --suffix option.
  497.  
  498.  
  499.        --uu,, ----uuppddaattee
  500.               This forces rsync to skip any files for  which  the
  501.               destination  file  already  exists  and  has a date
  502.               later than the source file.
  503.  
  504.  
  505.        --ll,, ----lliinnkkss
  506.               This tells rsync to recreate symbolic links on  the
  507.               remote system  to  be the same as the local system.
  508.               Without this option all symbolic links are skipped.
  509.  
  510.  
  511.        --LL,, ----ccooppyy--lliinnkkss
  512.               This  tells rsync to treat symbolic links just like
  513.               ordinary files.
  514.  
  515.  
  516.        ----ssaaffee--lliinnkkss
  517.               This tells rsync to ignore any symbolic links which
  518.               point  outside  the  destination tree. All absolute
  519.               symlinks are also ignored.  Using  this  option  in
  520.               conjunction  with  --relative  may  give unexpecetd
  521.               results.
  522.  
  523.  
  524.  
  525.  
  526.                            24 Nov 1998                          8
  527.  
  528.  
  529.  
  530.  
  531.  
  532. rsync(1)                                                 rsync(1)
  533.  
  534.  
  535.        --HH,, ----hhaarrdd--lliinnkkss
  536.               This tells rsync to recreate hard   links   on  the
  537.               remote system  to  be the same as the local system.
  538.               Without this option hard  links  are  treated  like
  539.               regular files.
  540.  
  541.               Note  that rsync can only detect hard links if both
  542.               parts of the link are in the list  of  files  being
  543.               sent.
  544.  
  545.               This  option  can  be quite slow, so only use it if
  546.               you need it.
  547.  
  548.  
  549.        --WW,, ----wwhhoollee--ffiillee
  550.               With this option the incremental rsync algorithm is
  551.               not  used   and   the  whole  file  is  sent  as-is
  552.               instead. This may be useful when using rsync with a
  553.               local machine.
  554.  
  555.  
  556.        ----ppaarrttiiaall
  557.               By  default  rsync will delete any partially trans-
  558.               ferred file if the transfer is interrupted. In some
  559.               circumstances  it  is  more  desirable to keep par-
  560.               tially  transferred  files.  Using  the   --partial
  561.               option  tells  rsync to keep the partial file which
  562.               should make a subsequent transfer of  the  rest  of
  563.               the file much faster.
  564.  
  565.  
  566.        --pp,, ----ppeerrmmss
  567.               This  option causes rsync to update the remote per-
  568.               missions to be the same as the local permissions.
  569.  
  570.  
  571.        --oo,, ----oowwnneerr
  572.               This option causes  rsync  to  update  the   remote
  573.               owner  of  the   file  to  be the same as the local
  574.               owner. This is only available  to  the  super-user.
  575.               Note  that  if  the source system is a daemon using
  576.               chroot, the --numeric-ids option is implied because
  577.               the  source  system  cannot  get access to the user
  578.               names.
  579.  
  580.  
  581.        --gg,, ----ggrroouupp
  582.               This option causes  rsync  to  update  the   remote
  583.               group  of  the  file  to  be  the same as the local
  584.               group.  Note that if the source system is a  daemon
  585.               using  chroot,  the --numeric-ids option is implied
  586.               because the source system cannot get access to  the
  587.               group names.
  588.  
  589.  
  590.  
  591.  
  592.                            24 Nov 1998                          9
  593.  
  594.  
  595.  
  596.  
  597.  
  598. rsync(1)                                                 rsync(1)
  599.  
  600.  
  601.        --DD,, ----ddeevviicceess
  602.               This  option causes rsync to transfer character and
  603.               block device information to the  remote  system  to
  604.               recreate  these devices. This option is only avail-
  605.               able to the super-user.
  606.  
  607.  
  608.        --tt,, ----ttiimmeess
  609.               This tells rsync  to  transfer  modification  times
  610.               along  with the files and update them on the remote
  611.               system.  Note that if this option is not used,  the
  612.               optimization that excludes files that have not been
  613.               modified cannot be effective;  in  other  words,  a
  614.               missing  -t  or  -a will cause the next transfer to
  615.               behave as if it used -I, and all  files  will  have
  616.               their  checksums  compared  and show up in log mes-
  617.               sages even if they haven't changed.
  618.  
  619.  
  620.        --nn,, ----ddrryy--rruunn
  621.               This tells rsync to  not  do  any  file  transfers,
  622.               instead  it  will  just report the actions it would
  623.               have taken.
  624.  
  625.  
  626.        --SS,, ----ssppaarrssee
  627.               Try to handle sparse files efficiently so they take
  628.               up less space on the destination.
  629.  
  630.               NOTE: Don't use this option when the destination is
  631.               a Solaris "tmpfs" filesystem. It  doesn't  seem  to
  632.               handle  seeks  over null regions correctly and ends
  633.               up corrupting the files.
  634.  
  635.  
  636.        --xx,, ----oonnee--ffiillee--ssyysstteemm
  637.               This tells rsync not to cross filesystem boundaries
  638.               when  recursing.   This  is useful for transferring
  639.               the contents of only one filesystem.
  640.  
  641.  
  642.        ----ddeelleettee
  643.               This tells rsync to delete any files on the receiv-
  644.               ing  side  that  aren't  on  the sending side. This
  645.               option can be dangerous if used incorrectly!
  646.  
  647.               It is a very good idea to run first using  the  dry
  648.               run  option (-n) to see what files would be deleted
  649.               to make sure important files aren't listed.
  650.  
  651.               rsync 1.6.4 changed the  behavior  of  --delete  to
  652.               make  it  less  dangerous.   rsync  now  only scans
  653.               directories on the receiving side that are  explic-
  654.               itly transferred from the sending side.  Only files
  655.  
  656.  
  657.  
  658.                            24 Nov 1998                         10
  659.  
  660.  
  661.  
  662.  
  663.  
  664. rsync(1)                                                 rsync(1)
  665.  
  666.  
  667.               in these directories are deleted.
  668.  
  669.               Still, it is probably easy to get burnt  with  this
  670.               option.   The  moral  of the story is to use the -n
  671.               option until  you  get  used  to  the  behavior  of
  672.               --delete.
  673.  
  674.               If  the sending side detects any IO errors then the
  675.               deletion of any files at the  destination  will  be
  676.               automatically  disabled.  This is to prevent tempo-
  677.               rary filesystem failures (such as  NFS  errors)  on
  678.               the  sending  side  causing  a  massive deletion of
  679.               files on the destination.
  680.  
  681.  
  682.        ----ffoorrccee
  683.               This options tells rsync to delete directories even
  684.               if  they  are  not empty.  This applies to both the
  685.               --delete option and to cases where rsync  tries  to
  686.               copy  a  normal file but the destination contains a
  687.               directory of the same  name.  Normally  rsync  will
  688.               refuse to do a recursive directory deletion in such
  689.               cases, by using --force the recursive deletion will
  690.               be done.
  691.  
  692.               Use this option with caution!
  693.  
  694.  
  695.        --BB ,, ----bblloocckk__ssiizzee BBLLOOCCKKSSIIZZEE
  696.               This  controls  the  block  size  used in the rsync
  697.               algorithm. See the technical report for details.
  698.  
  699.  
  700.        --ee,, ----rrsshh CCOOMMMMAANNDD
  701.               This option allows you  to  choose  an  alternative
  702.               remote  shell  program  to  use  for  communication
  703.               between the local and remote copies  of  rsync.  By
  704.               default  rsync  will  use  rsh, but you may like to
  705.               instead use ssh because of its high security.
  706.  
  707.               You can also choose the remote shell program  using
  708.               the RSYNC_RSH environment variable.
  709.  
  710.  
  711.        ----rrssyynncc--ppaatthh PPAATTHH
  712.               Use  this  to specify the path to the copy of rsync
  713.               on the remote machine. Useful when its not in  your
  714.               path.
  715.  
  716.  
  717.        ----eexxcclluuddee ppaatttteerrnn
  718.               This  option allows you to selectively exclude cer-
  719.               tain files from the list  of  files  to  be  trans-
  720.               ferred.  This  is most useful in combination with a
  721.  
  722.  
  723.  
  724.                            24 Nov 1998                         11
  725.  
  726.  
  727.  
  728.  
  729.  
  730. rsync(1)                                                 rsync(1)
  731.  
  732.  
  733.               recursive transfer.
  734.  
  735.               You may use as many --exclude options on  the  com-
  736.               mand line as you like to build up the list of files
  737.               to exclude.
  738.  
  739.               See the section of exclude patterns for information
  740.               on the syntax of this option.
  741.  
  742.  
  743.        ----eexxcclluuddee--ffrroomm FFIILLEE
  744.               This option is similar to the --exclude option, but
  745.               instead it adds all filenames listed  in  the  file
  746.               FILE to the exclude list.
  747.  
  748.  
  749.        ----iinncclluuddee ppaatttteerrnn
  750.               This  option  tells rsync to not exclude the speci-
  751.               fied pattern of filenames. This  is  useful  as  it
  752.               allows    you    to    build   up   quite   complex
  753.               exclude/include rules.
  754.  
  755.               See the section of exclude patterns for information
  756.               on the syntax of this option.
  757.  
  758.  
  759.        ----iinncclluuddee--ffrroomm FFIILLEE
  760.               This  specifies  a  list of include patterns from a
  761.               file.
  762.  
  763.  
  764.        --CC,, ----ccvvss--eexxcclluuddee
  765.               This is a useful shorthand for  excluding  a  broad
  766.               range  of files that you often don't want to trans-
  767.               fer between systems. It  uses  the  same  algorithm
  768.               that  CVS  uses  to  determine  if a file should be
  769.               ignored.
  770.  
  771.               The exclude list is initialized to:
  772.  
  773.               RCS SCCS CVS  CVS.adm  RCSLOG  cvslog.*  tags  TAGS
  774.               .make.state  .nse_depinfo  *~ #* .#* ,* *.old *.bak
  775.               *.BAK *.orig *.rej .del-* *.a *.o  *.obj  *.so  *.Z
  776.               *.elc *.ln core
  777.  
  778.               then  files  listed in a $HOME/.cvsignore are added
  779.               to the list and any files listed in  the  CVSIGNORE
  780.               environment variable (space delimited).
  781.  
  782.               Finally  in  each directory any files listed in the
  783.               .cvsignore file in that directory are added to  the
  784.               list.
  785.  
  786.  
  787.  
  788.  
  789.  
  790.                            24 Nov 1998                         12
  791.  
  792.  
  793.  
  794.  
  795.  
  796. rsync(1)                                                 rsync(1)
  797.  
  798.  
  799.        ----ssuuffffiixx SSUUFFFFIIXX
  800.               This  option  allows  you  to  override the default
  801.               backup suffix used with the -b option. The  default
  802.               is a ~.
  803.  
  804.  
  805.        ----ccssuumm--lleennggtthh LLEENNGGTTHH
  806.               By  default the primary checksum used in rsync is a
  807.               very strong 16 byte MD4 checksum. In most cases you
  808.               will find that a truncated version of this checksum
  809.               is quite efficient, and this will decrease the size
  810.               of  the  checksum  data  sent over the link, making
  811.               things faster.
  812.  
  813.               You can choose the number of bytes in the truncated
  814.               checksum  using the --csum-length option. Any value
  815.               less than or equal to 16 is valid.
  816.  
  817.               Note that if you use this option then you  run  the
  818.               risk  of  ending  up with an incorrect target file.
  819.               The risk with a value of 16 is microscopic and  can
  820.               be  safely  ignored (the universe will probably end
  821.               before it fails) but with smaller values  the  risk
  822.               is higher.
  823.  
  824.               Current  versions of rsync actually use an adaptive
  825.               algorithm for the checksum length by default, using
  826.               a  16 byte file checksum to determine if a 2nd pass
  827.               is required with a longer block checksum. Only  use
  828.               this  option  if  you have read the source code and
  829.               know what you are doing.
  830.  
  831.  
  832.        --TT,, ----tteemmpp--ddiirr DDIIRR
  833.               This option instructs rsync to use DIR as a scratch
  834.               directory  when  creating  temporary  copies of the
  835.               files  transferred  on  the  receiving  side.   The
  836.               default  behavior  is to create the temporary files
  837.               in the receiving directory.
  838.  
  839.  
  840.        ----ccoommppaarree--ddeesstt DDIIRR
  841.               This option instructs rsync to use DIR as an  addi-
  842.               tional   directory  to  compare  destination  files
  843.               against when doing transfers.  This is  useful  for
  844.               doing  transfers to a new destination while leaving
  845.               existing files intact,  and  then  doing  a  flash-
  846.               cutover  when  all  files  have  been  successfully
  847.               transfered  (for  example  by  moving   directories
  848.               around  and  removing  the  old directory, although
  849.               this requires also doing the transfer  with  -I  to
  850.               avoid  skipping  files that haven't changed).  This
  851.               option  increases  the  usefulness   of   --partial
  852.               because  partially transferred files will remain in
  853.  
  854.  
  855.  
  856.                            24 Nov 1998                         13
  857.  
  858.  
  859.  
  860.  
  861.  
  862. rsync(1)                                                 rsync(1)
  863.  
  864.  
  865.               the new temporary destination  until  they  have  a
  866.               chance to be completed.  If DIR is a relative path,
  867.               it is relative to the destination directory.
  868.  
  869.  
  870.        --zz,, ----ccoommpprreessss
  871.               With this option, rsync compresses  any  data  from
  872.               the  source  file(s) which it sends to the destina-
  873.               tion machine.  This option is useful on slow links.
  874.               The compression method used is the same method that
  875.               gzip uses.
  876.  
  877.               Note this this  option  typically  achieves  better
  878.               compression  ratios that can be achieved by using a
  879.               compressing remote shell, or a  compressing  trans-
  880.               port,  as it takes advantage of the implicit infor-
  881.               mation sent for matching data blocks.
  882.  
  883.  
  884.        ----nnuummeerriicc--iiddss
  885.               With this option rsync will transfer numeric  group
  886.               and user ids rather than using user and group names
  887.               and mapping them at both ends.
  888.  
  889.               By default rsync will use the user name  and  group
  890.               name to determine what ownership to give files. The
  891.               special uid 0 and the special  group  0  and  never
  892.               mapped  via user/group names even if the --numeric-
  893.               ids option is not specified.
  894.  
  895.               If the source system is a daemon using  chroot,  or
  896.               if  a user or group name does not exist on the des-
  897.               tination system,  then  the  numeric  id  from  the
  898.               source system is used instead.
  899.  
  900.  
  901.        ----ttiimmeeoouutt==TTIIMMEEOOUUTT
  902.               This  option allows you to set a maximum IO timeout
  903.               in seconds. If no data is transferred for the spec-
  904.               ified  time then rsync will exit. The default is 0,
  905.               which means no timeout.
  906.  
  907.  
  908.        ----ddaaeemmoonn
  909.               This tells rsync that it is to run as a rsync  dae-
  910.               mon.  If standard input is a socket then rsync will
  911.               assume that it is being run via inetd, otherwise it
  912.               will  detach from the current terminal and become a
  913.               background daemon. The daemon will read the  config
  914.               file  (/etc/rsyncd.conf)  on each connect made by a
  915.               client and respond to requests accordingly. See the
  916.               rsyncd.conf(5) man page for more details.
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                            24 Nov 1998                         14
  923.  
  924.  
  925.  
  926.  
  927.  
  928. rsync(1)                                                 rsync(1)
  929.  
  930.  
  931.        ----ccoonnffiigg FFIILLEE
  932.               This  specifies  an  alternate config file than the
  933.               default /etc/rsyncd.conf.  This  is  only  relevant
  934.               when --daemon is specified.
  935.  
  936.  
  937.        ----ppoorrtt PPOORRTT
  938.               This  specifies an alternate TCP port number to use
  939.               rather than the default port 873.
  940.  
  941.  
  942.        ----lloogg--ffoorrmmaatt==FFOORRMMAATT
  943.               This allows you to specify exactly what  the  rsync
  944.               client  logs to stdout on a per file basis. The log
  945.               format is specified using the same  format  conven-
  946.               tions as the log format option in rsyncd.conf.
  947.  
  948.  
  949.        ----ssttaattss
  950.               This  tells rsync to print a verbose set of statis-
  951.               tics on the file transfer, allowing you to tell how
  952.               effective  the  rsync  algorithm  is for your data.
  953.               This option only works in conjunction with  the  -v
  954.               (verbose) option.
  955.  
  956.  
  957.        ----pprrooggrreessss
  958.               This  option tells rsync to print information show-
  959.               ing the progress of  the  transfer.  This  gives  a
  960.               bored user something to watch.
  961.  
  962.  
  963.  
  964. EEXXCCLLUUDDEE PPAATTTTEERRNNSS
  965.        The  exclude and include patterns specified to rsync allow
  966.        for flexible selection of what files to transfer and  what
  967.        files to skip.
  968.  
  969.        rsync  build  a ordered list of include/exclude options as
  970.        specified on the command line. When a filename is  encoun-
  971.        tered   rsync   then   checks   the   name   against  each
  972.        exclude/include pattern in turn. The first  matching  pat-
  973.        tern  is  acted  on. If it is an exclude pattern than that
  974.        file is skipped. If it is an  include  pattern  then  that
  975.        filename  is  not  skipped. If no matching include/exclude
  976.        pattern is found then the filename is not skipped.
  977.  
  978.        The patterns themselves can take several forms. The  rules
  979.        are:
  980.  
  981.  
  982.        o      if  the  pattern starts with a / then it is matched
  983.               against the start of the filename, otherwise it  is
  984.               matched  against the end of the filename. Thus /foo
  985.  
  986.  
  987.  
  988.                            24 Nov 1998                         15
  989.  
  990.  
  991.  
  992.  
  993.  
  994. rsync(1)                                                 rsync(1)
  995.  
  996.  
  997.               would match a file called foo at the  base  of  the
  998.               tree  whereas  foo  would match any file called foo
  999.               anywhere in the tree.
  1000.  
  1001.  
  1002.        o      if the pattern ends with a  /  then  it  will  only
  1003.               match a directory, not a file, link or device.
  1004.  
  1005.  
  1006.        o      if  the  pattern contains a wildcard character from
  1007.               the set *?[ then  regular  expression  matching  is
  1008.               applied  using  the  normal shell filename matching
  1009.               rules. Otherwise a simple string match is used.
  1010.  
  1011.  
  1012.        o      if the pattern contains a / (not counting a  trail-
  1013.               ing  /)  then  it is matched against the full file-
  1014.               name, including any leading directory. If the  pat-
  1015.               tern  doesn't  contain  a / then it is matched only
  1016.               against the final component of the filename.
  1017.  
  1018.  
  1019.        o      if the pattern starts with "+ " (a plus followed by
  1020.               a  space)  then  it  is always considered a include
  1021.               pattern, even if specified as part  of  an  exclude
  1022.               option. The "+ " part is discarded before matching.
  1023.  
  1024.  
  1025.        o      if the pattern starts with "- " (a  minus  followed
  1026.               by  a space) then it is always considered a exclude
  1027.               pattern, even if specified as part  of  an  include
  1028.               option. The "- " part is discarded before matching.
  1029.  
  1030.  
  1031.        o      if the pattern is a single exclamation mark !  then
  1032.               the  current  exclude  list  is reset, removing all
  1033.               previous exclude patterns.
  1034.  
  1035.        The +/- rules are most useful in exclude  lists,  allowing
  1036.        you  to  have  a  single  exclude  list that contains both
  1037.        include and exclude options.
  1038.  
  1039.        Here are some examples:
  1040.  
  1041.  
  1042.        o      --exclude "*.o" would exclude all filenames  match-
  1043.               ing *.o
  1044.  
  1045.        o      --exclude  "/foo"  would exclude a file in the base
  1046.               directory called foo
  1047.  
  1048.        o      --exclude "foo/" would exclude any directory called
  1049.               foo
  1050.  
  1051.  
  1052.  
  1053.  
  1054.                            24 Nov 1998                         16
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. rsync(1)                                                 rsync(1)
  1061.  
  1062.  
  1063.        o      --include  "*/" --include "*.c" --exclude "*" would
  1064.               include all directories and C source files.
  1065.  
  1066.        o      --include "foo/"  --include  "foo/bar.c"  --exclude
  1067.               "*"  would  include only foo/bar.c (the foo/ direc-
  1068.               tory must be explicitly included  or  it  would  be
  1069.               excluded by the "*")
  1070.  
  1071.  
  1072. DDIIAAGGNNOOSSTTIICCSS
  1073.        rsync  occasinally produces error messages that may seem a
  1074.        little cryptic. The one that seems to cause the most  con-
  1075.        fusion  is  "protocol  version  mismatch  -  is your shell
  1076.        clean?".
  1077.  
  1078.        This message is usually caused by your startup scripts  or
  1079.        remote  shell  facility  producing unwanted garbage on the
  1080.        stream that rsync is using for its transport. The  way  ot
  1081.        diagnose  this  problem  is  to run your remote shell like
  1082.        this:
  1083.  
  1084.  
  1085.  
  1086.  
  1087.           rsh remotehost /bin/true > out.dat
  1088.  
  1089.  
  1090.  
  1091.  
  1092.        then look at out.dat. If everything is  working  correctly
  1093.        then  out.dat  should  be  a zero length file. You you are
  1094.        getting the above error from rsync then you will  probably
  1095.        find  that out.dat contains some text or data. Look at the
  1096.        contents and try to work out what  is  producing  it.  The
  1097.        most  common  cause is incorrectly configued shell startup
  1098.        scripts (such as .cshrc or .profile) that  contain  output
  1099.        statements for non-interactive logins.
  1100.  
  1101.  
  1102. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
  1103.        CCVVSSIIGGNNOORREE
  1104.               The  CVSIGNORE environment variable supplements any
  1105.               ignore patterns in .cvsignore files. See the --cvs-
  1106.               exclude option for more details.
  1107.  
  1108.  
  1109.        RRSSYYNNCC__RRSSHH
  1110.               The  RSYNC_RSH  environment  variable allows you to
  1111.               override the default shell used  as  the  transport
  1112.               for  rsync.  This  can  be  used  instead of the -e
  1113.               option.
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                            24 Nov 1998                         17
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126. rsync(1)                                                 rsync(1)
  1127.  
  1128.  
  1129.        RRSSYYNNCC__PPAASSSSWWOORRDD
  1130.               Setting RSYNC_PASSWORD  to  the  required  password
  1131.               allows  you  to run authenticated rsync connections
  1132.               to a rsync daemon without user  intervention.  Note
  1133.               that  this  does  not  supply a password to a shell
  1134.               transport such as ssh.
  1135.  
  1136.  
  1137.        UUSSEERR or LLOOGGNNAAMMEE
  1138.               The USER or LOGNAME environment variables are  used
  1139.               to  determine  the default username sent to a rsync
  1140.               server.
  1141.  
  1142.  
  1143.        HHOOMMEE   The HOME environment variable is used to  find  the
  1144.               users default .cvsignore file.
  1145.  
  1146.  
  1147.  
  1148. FFIILLEESS
  1149.        /etc/rsyncd.conf
  1150.  
  1151.  
  1152. SSEEEE AALLSSOO
  1153.        rsyncd.conf(5)
  1154.  
  1155.  
  1156. DDIIAAGGNNOOSSTTIICCSS
  1157. BBUUGGSS
  1158.        times are transferred as unix time_t values
  1159.  
  1160.        file  permissions,  devices  etc are transferred as native
  1161.        numerical values
  1162.  
  1163.        see also the comments on the --delete option
  1164.  
  1165.        Please report bugs!  The  rsync  bug  tracking  system  is
  1166.        online at http://samba.anu.edu.au/rsync/
  1167.  
  1168.  
  1169. VVEERRSSIIOONN
  1170.        This man page is current for version 2.0 of rsync
  1171.  
  1172.  
  1173. CCRREEDDIITTSS
  1174.        rsync  is  distributed  under the GNU public license.  See
  1175.        the file COPYING for details.
  1176.  
  1177.        The     primary     ftp     site     for     rsync      is
  1178.        ftp://samba.anu.edu.au/pub/rsync.
  1179.  
  1180.        A WEB site is available at http://samba.anu.edu.au/rsync/
  1181.  
  1182.        We  would  be  delighted to hear from you if you like this
  1183.  
  1184.  
  1185.  
  1186.                            24 Nov 1998                         18
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192. rsync(1)                                                 rsync(1)
  1193.  
  1194.  
  1195.        program.
  1196.  
  1197.        This program uses the zlib compression library written  by
  1198.        Jean-loup Gailly and Mark Adler.
  1199.  
  1200.  
  1201. TTHHAANNKKSS
  1202.        Thanks  to  Richard  Brent,  Brendan  Mackay,  Bill Waite,
  1203.        Stephen Rothwell and David Bell  for  helpful  suggestions
  1204.        and testing of rsync. I've probably missed some people, my
  1205.        apologies if I have.
  1206.  
  1207.  
  1208. AAUUTTHHOORR
  1209.        rsync was written by Andrew Tridgell and  Paul  Mackerras.
  1210.        They may be contacted via email at tridge@samba.anu.edu.au
  1211.        and Paul.Mackerras@cs.anu.edu.au
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.                            24 Nov 1998                         19
  1253.  
  1254.  
  1255.