From 0a09df2c5e62fa4e694f76a35d6f4e786907ef75 Mon Sep 17 00:00:00 2001 From: Wayne Davison Date: Tue, 23 Aug 2022 08:28:06 -0700 Subject: [PATCH] Rename `--protect-args` to `--secluded-args`. --- NEWS.md | 13 +++++++++- clientserver.c | 2 +- configure.ac | 8 +++--- options.c | 10 +++++--- rsync.1.md | 66 ++++++++++++++++++++++++++---------------------- rsyncd.conf.5.md | 4 +-- usage.c | 4 +-- 7 files changed, 63 insertions(+), 44 deletions(-) diff --git a/NEWS.md b/NEWS.md index 4b949766..f13f4ea5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -21,8 +21,19 @@ - A minor tweak to rrsync added "copy-devices" to the list of known args, but left it disabled by default. +### ENHANCEMENTS: + +- Rename `--protect-args` to [`--secluded-args`](#rsync.1#opt) to make it + clearer how it differs from the default backslash-escaped arg-protecting + behavior of rsync. The old option names are still accepted. The + environment-variable override did not change its name. + ### PACKAGING RELATED: +- The configure option `--with-protected-args` was renamed to + `--with-secluded-args`. This option makes `--secluded-args` the default + rsync behavior instead of using backslash escaping for protecting args. + - The mkgitver script now makes sure that a `.git` dir/file is in the top-level source dir before calling `git describe`. It also runs a basic check on the version value. This should avoid using an unrelated git description for @@ -104,7 +115,7 @@ ### BEHAVIOR CHANGES: - A new form of arg protection was added that works similarly to the older - [`--protect-args`](rsync.1#opt) (`-s`) option but in a way that avoids + `--protect-args` ([`-s`](rsync.1#opt)) 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 diff --git a/clientserver.c b/clientserver.c index 66311d3e..ca897ff1 100644 --- a/clientserver.c +++ b/clientserver.c @@ -381,7 +381,7 @@ int start_inband_exchange(int f_in, int f_out, const char *user, int argc, char if (rl_nulls) { for (i = 0; i < sargc; i++) { - if (!sargs[i]) /* stop at --protect-args NULL */ + if (!sargs[i]) /* stop at --secluded-args NULL */ break; write_sbuf(f_out, sargs[i]); write_byte(f_out, 0); diff --git a/configure.ac b/configure.ac index cfc0117f..b6de4eb3 100644 --- a/configure.ac +++ b/configure.ac @@ -153,10 +153,10 @@ AC_ARG_WITH(included-popt, AC_ARG_WITH(included-zlib, AS_HELP_STRING([--with-included-zlib],[use bundled zlib library, not from system])) -AC_ARG_WITH(protected-args, - AS_HELP_STRING([--with-protected-args],[make --protected-args option the default])) -if test x"$with_protected_args" = x"yes"; then - AC_DEFINE_UNQUOTED(RSYNC_USE_PROTECTED_ARGS, 1, [Define to 1 if --protected-args should be the default]) +AC_ARG_WITH(secluded-args, + AS_HELP_STRING([--with-secluded-args],[make --secluded-args option the default])) +if test x"$with_secluded_args" = x"yes"; then + AC_DEFINE_UNQUOTED(RSYNC_USE_SECLUDED_ARGS, 1, [Define to 1 if --secluded-args should be the default]) fi AC_ARG_WITH(rsync-path, diff --git a/options.c b/options.c index 5b3d6dea..3f8d5d08 100644 --- a/options.c +++ b/options.c @@ -788,7 +788,9 @@ static struct poptOption long_options[] = { {"no-from0", 0, POPT_ARG_VAL, &eol_nulls, 0, 0, 0}, {"old-args", 0, POPT_ARG_NONE, 0, OPT_OLD_ARGS, 0, 0}, {"no-old-args", 0, POPT_ARG_VAL, &old_style_args, 0, 0, 0}, - {"protect-args", 's', POPT_ARG_VAL, &protect_args, 1, 0, 0}, + {"secluded-args", 's', POPT_ARG_VAL, &protect_args, 1, 0, 0}, + {"no-secluded-args", 0, POPT_ARG_VAL, &protect_args, 0, 0, 0}, + {"protect-args", 0, POPT_ARG_VAL, &protect_args, 1, 0, 0}, {"no-protect-args", 0, POPT_ARG_VAL, &protect_args, 0, 0, 0}, {"no-s", 0, POPT_ARG_VAL, &protect_args, 0, 0, 0}, {"trust-sender", 0, POPT_ARG_VAL, &trust_sender, 1, 0, 0}, @@ -950,7 +952,7 @@ static void set_refuse_options(void) if (!am_daemon || op->shortName == 'e' /* Required for compatibility flags */ || op->shortName == '0' /* --from0 just modifies --files-from, so refuse that instead (or not) */ - || op->shortName == 's' /* --protect-args is always OK */ + || op->shortName == 's' /* --secluded-args is always OK */ || op->shortName == 'n' /* --dry-run is always OK */ || strcmp("iconv", longName) == 0 || strcmp("no-iconv", longName) == 0 @@ -1949,7 +1951,7 @@ int parse_arguments(int *argc_p, const char ***argv_p) } else if (old_style_args) { if (protect_args > 0) { snprintf(err_buf, sizeof err_buf, - "--protect-args conflicts with --old-args.\n"); + "--secluded-args conflicts with --old-args.\n"); return 0; } protect_args = 0; @@ -1961,7 +1963,7 @@ int parse_arguments(int *argc_p, const char ***argv_p) else if ((arg = getenv("RSYNC_PROTECT_ARGS")) != NULL && *arg) protect_args = atoi(arg) ? 1 : 0; else { -#ifdef RSYNC_USE_PROTECTED_ARGS +#ifdef RSYNC_USE_SECLUDED_ARGS protect_args = 1; #else protect_args = 0; diff --git a/rsync.1.md b/rsync.1.md index 866a9e4f..2fbc6e11 100644 --- a/rsync.1.md +++ b/rsync.1.md @@ -464,7 +464,7 @@ has its own detailed description later in this manpage. --files-from=FILE read list of source-file names from FILE --from0, -0 all *-from/filter files are delimited by 0s --old-args disable the modern arg-protection idiom ---protect-args, -s no space-splitting; wildcard chars only +--secluded-args, -s use the protocol to safely send the args --trust-sender trust the remote sender's file list --copy-as=USER[:GROUP] specify user & optional group for the copy --address=ADDRESS bind address for outgoing socket to daemon @@ -2334,7 +2334,7 @@ expand it. This would copy all the files specified in the /path/file-list file that was located on the remote "src" host. - If the [`--iconv`](#opt) and [`--protect-args`](#opt) options are specified + If the [`--iconv`](#opt) and [`--secluded-args`](#opt) options are specified and the `--files-from` filenames are being sent from one host to another, the filenames will be translated from the sending host's charset to the receiving host's charset. @@ -2383,38 +2383,46 @@ expand it. because we can't know for sure what names to expect when the remote shell is interpreting the args. - This option conflicts with the [`--protect-args`](#opt) option. + This option conflicts with the [`--secluded-args`](#opt) option. -0. `--protect-args`, `-s` +0. `--secluded-args`, `-s` - This option sends all filenames and most options to the remote rsync - without allowing the remote shell to interpret them. Wildcards are - expanded on the remote host by rsync instead of the shell doing it. + This option sends all filenames and most options to the remote rsync via + the protocol (not the remote shell command line) which avoids letting the + remote shell modify them. Wildcards are expanded on the remote host by + rsync instead of a shell. - This is similar to the new-style backslash-escaping of args that was added - in 3.2.4, but supports some extra features and doesn't rely on backslash - escaping in the remote shell. + This is similar to the default backslash-escaping of args that was added + in 3.2.4 (see [`--old-args`](#opt)) in that it prevents things like space + splitting and unwanted special-character side-effects. However, it has the + drawbacks of being incompatible with older rsync versions (prior to 3.0.0) + and of being refused by restricted shells that want to be able to inspect + all the option values for safety. - If you use this option with [`--iconv`](#opt), the args related to the - remote side will also be translated from the local to the remote - character-set. The translation happens before wild-cards are expanded. - See also the [`--files-from`](#opt) option. + This option is useful for those times that you need the argument's + character set to be converted for the remote host, if the remote shell is + incompatible with the default backslash-escpaing method, or there is some + other reason that you want the majority of the options and arguments to + bypass the command-line of the remote shell. + + If you combine this option with [`--iconv`](#opt), the args related to the + remote side will be translated from the local to the remote character-set. + The translation happens before wild-cards are expanded. See also the + [`--files-from`](#opt) option. You may also control this setting via the [`RSYNC_PROTECT_ARGS`](#) environment variable. If it has a non-zero value, this setting will be enabled by default, otherwise it will be disabled by default. Either state is overridden by a manually specified positive or negative version of this - option (note that `--no-s` and `--no-protect-args` are the negative + option (note that `--no-s` and `--no-secluded-args` are the negative versions). This environment variable is also superseded by a non-zero [`RSYNC_OLD_ARGS`](#) export. - You may need to disable this option when interacting with an older rsync - (one prior to 3.0.0). - This option conflicts with the [`--old-args`](#opt) option. - Note that this option is incompatible with the use of the restricted rsync - script (`rrsync`) since it hides options from the script's inspection. + This option used to be called `--protect-args` (before 3.2.6) and that + older name can still be used (though specifying it as `-s` is always the + easiest and most compatible choice). 0. `--trust-sender` @@ -2922,9 +2930,8 @@ expand it. [`--group`](#opt) (`-g`) option (since rsync needs to have those options enabled for the mapping options to work). - An older rsync client may need to use [`--protect-args`](#opt) (`-s`) to - avoid a complaint about wildcard characters, but a modern rsync handles - this automatically. + An older rsync client may need to use [`-s`](#opt) to avoid a complaint + about wildcard characters, but a modern rsync handles this automatically. 0. `--chown=USER:GROUP` @@ -2939,9 +2946,8 @@ expand it. "`--usermap=*:foo --groupmap=*:bar`", only easier (and with the same implied [`--owner`](#opt) and/or [`--group`](#opt) options). - An older rsync client may need to use [`--protect-args`](#opt) (`-s`) to - avoid a complaint about wildcard characters, but a modern rsync handles - this automatically. + An older rsync client may need to use [`-s`](#opt) to avoid a complaint + about wildcard characters, but a modern rsync handles this automatically. 0. `--timeout=SECONDS` @@ -3645,7 +3651,7 @@ expand it. For a list of what charset names your local iconv library supports, you can run "`iconv --list`". - If you specify the [`--protect-args`](#opt) (`-s`) option, rsync will + If you specify the [`--secluded-args`](#opt) (`-s`) option, rsync will translate the filenames you specify on the command-line that are being sent to the remote host. See also the [`--files-from`](#opt) option. @@ -4593,17 +4599,17 @@ file is included or excluded. supersedes the [`RSYNC_PROTECT_ARGS`](#) variable. This variable is ignored if [`--old-args`](#opt), `--no-old-args`, or - [`--protect-args`](#opt) is specified on the command line. + [`--secluded-args`](#opt) is specified on the command line. First supported in 3.2.4. 0. `RSYNC_PROTECT_ARGS` - Specify a non-zero numeric value if you want the [`--protect-args`](#opt) + Specify a non-zero numeric value if you want the [`--secluded-args`](#opt) option to be enabled by default, or a zero value to make sure that it is disabled by default. - This variable is ignored if [`--protect-args`](#opt), `--no-protect-args`, + This variable is ignored if [`--secluded-args`](#opt), `--no-secluded-args`, or [`--old-args`](#opt) is specified on the command line. First supported in 3.1.0. Starting in 3.2.4, this variable is ignored if diff --git a/rsyncd.conf.5.md b/rsyncd.conf.5.md index 8bcbec0a..400ad107 100644 --- a/rsyncd.conf.5.md +++ b/rsyncd.conf.5.md @@ -894,7 +894,7 @@ the values of parameters. See the GLOBAL PARAMETERS section for more details. > refuse options = * !a !v !compress* Don't worry that the "`*`" will refuse certain vital options such as - `--dry-run`, `--server`, `--no-iconv`, `--protect-args`, etc. These + `--dry-run`, `--server`, `--no-iconv`, `--seclude-args`, etc. These important options are not matched by wild-card, so they must be overridden by their exact name. For instance, if you're forcing iconv transfers you could use something like this: @@ -948,7 +948,7 @@ the values of parameters. See the GLOBAL PARAMETERS section for more details. `--log-file-format`. - `--sender`: Use "[write only](#)" parameter instead of refusing this. - `--dry-run`, `-n`: Who would want to disable this? - - `--protect-args`, `-s`: This actually makes transfers safer. + - `--seclude-args`, `-s`: Is the oldest arg-protection method. - `--from0`, `-0`: Makes it easier to accept/refuse `--files-from` without affecting this helpful modifier. - `--iconv`: This is auto-disabled based on "[charset](#)" parameter. diff --git a/usage.c b/usage.c index df033c92..048fd4cb 100644 --- a/usage.c +++ b/usage.c @@ -110,12 +110,12 @@ static void print_info_flags(enum logcode f) #endif "xattrs", -#ifdef RSYNC_USE_PROTECTED_ARGS +#ifdef RSYNC_USE_SECLUDED_ARGS "default " #else "optional " #endif - "protect-args", + "secluded-args", #ifndef ICONV_OPTION "no " -- 2.34.1