Adding upstream version 3.2.7.upstream/3.2.7

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 166 insertions, 0 deletions

diff --git a/rrsync.1 b/rrsync.1
new file mode 100644
index 0000000..74f9d34
--- /dev/null
+++ b/rrsync.1
@@ -0,0 +1,166 @@
+.TH "rrsync" "1" "20 Oct 2022" "rrsync from rsync 3.2.7" "User Commands"
+.\" prefix=/usr
+.P
+.SH "NAME"
+.P
+rrsync \- a script to setup restricted rsync users via ssh logins
+.P
+.SH "SYNOPSIS"
+.P
+.nf
+rrsync [-ro|-rw] [-munge] [-no-del] [-no-lock] DIR
+.fi
+.P
+The single non-option argument specifies the restricted \fIDIR\fP to use. It can be
+relative to the user's home directory or an absolute path.
+.P
+The online version of this manpage (that includes cross-linking of topics)
+is available at https://download.samba.org/pub/rsync/rrsync.1.
+.P
+.SH "DESCRIPTION"
+.P
+A user's ssh login can be restricted to only allow the running of an rsync
+transfer in one of two easy ways:
+.P
+.IP o
+forcing the running of the rrsync script
+.IP o
+forcing the running of an rsync daemon-over-ssh command.
+.P
+Both of these setups use a feature of ssh that allows a command to be forced to
+run instead of an interactive shell.  However, if the user's home shell is bash,
+please see BASH SECURITY ISSUE for a potential issue.
+.P
+To use the rrsync script, edit the user's \fB~/.ssh/authorized_keys\fP file and add
+a prefix like one of the following (followed by a space) in front of each
+ssh-key line that should be restricted:
+.RS 4
+.P
+.nf
+command="rrsync DIR"
+command="rrsync -ro DIR"
+command="rrsync -munge -no-del DIR"
+.fi
+.RE
+.P
+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 \fIDIR\fP if you want to further restrict the transfer.
+.P
+To use an rsync daemon setup, edit the user's \fB~/.ssh/authorized_keys\fP file and
+add a prefix like one of the following (followed by a space) in front of each
+ssh-key line that should be restricted:
+.RS 4
+.P
+.nf
+command="rsync --server --daemon ."
+command="rsync --server --daemon --config=/PATH/TO/rsyncd.conf ."
+.fi
+.RE
+.P
+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
+\fB\-\-config\fP option is omitted, it defaults to \fB~/rsyncd.conf\fP.
+See the \fBrsyncd.conf\fP(5) manpage for details of how to
+configure an rsync daemon.
+.P
+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
+file, each one with its own path setting.
+.P
+The remainder of this manpage is dedicated to using the rrsync script.
+.P
+.SH "OPTIONS"
+.P
+.IP "\fB\-ro\fP"
+Allow only reading from the DIR. Implies \fB\-no-del\fP and
+\fB\-no-lock\fP.
+.IP "\fB\-wo\fP"
+Allow only writing to the DIR.
+.IP "\fB\-munge\fP"
+Enable rsync's \fB\-\-munge-links\fP on the server side.
+.IP "\fB\-no-del\fP"
+Disable rsync's \fB\-\-delete*\fP and \fB\-\-remove*\fP options.
+.IP "\fB\-no-lock\fP"
+Avoid the single-run (per-user) lock check.  Useful with \fB\-munge\fP.
+.IP "\fB\-help\fP, \fB\-h\fP"
+Output this help message and exit.
+.P
+.SH "SECURITY RESTRICTIONS"
+.P
+The rrsync script validates the path arguments it is sent to try to restrict
+them to staying within the specified DIR.
+.P
+The rrsync script rejects rsync's \fB\-\-copy-links\fP option (by
+default) so that a copy cannot dereference a symlink within the DIR to get to a
+file outside the DIR.
+.P
+The rrsync script rejects rsync's \fB\-\-protect-args\fP (\fB\-s\fP) option
+because it would allow options to be sent to the server-side that the script
+cannot check.  If you want to support \fB\-\-protect-args\fP, use a daemon-over-ssh
+setup.
+.P
+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
+included to help it to interact with BackupPC and accept some convenient user
+overrides.
+.P
+The script (or a copy of it) can be manually edited if you want it to customize
+the option handling.
+.P
+.SH "BASH SECURITY ISSUE"
+.P
+If your users have bash set as their home shell, bash may try to be overly
+helpful and ensure that the user's login bashrc files are run prior to
+executing the forced command.  This can be a problem if the user can somehow
+update their home bashrc files, perhaps via the restricted copy, a shared home
+directory, or something similar.
+.P
+One simple way to avoid the issue is to switch the user to a simpler shell,
+such as dash.  When choosing the new home shell, make sure that you're not
+choosing bash in disguise, as it is unclear if it avoids the security issue.
+.P
+Another potential fix is to ensure that the user's home directory is not a
+shared mount and that they have no means of copying files outside of their
+restricted directories.  This may require you to force the enabling of symlink
+munging on the server side.
+.P
+A future version of openssh may have a change to the handling of forced
+commands that allows it to avoid using the user's home shell.
+.P
+.SH "EXAMPLES"
+.P
+The \fB~/.ssh/authorized_keys\fP file might have lines in it like this:
+.RS 4
+.P
+.nf
+command="rrsync client/logs" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAzG...
+command="rrsync -ro results" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAmk...
+.fi
+.RE
+.P
+.SH "FILES"
+.P
+~/.ssh/authorized_keys
+.P
+.SH "SEE ALSO"
+.P
+\fBrsync\fP(1), \fBrsyncd.conf\fP(5)
+.P
+.SH "VERSION"
+.P
+This manpage is current for version 3.2.7 of rsync.
+.P
+.SH "CREDITS"
+.P
+rsync is distributed under the GNU General Public License.  See the file
+COPYING for details.
+.P
+An rsync web site is available at https://rsync.samba.org/ and its github
+project is https://github.com/WayneD/rsync.
+.P
+.SH "AUTHOR"
+.P
+The original rrsync perl script was written by Joe Smith.  Many people have
+later contributed to it.  The python version was created by Wayne Davison.