diff options
Diffstat (limited to 'rrsync.1')
| -rw-r--r-- | rrsync.1 | 166 |
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. |