Improved the "use chroot" discussion on ID mapping.

[rsync/rsync.git] / rsyncd.conf.yo

diff --git a/rsyncd.conf.yo b/rsyncd.conf.yo
index a865864..aac28d7 100644 (file)
--- a/rsyncd.conf.yo
+++ b/rsyncd.conf.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
-manpage(rsyncd.conf)(5)(26 Jan 2003)()()
+manpage(rsyncd.conf)(5)(1 Jan 2004)()()
 manpagename(rsyncd.conf)(configuration file for rsync server)
 manpagesynopsis()
 
@@ -135,12 +135,20 @@ to the "path" before starting the file transfer with the client.  This has
 the advantage of extra protection against possible implementation security
 holes, but it has the disadvantages of requiring super-user privileges, 
 of not being able to follow symbolic links outside of the new root path
-when reading, and of implying the --numeric-ids option because /etc/passwd
-becomes inaccessible.  When "use chroot" is false, for security reasons
+when reading, and of complicating the preservation of usernames and groups
+(see below).  When "use chroot" is false, for security reasons,
 symlinks may only be relative paths pointing to other files within the root
 path, and leading slashes are removed from absolute paths.  The default for
 "use chroot" is true.
 
+In order to preserve usernames and groupnames, rsync needs to be able to
+lookup the IDs using getpuid() and getpgid().  This means that the chroot
+area will need to have copies of your user/group information (edited, if
+desired) inside the chroot tree for rsync to use (the traditional files
+are /etc/passwd and /etc/group).  If the needed files are not available,
+rsync will only be able to copy the IDs, just as if the --numeric-ids
+option had been specified.
+
 dit(bf(max connections)) The "max connections" option allows you to
 specify the maximum number of simultaneous connections you will allow.
 Any clients connecting when the maximum has been reached will receive a
@@ -399,6 +407,32 @@ encryption.
 Future versions of rsync may support SSL for better authentication and
 encryption, but that is still being investigated.
 
+manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+
+If rsync is run with both the --daemon and --rsh (-e) options, it will
+spawn an rsync daemon using a remote shell connection.  Several
+configuration options will not be available unless the remote user is
+root (e.g. chroot, setuid/setgid, etc.).  There is no need to configure
+inetd or the services map to include the rsync server port if you run an
+rsync server only via a remote shell program.
+
+ADVANCED: To run an rsync server out of a single-use ssh key, use the
+"command=em(COMMAND)" syntax in the remote user's authorized_keys entry,
+where command would be
+
+quote(rsync --server --daemon .)
+
+NOTE: rsync's argument parsing expects the trailing ".", so make sure
+that it's there.  If you want to use a rsyncd.conf(5)-style
+configuration file other than the default, you can added a
+--config option to the em(command):
+
+quote(rsync --server --daemon --config=em(file) .)
+
+Note that the "--server" here is the internal option that rsync uses to
+run the remote version of rsync that it communicates with, and thus you
+should not be using the --server option under normal circumstances.
+
 manpagesection(EXAMPLES)
 
 A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
@@ -468,7 +502,7 @@ Please report bugs! The rsync bug tracking system is online at
 url(http://rsync.samba.org/)(http://rsync.samba.org/)
 
 manpagesection(VERSION)
-This man page is current for version 2.0 of rsync
+This man page is current for version 2.x of rsync.
 
 manpagesection(CREDITS)