Bug 143

Summary:	Add reference to "rsync" in FAQ and documentation.
Product:	Portable OpenSSH	Reporter:	David A. Wheeler <dwheeler>
Component:	Documentation	Assignee:	OpenSSH Bugzilla mailing list <openssh-bugs>
Status:	CLOSED WONTFIX
Severity:	normal	Keywords:	help-wanted
Priority:	P2
Version:	-current
Hardware:	All
OS:	All

Description David A. Wheeler 2002-03-08 06:24:18 AEDT

There have been a number of people who want to copy only changed
files using the OpenSSH toolkit.  Please add the following text to the FAQ
and the scp man page, so that people will know how to do it:


How can I copy just the changed files?

One way to copy only the changed files using OpenSSH is by using
another package named "rsync".  rsync can transfer just the differences
between two sets of files, and can use "ssh" to implement it.
For example, to copy the changed files from the local directory
/home/joe/stuff (and its descendants) to the user joeuser at
computer joe.com, directory /home/joeuser/stuff, do this:

 rsync -a --rsh="ssh" /home/joe/stuff joeuser@joe.com:/home/joeuser/stuff

The "-a" option tries to make everything the same on the remote system
(including symbolic links, permissions, and timestamps), and the "--rsh"
option indicates that ssh should be used as the (secure) transport.

Especially useful rsync options include -C (which skips copying certain
useless files), -z (which compresses before sending over a network),
-v (verbose status information), and --progress (show status of the
file transfer).

Note that this only works if the remote system has an ssh server, permits
the user to log in using ssh, and is at least somewhat Unix-like.

Comment 1 Damien Miller 2002-04-17 12:46:55 AEST

I don't think the scp manpage is an appropriate place for this (maybe in the
'see also' section) and the FAQ is more for troubleshooting.

We don't yet have a good HOWTO-style document for OpenSSH. If we did, we could
put the text there

Comment 2 David A. Wheeler 2002-04-18 00:01:45 AEST

The FAQ currently emphasizes troubleshooting, but that's not necessary.
A FAQ is for "frequently asked questions", and since "how do I synchronize"
can be viewed as a frequent question, I think it's reasonable to add this
information to the FAQ.  In fact, PLEASE add the text I proposed
to the FAQ, since it would help many people immediately.

As far as the man page goes, changing the scp man page
so that the "SEE ALSO" section mentioned rsync would be an improvement.
But using rsync's "--rsh" flag really involves a combination
of both ssh and rsync, and some mention in the scp man page
on how to use them together would make the combination easier to use.
Besides modifying scp's "SEE ALSO" man page section, could you
at leat add a sentence mentioning this important use?
Many people only look at the man pages,
so it's important to give them a hint there.  Here's my proposal;
just add this text to the end of the scp man page "DESCRIPTION":


If you want to only copy changed files using ssh's security features,
use rsync(1) with the option --rsh="ssh", e.g.,
rsync -a --rsh="ssh" /home/joe/stuff joeuser@joe.com:/home/joeuser/stuff


It's short, it's simple, and it shows people how to do it.
If you don't like the example, drop everything after the "e.g.", but at least
tell people about rsync, what it does, and its --rsh option.
Just a "see also" to rsync won't tell people WHY they should also see that
program.

Thanks.  I'm just trying to make sure that users can use this great tool
(OpenSSH) using only the documentation they get... :-).

Comment 3 Damien Miller 2003-01-07 17:28:04 AEDT

wontfix

Comment 4 Damien Miller 2004-04-14 12:24:18 AEST

Mass change of RESOLVED bugs to CLOSED