mirror/rsync
1
0
Fork 0
mirror of https://github.com/RsyncProject/rsync.git synced 2026-02-25 19:06:03 -05:00
Code Issues Packages Projects Releases Wiki Activity

More man page and NEWS improvements.

Browse Source 
- Add link targets for all option choices, not just the first one.
- Tweak cross-link arg format.
- Add more links, including some in the latest NEWS.
- Split out a few numbered lists.
This commit is contained in:
Wayne Davison
2022-01-16 08:56:51 -08:00
parent e2a011d9d0
commit d07272d631
6 changed files with 332 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
NEWS.md
View File

@@ -6,20 +6,21 @@
### BEHAVIOR CHANGES:
- A new form of arg protection was added that works similarly to the older
`--protect-args` (`-s`) option but in a way that avoids breaking things like
rrsync (the restricted rsync script): rsync now uses backslash escaping for
sending "shell-active" characters to the remote shell. This includes spaces,
so fetching a remote file via a simple quoted filename value now works by
default without any extra quoting:
[`--protect-args`](rsync.1#opt) (`-s`) option but in a way that avoids
breaking things like rrsync (the restricted rsync script): rsync now uses
backslash escaping for sending "shell-active" characters to the remote
shell. This includes spaces, so fetching a remote file via a simple quoted
filename value now works by default without any extra quoting:
```shell
rsync -aiv host:'a simple file.pdf' .
```
Wildcards are not escaped in filename args, but they are escaped in options
like the `--suffix` and `--usermap` values. If your rsync script depends on
the old arg-splitting behavior, either run it with the `--old-args` option
or `export RSYNC_OLD_ARGS=1` in the script's environment.
like the [`--suffix`](rsync.1#opt) and [`--usermap`](rsync.1#opt) values.
If your rsync script depends on the old arg-splitting behavior, either run
it with the [`--old-args`](rsync.1#opt) option or `export RSYNC_OLD_ARGS=1`
in the script's environment.
- A long-standing bug was preventing rsync from figuring out the current
locale's decimal point character, which made rsync always output numbers
@@ -45,62 +46,66 @@
### BUG FIXES:
- Fixed a bug with `--inplace` + `--sparse` (and a lack of `--whole-file`)
where the destination file could get reconstructed with bogus data. Since
the bug can also be avoided by using (the seemingly redundant) `--no-W` on
the receiving side, the latest rsync will now send `--no-W` to a remote
receiver when this option combination occurs. If your client rsync is not
new enough to do this for you (or if you're just paranoid), you can manually
specify `--no-W -M--no-W` (when not using `--whole-file`) to make sure the
- Fixed a bug with [`--inplace`](rsync.1#opt) + [`--sparse`](rsync.1#opt) (and
a lack of [`--whole-file`](rsync.1#opt)) where the destination file could
get reconstructed with bogus data. Since the bug can also be avoided by
using (the seemingly redundant) [`--no-W`](rsync.1#opt) on the receiving
side, the latest rsync will now send `--no-W` to a remote receiver when this
option combination occurs. If your client rsync is not new enough to do
this for you (or if you're just paranoid), you can manually specify `--no-W
-M--no-W` (when not using [`--whole-file`](rsync.1#opt)) to make sure the
bug is avoided.
- Fixed a bug with `--mkpath` if a single-file copy specifies an existing
destination dir with a non-existing destination filename.
- Fixed a bug with [`--mkpath`](rsync.1#opt) if a single-file copy specifies
an existing destination dir with a non-existing destination filename.
- Fixed `--update -vv` to output "is uptodate" instead of "is newer" messages
for files that are being skipped due to an identical modify time. (This
was a new output quirk in 3.2.3.)
for files that are being skipped due to an identical modify time. (This was
a new output quirk in 3.2.3.)
- When doing an append transfer, the sending side's file must not get shorter
or it is skipped. Fixes a crash that could occur when the size changes to 0
in the middle of the send negotiations.
- When dealing with special files (see `--specials`) in an alt-dest hierarchy,
rsync now checks the non-permission mode bits to ensure that the 2 special
files are really the same before hard-linking them together.
- When dealing with special files (see [`--specials`](rsync.1#opt)) in an
alt-dest hierarchy, rsync now checks the non-permission mode bits to ensure
that the 2 special files are really the same before hard-linking them
together.
- Fixed a bug where `--delay-updates` with stale partial data could cause a
file to fail to update.
- Fixed a bug where [`--delay-updates`](rsync.1#opt) with stale partial data
could cause a file to fail to update.
- Fixed a few places that would output an INFO message with `--info=NAME` that
should only have been output given `--verbose` or `--itemize-changes`.
- Fixed a few places that would output an INFO message with
[`--info=NAME`](rsync.1#opt) that should only have been output given
[`--verbose`](rsync.1#opt) or [`--itemize-changes`](rsync.1#opt).
- Avoid a weird failure if you run a local copy with a (useless) `--rsh`
option that contains a `V` in the command.
- Avoid a weird failure if you run a local copy with a (useless)
[`--rsh`](rsync.1#opt) option that contains a `V` in the command.
- Fixed a long-standing compression bug where the compression level of the
first file transferred affected the level for all future files. Also, the
per-file compression skipping has apparently never worked, so it is now
documented as being ineffective.
- Improved how the `--stop-at`, `--stop-after`, and `--time-limit` options
check to see if the allowed time is over, which should make rsync exit more
consistently.
- Improved how the [`--stop-at`](rsync.1#opt), [`--stop-after`](rsync.1#opt),
and (the deprecated) [`--time-limit`](rsync.1#opt) options check to see if
the allowed time is over, which should make rsync exit more consistently.
- Tweak --progress to display "??:??:??" when the time-remaining value is
so large as to be meaningless.
- Tweak --progress to display "`??:??:??`" when the time-remaining value is so
large as to be meaningless.
### ENHANCEMENTS:
- Use openssl's `-verify_hostname` option in the rsync-ssl script.
- Added extra info to the "FILENAME exists" output of `--ignore-existing` when
`--info=skip2` is used. The skip message becomes "FILENAME exists (INFO)"
where the INFO is one of "type change", "sum change" (requires `-c`), "file
change" (based on the quick check), "attr change", or "uptodate". Prior
versions only supported `--info=skip1`.
- Added extra info to the "FILENAME exists" output of
[`--ignore-existing`](rsync.1#opt) when [`--info=skip2`](rsync.1#opt) is
used. The skip message becomes "FILENAME exists (INFO)" where the INFO is
one of "type change", "sum change" (requires [`--checksum`](rsync.1#opt)),
"file change" (based on the quick check), "attr change", or "uptodate".
Prior versions only supported `--info=skip1`.
- Added the `--fsync` option (promoted from the patches repo).
- Added the [`--fsync`](rsync.1#opt) option (promoted from the patches repo).
- Reduced memory usage for an incremental transfer that has a bunch of small
directories.
@@ -108,37 +113,42 @@
- The rsync daemon can now handle a client address with an implied "%scope"
suffix.
- Added support for `--atimes` on macOS and fixed a bug where it wouldn't work
without `--times`.
- Added support for [`--atimes`](rsync.1#opt) on macOS and fixed a bug where
it wouldn't work without [`--times`](rsync.1#opt).
- Rsync can now update the xattrs on a read-only file when your user can
temporarily add user-write permission to the file. (It always worked for a
root transfer.)
- Rsync can now work around an `--inplace` update of a file that is being
refused due to the Linux fs.protected_regular sysctl setting.
- Rsync can now work around an [`--inplace`](rsync.1#opt) update of a file
that is being refused due to the Linux fs.protected_regular sysctl setting.
- When `--chown`, `--usermap`, or `--groupmap` is specified, rsync now makes
sure that the appropriate `--owner` and/or `--group` option is enabled.
- When [`--chown`](rsync.1#opt), [`--usermap`](rsync.1#opt), or
[`--groupmap`](rsync.1#opt), is specified, rsync now makes sure that the
appropriate [`--owner`](rsync.1#opt) and/or [`--group`](rsync.1#opt) options
are enabled.
- Added the `--info=NONREG` setting to control if rsync should warn about
non-regular files in the transfer. This is enabled by default (keeping the
behavior the same as before), so specifying `--info=nonreg0` can be used to
turn the warnings off.
- Added the [`--info=NONREG`](rsync.1#opt) setting to control if rsync should
warn about non-regular files in the transfer. This is enabled by default
(keeping the behavior the same as before), so specifying `--info=nonreg0`
can be used to turn the warnings off.
- More ASM optimizations from Shark64.
- Transformed rrsync into a python script with improvements:
- Security has been beefed up.
- The known rsync options were updated to include recent additions.
- Make rrsync reject `-L`, `-K`, & `-k` by default to make it harder to
- Make rrsync reject [`--copy-links`](rsync.1#opt) (`-L`),
[`--copy-dirlinks`](rsync.1#opt) (`-k`), &
[`--keep-dirlinks`](rsync.1#opt) (`-K`) by default to make it harder to
exploit any out-of-subdir symlinks.
- A new rrsync option of `-munge` tells rrsync to always enable rsync's
`--munge-links` option on the server side.
- A new rrsync option of `-no-lock` disables a new single-use locking idiom
that is the default when `-ro` is not used (useful with `-munge`).
- A new rrsync option of `-no-del` disables all `--remove*` and `--delete*`
options on the server side.
- A new rrsync option of [`-munge`](rrsync.1#opt) tells rrsync to always
enable rsync's [`--munge-links`](rsync.1#opt) option on the server side.
- A new rrsync option of [`-no-lock`](rrsync.1#opt) disables a new
single-use locking idiom that is the default when [`-ro`](rrsync.1#opt) is
not used (useful with [`-munge`](rrsync.1#opt)).
- A new rrsync option of [`-no-del`](rrsync.1#opt) disables all `--remove*`
and `--delete*` rsync options on the server side.
- The log format has been tweaked slightly to add seconds to the timestamp
and to output the command executed as a tuple (making the args clearer).
- An rrsync.1 man page was added (in the support dir with rrsync).
@@ -226,65 +236,70 @@
- Fixed a bug in the xattr code that was not leaving room for the "rsync."
prefix in some instances where it needed to be added.
- Restored the ability to use `--bwlimit=0` to specify no bandwidth limit. (It
was accidentally broken in 3.2.2.)
- Restored the ability to use [`--bwlimit=0`](rsync.1#opt) to specify no
bandwidth limit. (It was accidentally broken in 3.2.2.)
- Fixed a bug when combining `--delete-missing-args` with `--no-implied-dirs` &
`-R` where rsync might create the destination path of a missing arg. The
code also avoids some superfluous warnings for nested paths of removed args.
- Fixed a bug when combining [`--delete-missing-args`](rsync.1#opt) with
[`--no-implied-dirs`](rsync.1#opt) & [`-R`](rsync.1#opt) where rsync might
create the destination path of a missing arg. The code also avoids some
superfluous warnings for nested paths of removed args.
- Fixed an issue where hard-linked devices could cause the rdev_major value to
get out of sync between the sender and the receiver, which could cause a
device to get created with the wrong major value in its major,minor pair.
- Rsync now complains about a missing `--temp-dir` before starting any file
transfers.
- Rsync now complains about a missing [`--temp-dir`](rsync.1#opt) before
starting any file transfers.
- A completely empty source arg is now a fatal error. This doesn't change
the handling of implied dot-dir args such as "localhost:" and such.
### ENHANCEMENTS:
- Allow `--max-alloc=0` to specify no limit to the alloc sanity check.
- Allow [`--max-alloc=0`](rsync.1#opt) to specify no limit to the alloc sanity
check.
- Allow `--block-size=SIZE` to specify the size using units (e.g. "100K").
- Allow [`--block-size=SIZE`](rsync.1#opt) to specify the size using units
(e.g. "100K").
- The name of the id-0 user & group are now sent to the receiver along with
the other user/group names in the transfer (instead of assuming that both
sides have the same id-0 names).
- Added the `--stop-after=MINS` and `--stop-at=DATE_TIME` options (with the
`--time-limit=MINS` option accepted as an alias for `--stop-after`). This
is an enhanced version of the time-limit patch from the patches repo.
- Added the [`--stop-after`](rsync.1#opt) and [`--stop-at`](rsync.1#opt)
options (with a [`--time-limit`](rsync.1#opt) alias for `--stop-after`).
This is an enhanced version of the time-limit patch from the patches repo.
- Added the `name converter` daemon parameter to make it easier to convert
user & group names inside a chrooted daemon module. This is based on the
nameconverter patch with some improvements, including a tweak to the request
protocol (so if you used this patch in the past, be sure to update your
converter script to use newlines instead of null chars).
- Added the [`name converter`](rsyncd.conf.5#opt) daemon parameter to make it
easier to convert user & group names inside a chrooted daemon module. This
is based on the nameconverter patch with some improvements, including a
tweak to the request protocol (so if you used this patch in the past, be
sure to update your converter script to use newlines instead of null chars).
- Added `--crtimes` (`-N`) option for preserving the file's create time (I
believe that this is macOS only at the moment).
- Added [`--crtimes`](rsync.1#opt) (`-N`) option for preserving the file's
create time (I believe that this is macOS only at the moment).
- Added `--mkpath` option to tell rsync that it should create a non-existing
path component of the destination arg.
- Added [`--mkpath`](rsync.1#opt) option to tell rsync that it should create a
non-existing path component of the destination arg.
- Added `--stderr=errors|all|client` to replace the `--msgs2stderr` and
`--no-msgs2stderr` options (which are still accepted). The default use of
stderr was changed to be `--stderr=errors` where all the processes that have
stderr available output directly to stderr, which should help error messages
get to the user more quickly, especially when doing a push (which includes
local copying). This also allows rsync to exit quickly when a receiver
failure occurs, since rsync doesn't need to try to keep the connection alive
long enough for the fatal error to go from the receiver to the generator to
the sender. The old default can be requested via `--stderr=client`. Also
changed is that a non-default stderr mode is conveyed to the remote rsync
(using the older option names) instead of requiring the user to use
`--remote-option` (`-M`) to tell the remote rsync what to do.
- Added [`--stderr=errors|all|client`](rsync.1#opt) to replace the
`--msgs2stderr` and `--no-msgs2stderr` options (which are still accepted).
The default use of stderr was changed to be `--stderr=errors` where all the
processes that have stderr available output directly to stderr, which should
help error messages get to the user more quickly, especially when doing a
push (which includes local copying). This also allows rsync to exit quickly
when a receiver failure occurs, since rsync doesn't need to try to keep the
connection alive long enough for the fatal error to go from the receiver to
the generator to the sender. The old default can be requested via
`--stderr=client`. Also changed is that a non-default stderr mode is
conveyed to the remote rsync (using the older option names) instead of
requiring the user to use [`--remote-option`](rsync.1#opt) (`-M`) to tell
the remote rsync what to do.
- Added the ability to specify "@netgroup" names to the `hosts allow` and
`hosts deny` daemon parameters. This is a finalized version of the
netgroup-auth patch from the patches repo.
- Added the ability to specify "@netgroup" names to the [`hosts
allow`](rsyncd.conf.5#opt) and [`hosts deny`](rsyncd.conf.5#opt) daemon
parameters. This is a finalized version of the netgroup-auth patch from the
patches repo.
- Rsync can now hard-link symlinks on FreeBSD due to it making use of the
linkat() function when it is available.

81
md-convert
View File

@@ -32,6 +32,8 @@
import os, sys, re, argparse, subprocess, time
from html.parser import HTMLParser
VALID_PAGES = 'README INSTALL COPYING rsync.1 rrsync.1 rsync-ssl.1 rsyncd.conf.5'.split()
CONSUMES_TXT = set('h1 h2 h3 p li pre'.split())
HTML_START = """\
@@ -120,7 +122,7 @@ BIN_CHARS_RE = re.compile(r'[\1-\7]+')
SPACE_DOUBLE_DASH_RE = re.compile(r'\s--(\s)')
NON_SPACE_SINGLE_DASH_RE = re.compile(r'(^|\W)-')
WHITESPACE_RE = re.compile(r'\s')
CODE_BLOCK_RE = re.compile(r'[%s](.+?)[=%s].*' % (BOLD_FONT[0], NORM_FONT[0]))
CODE_BLOCK_RE = re.compile(r'[%s]([^=%s]+)[=%s]' % (BOLD_FONT[0], NORM_FONT[0], NORM_FONT[0]))
NBR_DASH_RE = re.compile(r'[%s]' % NBR_DASH[0])
INVALID_TARGET_CHARS_RE = re.compile(r'[^-A-Za-z0-9._]')
INVALID_START_CHAR_RE = re.compile(r'^([^A-Za-z0-9])')
@@ -148,7 +150,7 @@ def parse_md_file(mdfn):
if fi.want_manpage:
fi.title = fi.prog + '(' + fi.sect + ') man page'
else:
fi.title = fi.prog
fi.title = fi.prog + ' for rsync'
if fi.want_manpage:
if not env_subs:
@@ -268,7 +270,7 @@ class TransformHtml(HTMLParser):
derived_hashtags = set(),
referenced_hashtags = set(),
bad_hashtags = set(),
prior_target = None,
latest_targets = [ ],
opt_prefix = 'opt',
a_txt_start = None,
target_suf = '',
@@ -294,11 +296,11 @@ class TransformHtml(HTMLParser):
fi.man_out = ''.join(st.man_out)
st.man_out = None
for href, txt in st.derived_hashtags:
derived = txt2target(txt, href[1:])
for tgt, txt in st.derived_hashtags:
derived = txt2target(txt, tgt)
if derived not in st.created_hashtags:
txt = BIN_CHARS_RE.sub('', txt.replace(NBR_DASH[0], '-').replace(NBR_SPACE[0], ' '))
warn('Unknown derived hashtag link in', self.fn, 'based on:', (href, txt))
warn('Unknown derived hashtag link in', self.fn, 'based on:', (tgt, txt))
for bad in st.bad_hashtags:
if bad in st.created_hashtags:
@@ -380,13 +382,19 @@ class TransformHtml(HTMLParser):
st.a_href = None
for var, val in attrs_list:
if var == 'href':
if val in ('#', '#opt', '#daemon-opt'):
st.a_href = val
elif val.startswith('#'):
st.referenced_hashtags.add(val[1:])
if val[1:] == st.prior_target:
warn('Found link to the current section in', self.fn + ':', val)
elif not val.startswith(('https://', 'http://', 'mailto:', 'ftp:', './')):
if val.startswith(('https://', 'http://', 'mailto:', 'ftp:')):
pass # nothing to check
elif '#' in val:
pg, tgt = val.split('#', 2)
if pg and pg not in VALID_PAGES or '#' in tgt:
st.bad_hashtags.add(val)
elif tgt in ('', 'opt', 'dopt'):
st.a_href = val
elif pg == '':
st.referenced_hashtags.add(tgt)
if tgt in st.latest_targets:
warn('Found link to the current section in', self.fn + ':', val)
elif val not in VALID_PAGES:
st.bad_hashtags.add(val)
st.a_txt_start = len(st.txt)
st.html_out.append('<' + tag + ''.join(' ' + var + '="' + htmlify(val) + '"' for var, val in attrs_list) + '>')
@@ -411,20 +419,20 @@ class TransformHtml(HTMLParser):
if m:
tgt = m.group(1)
st.target_suf = '-' + tgt
self.add_target(tgt)
self.add_targets(tgt)
elif tag == 'h2':
st.man_out.append(st.p_macro + '.SH "' + manify(txt) + '"\n')
self.add_target(txt, st.target_suf)
st.opt_prefix = 'daemon-opt' if txt == 'DAEMON OPTIONS' else 'opt'
self.add_targets(txt, st.target_suf)
st.opt_prefix = 'dopt' if txt == 'DAEMON OPTIONS' else 'opt'
elif tag == 'h3':
st.man_out.append(st.p_macro + '.SS "' + manify(txt) + '"\n')
self.add_target(txt, st.target_suf)
self.add_targets(txt, st.target_suf)
elif tag == 'p':
if st.dt_from == 'p':
tag = 'dt'
st.man_out.append('.IP "' + manify(txt) + '"\n')
if txt.startswith(BOLD_FONT[0]):
self.add_target(txt)
self.add_targets(txt)
st.dt_from = None
elif txt != '':
st.man_out.append(manify(txt) + "\n")
@@ -466,11 +474,13 @@ class TransformHtml(HTMLParser):
find = 'href="' + st.a_href + '"'
for j in range(len(st.html_out)-1, 0, -1):
if find in st.html_out[j]:
derived = txt2target(atxt, st.a_href[1:])
if derived == st.prior_target:
warn('Found link to the current section in', self.fn + ':', derived)
st.derived_hashtags.add((st.a_href, atxt))
st.html_out[j] = st.html_out[j].replace(find, 'href="#' + derived + '"')
pg, tgt = st.a_href.split('#', 2)
derived = txt2target(atxt, tgt)
if pg == '':
if derived in st.latest_targets:
warn('Found link to the current section in', self.fn + ':', st.a_href)
st.derived_hashtags.add((tgt, atxt))
st.html_out[j] = st.html_out[j].replace(find, 'href="' + pg + '#' + derived + '"')
break
else:
die('INTERNAL ERROR: failed to find href in html data:', find)
@@ -509,10 +519,16 @@ class TransformHtml(HTMLParser):
st.txt += txt
def add_target(self, txt, suf=None):
def add_targets(self, txt, suf=None):
st = self.state
txt = txt2target(txt, st.opt_prefix)
if txt:
targets = CODE_BLOCK_RE.findall(txt)
if not targets:
targets = [ txt ]
first_one = True
for txt in targets:
txt = txt2target(txt, st.opt_prefix)
if not txt:
continue
if suf:
txt += suf
if txt in st.created_hashtags:
@@ -522,9 +538,13 @@ class TransformHtml(HTMLParser):
print('Made link target unique:', chk)
txt = chk
break
st.html_out.append('<a id="' + txt + '" href="#' + txt + '" class="tgt"></a>')
if first_one:
st.html_out.append('<a id="' + txt + '" href="#' + txt + '" class="tgt"></a>')
first_one = False
else:
st.html_out.append('<span id="' + txt + '"></span>')
st.created_hashtags.add(txt)
st.prior_target = txt
st.latest_targets = targets
def output_debug(self, event, extra):
@@ -541,7 +561,10 @@ class TransformHtml(HTMLParser):
def txt2target(txt, opt_prefix):
txt = CODE_BLOCK_RE.sub(r'\1', txt.strip().rstrip(':'))
txt = txt.strip().rstrip(':')
m = CODE_BLOCK_RE.search(txt)
if m:
txt = m.group(1)
txt = NBR_DASH_RE.sub('-', txt)
txt = BIN_CHARS_RE.sub('', txt)
txt = INVALID_TARGET_CHARS_RE.sub('_', txt)

4
rsync-ssl.1.md
View File

@@ -96,7 +96,7 @@ The ssl helper scripts are affected by the following environment variables:
## SEE ALSO
[**rsync**(1)](./rsync.1), [**rsyncd.conf**(5)](./rsyncd.conf.5)
[**rsync**(1)](rsync.1), [**rsyncd.conf**(5)](rsyncd.conf.5)
## CAVEATS
@@ -122,7 +122,7 @@ This man page is current for version @VERSION@ of rsync.
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
[COPYING](./COPYING) for details.
[COPYING](COPYING) for details.
A web site is available at <https://rsync.samba.org/>. The site includes an
FAQ-O-Matic which may cover questions unanswered by this manual page.

241
rsync.1.md
View File

@@ -92,7 +92,7 @@ protocol). For remote transfers, a modern rsync uses ssh for its
communications, but it may have been configured to use a different remote shell
by default, such as rsh or remsh.
You can also specify any remote shell you like, either by using the [`-e`](#opt--rsh)
You can also specify any remote shell you like, either by using the [`-e`](#opt)
command line option, or by setting the RSYNC_RSH environment variable.
Note that rsync must be installed on both the source and destination machines.
@@ -270,7 +270,7 @@ In order to connect to an rsync daemon, the remote system needs to have a
daemon already running (or it needs to have configured something like inetd to
spawn an rsync daemon for incoming connections on a particular port). For full
information on how to start a daemon that will handling incoming socket
connections, see the [**rsyncd.conf**(5)](./rsyncd.conf.5) man page -- that is
connections, see the [**rsyncd.conf**(5)](rsyncd.conf.5) man page -- that is
the config file for the daemon, and it contains the full details for how to run
the daemon (including stand-alone and inetd configurations).
@@ -512,11 +512,11 @@ your home directory (remove the '=' for that).
[comment]: # (An OL starting at 0 is converted into a DL by the parser.)
0. `--help`, `-h` `(*)`
0. `--help`
Print a short help page describing the options available in rsync and exit.
(*) The `-h` short option will only invoke `--help` when used without other
options since it normally means [`--human-readable`](#opt).
You can also use `-h` for `--help` when it is used without any other
options (since it normally means [`--human-readable`](#opt)).
0. `--version`, `-V`
@@ -734,28 +734,28 @@ your home directory (remove the '=' for that).
crtimes (`-N`), nor the finding and preserving of hardlinks (`-H`).
The only exception to the above equivalence is when [`--files-from`](#opt)
is specified, in which case [`-r`](#opt--recursive) is not implied.
is specified, in which case [`-r`](#opt) is not implied.
0. `--no-OPTION`
You may turn off one or more implied options by prefixing the option name
with "no-". Not all options may be prefixed with a "no-": only options that
are implied by other options (e.g. `--no-D`, `--no-perms`) or have
different defaults in various circumstances (e.g. `--no-whole-file`,
`--no-blocking-io`, `--no-dirs`). You may specify either the short or the
long option name after the "no-" prefix (e.g. `--no-R` is the same as
`--no-relative`).
with "no-". Not all positive options have a negated opposite, but a lot
do, including those that can be used to disable an implied option (e.g.
`--no-D`, `--no-perms`) or have different defaults in various circumstances
(e.g. [`--no-whole-file`](#opt), `--no-blocking-io`, `--no-dirs`). Every
valid negated option accepts both the short and the long option name after
the "no-" prefix (e.g. `--no-R` is the same as `--no-relative`).
For example: if you want to use [`--archive`](#opt) (`-a`) but don't want
As an example, if you want to use [`--archive`](#opt) (`-a`) but don't want
[`--owner`](#opt) (`-o`), instead of converting `-a` into `-rlptgD`, you
could specify `-a --no-o` (or `-a --no-owner`).
can specify `-a --no-o` (aka `--archive --no-owner`).
The order of the options is important: if you specify `--no-r -a`, the `-r`
option would end up being turned on, the opposite of `-a --no-r`. Note
also that the side-effects of the [`--files-from`](#opt) option are NOT
positional, as it affects the default state of several options and slightly
changes the meaning of [`-a`](#opt--archive) (see the
[`--files-from`](#opt) option for more details).
changes the meaning of [`-a`](#opt) (see the [`--files-from`](#opt) option
for more details).
0. `--recursive`, `-r`
@@ -892,16 +892,20 @@ your home directory (remove the '=' for that).
what (if any) suffix gets appended using the [`--backup-dir`](#opt) and
[`--suffix`](#opt) options.
Note that if you don't specify [`--backup-dir`](#opt), (1) the
[`--omit-dir-times`](#opt) option will be forced on, and (2) if
[`--delete`](#opt) is also in effect (without [`--delete-excluded`](#opt)),
rsync will add a "protect" filter-rule for the backup suffix to the end of
all your existing excludes (e.g. `-f "P *~"`). This will prevent
previously backed-up files from being deleted. Note that if you are
supplying your own filter rules, you may need to manually insert your own
exclude/protect rule somewhere higher up in the list so that it has a high
enough priority to be effective (e.g., if your rules specify a trailing
inclusion/exclusion of `*`, the auto-added rule would never be reached).
If you don't specify [`--backup-dir`](#opt):
1. the [`--omit-dir-times`](#opt) option will be forced on
2. the use of [`--delete`](#opt) (without [`--delete-excluded`](#opt)),
causes rsync to add a "protect" [filter-rule](#FILTER_RULES) for the
backup suffix to the end of all your existing filters that looks like
this: `-f "P *~"`. This rule prevents previously backed-up files from
being deleted.
Note that if you are supplying your own filter rules, you may need to
manually insert your own exclude/protect rule somewhere higher up in the
list so that it has a high enough priority to be effective (e.g. if your
rules specify a trailing inclusion/exclusion of `*`, the auto-added rule
would never be reached).
0. `--backup-dir=DIR`
@@ -1480,11 +1484,11 @@ your home directory (remove the '=' for that).
This tells rsync to transfer modification times along with the files and
update them on the remote system. Note that if this option is not used,
the optimization that excludes files that have not been modified cannot be
effective; in other words, a missing `-t` (or [`-a`](#opt--archive)) will
cause the next transfer to behave as if it used [`--ignore-times`](#opt)
(`-I`), causing all files to be updated (though rsync's delta-transfer
algorithm will make the update fairly efficient if the files haven't
actually changed, you're much better off using `-t`).
effective; in other words, a missing `-t` (or [`-a`](#opt)) will cause the
next transfer to behave as if it used [`--ignore-times`](#opt) (`-I`),
causing all files to be updated (though rsync's delta-transfer algorithm
will make the update fairly efficient if the files haven't actually
changed, you're much better off using `-t`).
0. `--atimes`, `-U`
@@ -1572,7 +1576,7 @@ your home directory (remove the '=' for that).
This option is overridden by both [`--super`](#opt) and `--no-super`.
See also the [`fake super`](./rsyncd.conf.5#fake_super) setting in the
See also the [`fake super`](rsyncd.conf.5#fake_super) setting in the
daemon's rsyncd.conf file.
0. `--sparse`, `-S`
@@ -1631,6 +1635,15 @@ your home directory (remove the '=' for that).
source and destination are specified as local paths, but only if no
batch-writing option is in effect.
0. `--no-whole-file`, `--no-W`
Disable whole-file updating when it is enaled by default for a local
transfer. This usually slows rsync down, but it can be useful if you are
trying to minimize the writes to the destination file (if combined with
[`--inplace`](#opt)) or for testing the checksum-based update algorithm.
See also the [`--whole-file`](#opt) option.
0. `--checksum-choice=STR`, `--cc=STR`
This option overrides the checksum algorithms. If one algorithm name is
@@ -1730,10 +1743,10 @@ your home directory (remove the '=' for that).
When [`--info=skip2`](#opt) is used rsync will output "FILENAME exists
(INFO)" messages where the INFO indicates one of "type change", "sum
change" (requires [`-c`](#opt--checksum)), "file change" (based on the
quick check), "attr change", or "uptodate". Using [`--info=skip1`](#opt)
(which is also implied by 2 [`-v`](#opt--verbose) options) outputs the
exists message without the INFO suffix.
change" (requires [`-c`](#opt)), "file change" (based on the quick check),
"attr change", or "uptodate". Using [`--info=skip1`](#opt) (which is also
implied by 2 [`-v`](#opt) options) outputs the exists message without the
INFO suffix.
0. `--remove-source-files`
@@ -2219,8 +2232,8 @@ your home directory (remove the '=' for that).
[`--recursive`](#opt) (`-r`), so specify it explicitly, if you want it.
- These side-effects change the default state of rsync, so the position of
the `--files-from` option on the command-line has no bearing on how other
options are parsed (e.g. [`-a`](#opt--archive) works the same before or
after `--files-from`, as does `--no-R` and all other options).
options are parsed (e.g. [`-a`](#opt) works the same before or after
`--files-from`, as does `--no-R` and all other options).
The filenames that are read from the FILE are all relative to the source
dir -- any leading slashes are removed and no ".." references are allowed
@@ -2233,13 +2246,12 @@ your home directory (remove the '=' for that).
contains "bin/" (note the trailing slash), the immediate contents of the
directory would also be sent (without needing to be explicitly mentioned in
the file -- this began in version 2.6.4). In both cases, if the
[`-r`](#opt--recursive) option was enabled, that dir's entire hierarchy
would also be transferred (keep in mind that [`-r`](#opt--recursive) needs
to be specified explicitly with `--files-from`, since it is not implied by
[`-a`](#opt--archive). Also note that the effect of the (enabled by
default) [`-r`](#opt--relative) option is to duplicate only the path info
that is read from the file -- it does not force the duplication of the
source-spec path (/usr in this case).
[`-r`](#opt) option was enabled, that dir's entire hierarchy would also be
transferred (keep in mind that [`-r`](#opt) needs to be specified
explicitly with `--files-from`, since it is not implied by [`-a`](#opt).
Also note that the effect of the (enabled by default) [`-r`](#opt) option
is to duplicate only the path info that is read from the file -- it does
not force the duplication of the source-spec path (/usr in this case).
In addition, the `--files-from` file can be read from the remote host
instead of the local host if you specify a "host:" in front of the file
@@ -2741,7 +2753,7 @@ your home directory (remove the '=' for that).
If a user or group has no name on the source system or it has no match on
the destination system, then the numeric ID from the source system is used
instead. See also the [`use chroot`](./rsyncd.conf.5#use_chroot) setting
instead. See also the [`use chroot`](rsyncd.conf.5#use_chroot) setting
in the rsyncd.conf manpage for some comments on how the chroot setting
affects rsync's ability to look up the names of the users and groups and
what you can do about it.
@@ -2799,7 +2811,7 @@ your home directory (remove the '=' for that).
0. `--chown=USER:GROUP`
This option forces all files to be owned by USER with group GROUP. This is
a simpler interface than using [`--usermap` & `--groupmap`](#opt--usermap)
a simpler interface than using [`--usermap`](#opt) & [`--groupmap`](#opt)
directly, but it is implemented using those options internally so they
cannot be mixed. If either the USER or GROUP is empty, no mapping for the
omitted user/group will occur. If GROUP is empty, the trailing colon may
@@ -2831,8 +2843,7 @@ your home directory (remove the '=' for that).
rsync daemon. The `--address` option allows you to specify a specific IP
address (or hostname) to bind to.
See also [the daemon version of the `--address`
option](#daemon-opt--address).
See also [the daemon version of the `--address` option](#dopt--address).
0. `--port=PORT`
@@ -2841,7 +2852,7 @@ your home directory (remove the '=' for that).
to connect with an rsync daemon (since the URL syntax has a way to specify
the port as a part of the URL).
See also [the daemon version of the `--port` option](#daemon-opt--port).
See also [the daemon version of the `--port` option](#dopt--port).
0. `--sockopts=OPTIONS`
@@ -2852,8 +2863,7 @@ your home directory (remove the '=' for that).
able to set. By default no special socket options are set. This only
affects direct socket connections to a remote rsync daemon.
See also [the daemon version of the `--sockopts`
option](#daemon-opt--sockopts).
See also [the daemon version of the `--sockopts` option](#dopt--sockopts).
0. `--blocking-io`
@@ -2955,11 +2965,10 @@ your home directory (remove the '=' for that).
user on a per-update basis. The format is a text string containing
embedded single-character escape sequences prefixed with a percent (%)
character. A default format of "%n%L" is assumed if either
[`--info=name`](#opt) or [`-v`](#opt--verbose) is specified (this tells you
just the name of the file and, if the item is a link, where it points).
For a full list of the possible escape characters, see the
[`log format`](./rsyncd.conf.5#log_format) setting in the rsyncd.conf
manpage.
[`--info=name`](#opt) or [`-v`](#opt) is specified (this tells you just the
name of the file and, if the item is a link, where it points). For a full
list of the possible escape characters, see the [`log
format`](rsyncd.conf.5#log_format) setting in the rsyncd.conf manpage.
Specifying the `--out-format` option implies the [`--info=name`](#opt)
option, which will mention each file, dir, etc. that gets updated in a
@@ -2994,8 +3003,7 @@ your home directory (remove the '=' for that).
This is very useful if you need to debug why a connection is closing
unexpectedly.
See also [the daemon version of the `--log-file`
option](#daemon-opt--log-file).
See also [the daemon version of the `--log-file` option](#dopt--log-file).
0. `--log-file-format=FORMAT`
@@ -3003,23 +3011,22 @@ your home directory (remove the '=' for that).
file specified by the [`--log-file`](#opt) option (which must also be
specified for this option to have any effect). If you specify an empty
string, updated files will not be mentioned in the log file. For a list of
the possible escape characters, see the [`log format`](./rsyncd.conf.5#log_format)
the possible escape characters, see the [`log format`](rsyncd.conf.5#log_format)
setting in the rsyncd.conf manpage.
The default FORMAT used if [`--log-file`](#opt) is specified and this
option is not is '%i %n%L'.
See also [the daemon version of the `--log-file-format`
option](#daemon-opt--log-file-format).
option](#dopt--log-file-format).
0. `--stats`
This tells rsync to print a verbose set of statistics on the file transfer,
allowing you to tell how effective rsync's delta-transfer algorithm is for
your data. This option is equivalent to [`--info=stats2`](#opt) if
combined with 0 or 1 [`-v`](#opt--verbose) options, or
[`--info=stats3`](#opt) if combined with 2 or more [`-v`](#opt--verbose)
options.
combined with 0 or 1 [`-v`](#opt) options, or [`--info=stats3`](#opt) if
combined with 2 or more [`-v`](#opt) options.
The current statistics are as follows:
@@ -3080,12 +3087,14 @@ your home directory (remove the '=' for that).
0. `--human-readable`, `-h`
Output numbers in a more human-readable format. There are 3 possible
levels: (1) output numbers with a separator between each set of 3 digits
(either a comma or a period, depending on if the decimal point is
represented by a period or a comma); (2) output numbers in units of 1000
(with a character suffix for larger units -- see below); (3) output
numbers in units of 1024.
Output numbers in a more human-readable format. There are 3 possible levels:
1. output numbers with a separator between each set of 3 digits (either a
comma or a period, depending on if the decimal point is represented by a
period or a comma).
2. output numbers in units of 1000 (with a character suffix for larger
units -- see below).
3. output numbers in units of 1024.
The default is human-readable level 1. Each `-h` option increases the
level by one. You can take the level down to 0 (to output numbers as pure
@@ -3141,14 +3150,17 @@ your home directory (remove the '=' for that).
rules.
If you are supplying your own exclude rules, you may need to add your own
exclude/hide/protect rule for the partial-dir because (1) the auto-added
rule may be ineffective at the end of your other rules, or (2) you may wish
to override rsync's exclude choice. For instance, if you want to make
rsync clean-up any left-over partial-dirs that may be lying around, you
should specify [`--delete-after`](#opt) and add a "risk" filter rule, e.g.
`-f 'R .rsync-partial/'`. (Avoid using [`--delete-before`](#opt) or
[`--delete-during`](#opt) unless you don't need rsync to use any of the
left-over partial-dir data during the current run.)
exclude/hide/protect rule for the partial-dir because:
1. the auto-added rule may be ineffective at the end of your other rules, or
2. you may wish to override rsync's exclude choice.
For instance, if you want to make rsync clean-up any left-over partial-dirs
that may be lying around, you should specify [`--delete-after`](#opt) and
add a "risk" filter rule, e.g. `-f 'R .rsync-partial/'`. Avoid using
[`--delete-before`](#opt) or [`--delete-during`](#opt) unless you don't
need rsync to use any of the left-over partial-dir data during the current
run.
IMPORTANT: the `--partial-dir` should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
@@ -3161,9 +3173,11 @@ your home directory (remove the '=' for that).
set RSYNC_PARTIAL_DIR=.rsync-tmp in your environment and then just use the
[`-P`](#opt) option to turn on the use of the .rsync-tmp dir for partial
transfers. The only times that the [`--partial`](#opt) option does not
look for this environment value are (1) when [`--inplace`](#opt) was
specified (since [`--inplace`](#opt) conflicts with `--partial-dir`), and
(2) when [`--delay-updates`](#opt) was specified (see below).
look for this environment value are:
1. when [`--inplace`](#opt) was specified (since [`--inplace`](#opt)
conflicts with `--partial-dir`), and
2. when [`--delay-updates`](#opt) was specified (see below).
When a modern rsync resumes the transfer of a file in the partial-dir, that
partial file is now updated in-place instead of creating yet another
@@ -3197,11 +3211,13 @@ your home directory (remove the '=' for that).
This option uses more memory on the receiving side (one bit per file
transferred) and also requires enough free disk space on the receiving side
to hold an additional copy of all the updated files. Note also that you
should not use an absolute path to [`--partial-dir`](#opt) unless (1) there
is no chance of any of the files in the transfer having the same name
(since all the updated files will be put into a single directory if the
path is absolute) and (2) there are no mount points in the hierarchy (since
the delayed updates will fail if they can't be renamed into place).
should not use an absolute path to [`--partial-dir`](#opt) unless:
1. there is no chance of any of the files in the transfer having the same
name (since all the updated files will be put into a single directory if
the path is absolute), and
2. there are no mount points in the hierarchy (since the delayed updates
will fail if they can't be renamed into place).
See also the "atomic-rsync" python script in the "support" subdir for an
update algorithm that is even more atomic (it uses [`--link-dest`](#opt)
@@ -3346,12 +3362,16 @@ your home directory (remove the '=' for that).
This option will cause the source files to be listed instead of
transferred. This option is inferred if there is a single source arg and
no destination specified, so its main uses are: (1) to turn a copy command
that includes a destination arg into a file-listing command, or (2) to be
able to specify more than one source arg (note: be sure to include the
destination). Caution: keep in mind that a source arg with a wild-card is
expanded by the shell into multiple args, so it is never safe to try to
list such an arg without using this option. For example:
no destination specified, so its main uses are:
1. to turn a copy command that includes a destination arg into a
file-listing command, or
2. to be able to specify more than one source arg. Note: be sure to
include the destination.
CAUTION: keep in mind that a source arg with a wild-card is expanded by the
shell into multiple args, so it is never safe to try to list such an arg
without using this option. For example:
> rsync -av --list-only foo* dest/
@@ -3397,22 +3417,21 @@ your home directory (remove the '=' for that).
quickly buffered, while other can show up as very slow when the flushing of
the output buffer occurs. This may be fixed in a future version.
See also [the daemon version of the `--bwlimit`
option](#daemon-opt--bwlimit).
See also [the daemon version of the `--bwlimit` option](#dopt--bwlimit).
0. `--stop-after=MINS`
0. `--stop-after=MINS`, (`--time-limit=MINS`)
This option tells rsync to stop copying when the specified number of
minutes has elapsed.
Rsync also accepts an earlier version of this option: `--time-limit=MINS`.
For maximal flexibility, rsync does not communicate this option to the
remote rsync since it is usually enough that one side of the connection
quits as specified. This allows the option's use even when only one side
of the connection supports it. You can tell the remote side about the time
limit using [`--remote-option`](#opt) (`-M`), should the need arise.
The `--time-limit` version of this option is deprecated.
0. `--stop-at=y-m-dTh:m`
This option tells rsync to stop copying when the specified point in time
@@ -3534,7 +3553,7 @@ your home directory (remove the '=' for that).
the "`--rsh SHELL -4`" option directly (or whatever ipv4/ipv6 hint options
it uses).
See also [the daemon version of these options](#daemon-opt--ipv4).
See also [the daemon version of these options](#dopt--ipv4).
If rsync was compiled without support for IPv6, the `--ipv6` option will
have no effect. The `rsync --version` output will contain "`no IPv6`" if
@@ -3566,7 +3585,7 @@ The options allowed when starting an rsync daemon are as follows:
background daemon. The daemon will read the config file (rsyncd.conf) on
each connect made by a client and respond to requests accordingly.
See the [**rsyncd.conf**(5)](./rsyncd.conf.5) man page for more details.
See the [**rsyncd.conf**(5)](rsyncd.conf.5) man page for more details.
0. `--address=ADDRESS`
@@ -3575,7 +3594,7 @@ The options allowed when starting an rsync daemon are as follows:
specific IP address (or hostname) to bind to. This makes virtual hosting
possible in conjunction with the `--config` option.
See also the [address](./rsyncd.conf.5#address) global option in the
See also the [address](rsyncd.conf.5#address) global option in the
rsyncd.conf manpage and the [client version of the `--address`
option](#opt--address).
@@ -3591,7 +3610,7 @@ The options allowed when starting an rsync daemon are as follows:
0. `--config=FILE`
This specifies an alternate config file than the default. This is only
relevant when [`--daemon`](#daemon-opt) is specified. The default is
relevant when [`--daemon`](#dopt) is specified. The default is
/etc/rsyncd.conf unless the daemon is running over a remote shell program
and the remote user is not the super-user; in that case the default is
rsyncd.conf in the current directory (typically $HOME).
@@ -3621,7 +3640,7 @@ The options allowed when starting an rsync daemon are as follows:
rather than the default of 873.
See also [the client version of the `--port` option](#opt--port) and the
[port](./rsyncd.conf.5#port) global setting in the rsyncd.conf manpage.
[port](rsyncd.conf.5#port) global setting in the rsyncd.conf manpage.
0. `--log-file=FILE`
@@ -3642,7 +3661,7 @@ The options allowed when starting an rsync daemon are as follows:
0. `--sockopts`
This overrides the [`socket options`](./rsyncd.conf.5#socket_options)
This overrides the [`socket options`](rsyncd.conf.5#socket_options)
setting in the rsyncd.conf file and has the same syntax.
See also [the client version of the `--sockopts` option](#opt--sockopts).
@@ -3780,8 +3799,8 @@ forms:
had been specified). This behavior was added in version 2.6.7.
Note that, when using the [`--recursive`](#opt) (`-r`) option (which is implied
by [`-a`](#opt--archive)), every subdir component of every path is visited left
to right, with each directory having a chance for exclusion before its content.
by [`-a`](#opt)), every subdir component of every path is visited left to
right, with each directory having a chance for exclusion before its content.
In this way include/exclude patterns are applied recursively to the pathname of
each node in the filesystem's tree (those inside the transfer). The exclude
patterns short-circuit the directory traversal stage as rsync finds the files
@@ -4175,10 +4194,10 @@ already) or the file-update may be attempted and then, if the file fails to
verify, the update discarded with an error. This means that it should be safe
to re-run a read-batch operation if the command got interrupted. If you wish
to force the batched-update to always be attempted regardless of the file's
size and date, use the [`-I`](#opt--ignore-times) option (when reading the
batch). If an error occurs, the destination tree will probably be in a
partially updated state. In that case, rsync can be used in its regular
(non-batch) mode of operation to fix up the destination tree.
size and date, use the [`-I`](#opt) option (when reading the batch). If an
error occurs, the destination tree will probably be in a partially updated
state. In that case, rsync can be used in its regular (non-batch) mode of
operation to fix up the destination tree.
The rsync version used on all destinations must be at least as new as the one
used to generate the batch file. Rsync will die with an error if the protocol
@@ -4368,7 +4387,7 @@ file is included or excluded.
## SEE ALSO
[**rsync-ssl**(1)](./rsync-ssl.1), [**rsyncd.conf**(5)](./rsyncd.conf.5), [**rrsync**(1)](./rrsync.1)
[**rsync-ssl**(1)](rsync-ssl.1), [**rsyncd.conf**(5)](rsyncd.conf.5), [**rrsync**(1)](rrsync.1)
## BUGS
@@ -4396,7 +4415,7 @@ that can be used with a restricted ssh login.
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
[COPYING](./COPYING) for details.
[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/>. The site
includes an FAQ-O-Matic which may cover questions unanswered by this manual

4
rsyncd.conf.5.md
View File

@@ -1210,7 +1210,7 @@ The /etc/rsyncd.secrets file would look something like this:
## SEE ALSO
[**rsync**(1)](./rsync.1), [**rsync-ssl**(1)](./rsync-ssl.1)
[**rsync**(1)](rsync.1), [**rsync-ssl**(1)](rsync-ssl.1)
## BUGS
@@ -1224,7 +1224,7 @@ This man page is current for version @VERSION@ of rsync.
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
[COPYING](./COPYING) for details.
[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/> and its github
project is <https://github.com/WayneD/rsync>.

63
support/rrsync.1.md
View File

@@ -8,6 +8,9 @@ rrsync - a script to setup restricted rsync users via ssh logins
rrsync [-ro|-rw] [-munge] [-no-del] [-no-lock] DIR
```
The single non-option argument specifies the restricted _DIR_ to use. It can be
relative to the user's home directory or an absolute path.
The online version of this man page (that includes cross-linking of topics)
is available at <https://download.samba.org/pub/rsync/rrsync.1>.
@@ -30,7 +33,7 @@ ssh-key line that should be restricted:
Then, ensure that the rrsync script has your desired option restrictions. You
may want to copy the script to a local bin dir with a unique name if you want
to have multiple configurations. One or more rrsync options can be specified
prior to the `DIR` if you want to further restrict the transfer.
prior to the _DIR_ if you want to further restrict the transfer.
To use an rsync daemon setup, edit the user's `~/.ssh/authorized_keys` file and
add a prefix like one of the following (followed by a space) in front of each
@@ -43,9 +46,8 @@ ssh-key line that should be restricted:
Then, ensure that the rsyncd.conf file is created with one or more module names
with the appropriate path and option restrictions. If rsync's
[`--config`](./rsync.1#daemon-opt--config) option is omitted, it defaults to
`~/rsyncd.conf`. See the `rsyncd.conf` man page for details of how to
configure an rsync daemon.
[`--config`](rsync.1#dopt) option is omitted, it defaults to `~/rsyncd.conf`.
See the `rsyncd.conf` man page for details of how to configure an rsync daemon.
When using rrsync, there can be just one restricted dir per authorized key. A
daemon setup, on the other hand, allows multiple module names inside the config
@@ -53,33 +55,46 @@ file, each one with its own path setting.
The remainder of this man page is dedicated to using the rrsync script.
## OPTION SUMMARY
## OPTIONS
```
-ro Allow only reading from the DIR. Implies -no-del and -no-lock.
-wo Allow only writing to the DIR.
-munge Enable rsync's --munge-links on the server side.
-no-del Disable rsync's --delete* and --remove* options.
-no-lock Avoid the single-run (per-user) lock check.
-help, -h Output this help message and exit.
```
0. `-ro`
A single non-option argument specifies the restricted DIR to use. It can be
relative to the user's home directory or an absolute path.
Allow only reading from the DIR. Implies [`-no-del`](#opt) and
[`-no-lock`](#opt).
0. `-wo`
Allow only writing to the DIR.
0. `-munge`
Enable rsync's [`--munge-links`](rsync.1#opt) on the server side.
0. `-no-del`
Disable rsync's `--delete*` and `--remove*` options.
0. `-no-lock`
Avoid the single-run (per-user) lock check. Useful with [`-munge`](#opt).
0. `-help`, `-h`
Output this help message and exit.
## SECURITY RESTRICTIONS
The rrsync script validates the path arguments it is sent to try to restrict
them to staying within the specified DIR.
The rrsync script rejects rsync's [`--copy-links`](./rsync.1#opt--copy-links)
option (by default) so that a copy cannot dereference a symlink within the DIR
to get to a file outside the DIR.
The rrsync script rejects rsync's [`--copy-links`](rsync.1#opt) option (by
default) so that a copy cannot dereference a symlink within the DIR to get to a
file outside the DIR.
The rrsync script rejects rsync's
[`--protect-args`](./rsync.1#opt--protect-args) (`-s`) option because it would
allow options to be sent to the server-side that the script cannot check. If
you want to support `--protect-args`, use a daemon-over-ssh setup.
The rrsync script rejects rsync's [`--protect-args`](rsync.1#opt) (`-s`) option
because it would allow options to be sent to the server-side that the script
cannot check. If you want to support `--protect-args`, use a daemon-over-ssh
setup.
The rrsync script accepts just a subset of rsync's options that the real rsync
uses when running the server command. A few extra convenience options are also
@@ -104,7 +119,7 @@ The `~/.ssh/authorized_keys` file might have lines in it like this:
## SEE ALSO
[**rsync**(1)](./rsync.1)
[**rsync**(1)](rsync.1)
## VERSION
@@ -113,7 +128,7 @@ This man page is current for version @VERSION@ of rsync.
## CREDITS
rsync is distributed under the GNU General Public License. See the file
[COPYING](./COPYING) for details.
[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/> and its github
project is <https://github.com/WayneD/rsync>.