A few more doc tweaks & comment tweaks.

Author: WayneD

NEWS.md

@@ -18,32 +18,34 @@
 ### ENHANCEMENTS:
 
 - Added negotiated daemon-auth support that allows a stronger checksum digest
-  to be used.  Added SHA512, SHA256, and SHA1 digests to MD5 & MD4.  These new
-  digests are at the highest priority in the new daemon-auth negotiation list.
+  to be used to validate a user's login to the daemon.  Added SHA512, SHA256,
+  and SHA1 digests to MD5 & MD4.  These new digests are at the highest priority
+  in the new daemon-auth negotiation list.
 
-- Added support for SHA1, SHA256, and SHA512 digests in file checksums.  While
-  this tends to be overkill, it is available if someone really needs it.  These
-  overly-long checksums are at the lowest priority in the normal checksum
-  negotiation list.
+- Added support for the SHA1 digest in file checksums.  While this tends to be
+  overkill, it is available if someone really needs it.  This overly-long
+  checksum is at the lowest priority in the normal checksum negotiation list.
+  See `--checksum-choice` (`--cc`) and the `RSYNC_CHECKSUM_LIST` environment
+  var for how to customize this.
 
-- Improved the xattr hash table to use a 64-bit key (which should ensure fewer
-  collisions).
+- Improved the xattr hash table to use a 64-bit key without slowing down the
+  key's computation.  This should make extra sure that a collision doesn't
+  happen.
 
 - If the `--version` option is repeated (e.g. `-VV`) then the information is
-  output in a (still human-readable) JSON format (client side only).
+  output in a (still fairly readable) JSON format.  Client side only.
 
 - The script `support/json-rsync-version` is available to get the JSON style
   version output from any rsync.  The script accepts either text on stdin
   **or** an arg that specifies an rsync executable to run with a doubled
   `--version` option.  If the text we get isn't already in JSON format, it is
-  converted. Newer rsync versions will provide more complete info than older
-  versions.
+  converted. Newer rsync versions will provide more complete json info than
+  older rsync versions.
 
 - The [`use chroot`](rsyncd.conf.5#use_chroot) daemon parameter now defaults to
-  "unset" so that rsync can use chroot when it works and decide to proceed with
-  a sanitized copy when chroot is not supported (e.g., for a non-root daemon).
-  Explicitly setting it to true or false (on or off) behaves the same way as
-  before.
+  "unset" so that rsync can use chroot when it works and a sanitized copy when
+  chroot is not supported (e.g., for a non-root daemon).  Explicitly setting
+  the parameter to true or false (on or off) behaves the same way as before.
 
 - The `--fuzzy` option was optimized a bit to try to cut down on the amount of
   computations when considering a big pool of files. The simple heuristic from
@@ -54,10 +56,10 @@
 - The checksum code now uses openssl's EVP methods, which gets rid of various
   deprecation warnings and makes it easy to support more digest methods.  On
   newer systems, the MD4 digest is marked as legacy in the openssl code, which
-  makes openssl refuse to support it via EVP.  You can just ignore this and
-  allow the included MD4 code to be used for older rsync connections (when
-  talking to an rsync prior to 3.0.0) or you can configure rsync to tell
-  openssl to enable legacy algorithms (see below).
+  makes openssl refuse to support it via EVP.  You can choose to ignore this
+  and allow the included MD4 code to be used for older rsync connections (when
+  talking to an rsync prior to 3.0.0) or you can choose to configure rsync to
+  tell openssl to enable legacy algorithms (see below).
 
 - A simple openssl config file is supplied that can be installed for rsync to
   use.  If you install packaging/openssl-rsync.cnf to a public spot (such as
@@ -67,15 +69,18 @@
   is not already set).  This will enable openssl's MD4 code for rsync to use.
 
 - The packager may wish to include an explicit "use chroot = true" in the top
-  section of the /etc/rsyncd.conf file if the daemon is being installed to run
-  as the root user (though rsync should behave the same even with the value
-  unset, a little extra paranoia doesn't hurt).
+  section of their supplied /etc/rsyncd.conf file if the daemon is being
+  installed to run as the root user (though rsync should behave the same even
+  with the value unset, a little extra paranoia doesn't hurt).
 
 - I've noticed that some packagers haven't installed support/nameconvert for
   users to use in their chrooted rsync configs.  Even if it is not installed
   as an executable script (to avoid a python3 dependency) it would be good to
   install it with the other rsync-related support scripts.
 
+- It would be good to add support/json-rsync-version to the list of installed
+  support scripts.
+
 ------------------------------------------------------------------------------
 
 # NEWS for rsync 3.2.6 (9 Sep 2022)

checksum.c

@@ -552,6 +552,9 @@ int cur_sum_len;
 static const EVP_MD *cur_sum_evp_md;
 #endif
 
+/* Initialize a hash digest accumulator.  Data is supplied via
+ * sum_update() and the resulting binary digest is retrieved via
+ * sum_end().  This only supports one active sum at a time. */
 int sum_init(struct name_num_item *nni, int seed)
 {
 	char s[4];
@@ -615,14 +618,7 @@ int sum_init(struct name_num_item *nni, int seed)
 	return cur_sum_len;
 }
 
-/**
- * Feed data into an MD4 accumulator, md.  The results may be
- * retrieved using sum_end().  md is used for different purposes at
- * different points during execution.
- *
- * @todo Perhaps get rid of md and just pass in the address each time.
- * Very slightly clearer and slower.
- **/
+/* Feed data into a hash digest accumulator. */
 void sum_update(const char *p, int32 len)
 {
 #ifdef USE_OPENSSL

clientserver.c

@@ -831,7 +831,7 @@ static int rsync_module(int f_in, int f_out, int i, const char *addr, const char
 			use_chroot = 1; /* The module is expecting a chroot inner & outer path. */
 		else if (chroot("/") < 0) {
 			rprintf(FLOG, "chroot test failed: %s. "
-				      "Switching 'use chroot' from unset to no.\n",
+				      "Switching 'use chroot' from unset to false.\n",
 				      strerror(errno));
 			use_chroot = 0;
 		} else {

csprotocol.txt

@@ -53,8 +53,8 @@ base64 form of the digest hash of the challenge+password string. The
 chosen digest method is the most preferred client method that is also in
 the server's list.  If no digest list was explicitly provided, the side
 expecting a list assumes the other side provided either the single name
-"md5" (for a negotiated protocol 30), or the single name "md4" (for an
-older protocol).
+"md5" (for a negotiated protocol 30 or 31), or the single name "md4"
+(for an older protocol).
 
 At this point the server applies all remaining constraints before
 handing control to the client, including switching uid/gid, setting up
@@ -91,10 +91,12 @@ stay tuned (or write it yourself!).
 ------------
 Protocol version changes
 
-31	(2022-09-10, 3.2.7dev)
+31	(2013-09-28, 3.1.0)
 
-	The use of a suffixed list of digest names was added as an
-	optional suffix to the greeting line.
+	Initial release of protocol 31 had no changes.  Rsync 3.2.7
+	introduced the suffixed list of digest names on the greeting
+	line.  The presence of the list is allowed even if the greeting
+	indicates an older protocol version number.
 
 30	(2007-10-04, 3.0.0pre1)
 

rsync.1.md

@@ -581,8 +581,8 @@ expand it.
 0.  `--version`, `-V`
 
     Print the rsync version plus other info and exit.  When repeated, the
-    information is output is a JSON format that is still hum-readable (client
-    side only).
+    information is output is a JSON format that is still fairly readable
+    (client side only).
 
     The output includes a list of compiled-in capabilities, a list of
     optimizations, the default list of checksum algorithms, the default list of
@@ -1731,8 +1731,6 @@ expand it.
     - `md5`
     - `md4`
     - `sha1`
-    - `sha256`
-    - `sha512`
     - `none`
 
     Run `rsync --version` to see the default checksum list compiled into your

rsyncd.conf.5.md

@@ -203,35 +203,39 @@ the values of parameters.  See the GLOBAL PARAMETERS section for more details.
     divider in it -- this causes an unset value to be treated as true for that
     module.
 
-    Prior to rsync 3.2.7, the default value was "true".  The new default makes
-    it easier to setup an rsync daemon as a non-root user or to run a daemon on
-    a system where chroot fails.  Explicitly setting the value to true in the
-    rsyncd.conf file will always require the chroot to succeed.
+    Prior to rsync 3.2.7, the default value was "true".  The new "unset"
+    default makes it easier to setup an rsync daemon as a non-root user or to
+    run a daemon on a system where chroot fails.  Explicitly setting the value
+    to "true" in rsyncd.conf will always require the chroot to succeed.
 
     It is also possible to specify a dot-dir in the module's "[path](#)" to
     indicate that you want to chdir to the earlier part of the path and then
-    serve files from inside the latter part of the path (with default
-    sanitizing and symlink munging).  This can be useful if you need some
-    library dirs inside the chroot (typically for uid & gid lookups) but don't
-    want to put the lib dir into the top of the served path (even though they
-    can be hidden with an [`exclude`](#) directive).  However, a better choice
-    for a modern rsync setup is to use a [`name converter`](#)" and try to
-    avoid inner lib dirs altogether.  See also the [`daemon chroot`](#)
-    parameter, which causes rsync to chroot into its own chroot area before
-    doing any path-related chrooting.
+    serve files from inside the latter part of the path (with sanitizing and
+    default symlink munging).  This can be useful if you need some library dirs
+    inside the chroot (typically for uid & gid lookups) but don't want to put
+    the lib dir into the top of the served path (even though they can be hidden
+    with an [`exclude`](#) directive).  However, a better choice for a modern
+    rsync setup is to use a [`name converter`](#)" and try to avoid inner lib
+    dirs altogether.  See also the [`daemon chroot`](#) parameter, which causes
+    rsync to chroot into its own chroot area before doing any path-related
+    chrooting.
 
     If the daemon is serving the "/" dir (either directly or due to being
-    chrooted to the module's path), rsync does not do any extra path sanitizing
-    or (default) munging.  When it has to limit access to a particular subdir
-    (either due to chroot being disabled or having an inside-chroot path set),
-    rsync will munge symlinks (by default) and sanitize paths.  Those that
-    dislike munged symlinks (and really, really trust their users to not break
-    out of the subdir) can disable the symlink munging via the "[munge
-    symlinks](#)" parameter. Sanitizing paths trims ".." path elements from
-    args that rsync believes would escape the module hierarchy, and also
-    substitutes leading slashes in absolute paths with the module's path (so
-    that options such as `--backup-dir` & `--compare-dest` interpret an
-    absolute path as rooted in the module's "[path](#)" dir).
+    chrooted to the module's path), rsync does not do any path sanitizing or
+    (default) munging.
+
+    When it has to limit access to a particular subdir (either due to chroot
+    being disabled or having an inside-chroot path set), rsync will munge
+    symlinks (by default) and sanitize paths.  Those that dislike munged
+    symlinks (and really, really trust their users to not break out of the
+    subdir) can disable the symlink munging via the "[munge symlinks](#)"
+    parameter.
+
+    When rsync is sanitizing paths, it trims ".." path elements from args that
+    it believes would escape the module hierarchy. It also substitutes leading
+    slashes in absolute paths with the module's path (so that options such as
+    `--backup-dir` & `--compare-dest` interpret an absolute path as rooted in
+    the module's "[path](#)" dir).
 
     When a chroot is in effect *and* the "[name converter](#)" parameter is
     *not* set, the "[numeric ids](#)" parameter will default to being enabled