| 1 |
.TH "rrsync" "1" "20 May 2026" "rrsync from rsync 3.4.3" "User Commands" |
| 2 |
.\" prefix=/usr |
| 3 |
.P |
| 4 |
.SH "NAME" |
| 5 |
.P |
| 6 |
rrsync \- a script to setup restricted rsync users via ssh logins |
| 7 |
.P |
| 8 |
.SH "SYNOPSIS" |
| 9 |
.P |
| 10 |
.nf |
| 11 |
rrsync [-ro|-wo] [-munge] [-no-del] [-no-lock] [-no-overwrite] DIR |
| 12 |
.fi |
| 13 |
.P |
| 14 |
The single non-option argument specifies the restricted \fIDIR\fP to use. It can be |
| 15 |
relative to the user's home directory or an absolute path. |
| 16 |
.P |
| 17 |
The online version of this manpage (that includes cross-linking of topics) |
| 18 |
is available at |
| 19 |
.UR https://download.samba.org/pub/rsync/rrsync.1 |
| 20 |
.UE . |
| 21 |
.P |
| 22 |
.SH "DESCRIPTION" |
| 23 |
.P |
| 24 |
A user's ssh login can be restricted to only allow the running of an rsync |
| 25 |
transfer in one of two easy ways: |
| 26 |
.P |
| 27 |
.IP o |
| 28 |
forcing the running of the rrsync script |
| 29 |
.IP o |
| 30 |
forcing the running of an rsync daemon-over-ssh command. |
| 31 |
.P |
| 32 |
Both of these setups use a feature of ssh that allows a command to be forced to |
| 33 |
run instead of an interactive shell. However, if the user's home shell is bash, |
| 34 |
please see BASH SECURITY ISSUE for a potential issue. |
| 35 |
.P |
| 36 |
To use the rrsync script, edit the user's \fB~/.ssh/authorized_keys\fP file and add |
| 37 |
a prefix like one of the following (followed by a space) in front of each |
| 38 |
ssh-key line that should be restricted: |
| 39 |
.RS 4 |
| 40 |
.P |
| 41 |
.nf |
| 42 |
command="rrsync DIR" |
| 43 |
command="rrsync -ro DIR" |
| 44 |
command="rrsync -munge -no-del DIR" |
| 45 |
.fi |
| 46 |
.RE |
| 47 |
.P |
| 48 |
Then, ensure that the rrsync script has your desired option restrictions. You |
| 49 |
may want to copy the script to a local bin dir with a unique name if you want |
| 50 |
to have multiple configurations. One or more rrsync options can be specified |
| 51 |
prior to the \fIDIR\fP if you want to further restrict the transfer. |
| 52 |
.P |
| 53 |
To use an rsync daemon setup, edit the user's \fB~/.ssh/authorized_keys\fP file and |
| 54 |
add a prefix like one of the following (followed by a space) in front of each |
| 55 |
ssh-key line that should be restricted: |
| 56 |
.RS 4 |
| 57 |
.P |
| 58 |
.nf |
| 59 |
command="rsync --server --daemon ." |
| 60 |
command="rsync --server --daemon --config=/PATH/TO/rsyncd.conf ." |
| 61 |
.fi |
| 62 |
.RE |
| 63 |
.P |
| 64 |
Then, ensure that the rsyncd.conf file is created with one or more module names |
| 65 |
with the appropriate path and option restrictions. If rsync's |
| 66 |
\fB\-\-config\fP option is omitted, it defaults to \fB~/rsyncd.conf\fP. |
| 67 |
See the \fBrsyncd.conf\fP(5) manpage for details of how to |
| 68 |
configure an rsync daemon. |
| 69 |
.P |
| 70 |
When using rrsync, there can be just one restricted dir per authorized key. A |
| 71 |
daemon setup, on the other hand, allows multiple module names inside the config |
| 72 |
file, each one with its own path setting. |
| 73 |
.P |
| 74 |
The remainder of this manpage is dedicated to using the rrsync script. |
| 75 |
.P |
| 76 |
.SH "OPTIONS" |
| 77 |
.P |
| 78 |
.IP "\fB\-ro\fP" |
| 79 |
Allow only reading from the DIR. Implies \fB\-no-del\fP and |
| 80 |
\fB\-no-lock\fP. |
| 81 |
.IP "\fB\-wo\fP" |
| 82 |
Allow only writing to the DIR. |
| 83 |
.IP "\fB\-munge\fP" |
| 84 |
Enable rsync's \fB\-\-munge\-links\fP on the server side. |
| 85 |
.IP "\fB\-no-del\fP" |
| 86 |
Disable rsync's \fB\-\-delete*\fP and \fB\-\-remove*\fP options. |
| 87 |
.IP "\fB\-no-lock\fP" |
| 88 |
Avoid the single-run (per-user) lock check. Useful with \fB\-munge\fP. |
| 89 |
.IP "\fB\-no-overwrite\fP" |
| 90 |
Enforce \fB\-\-ignore\-existing\fP on the server. Prevents overwriting existing |
| 91 |
files when the server is the receiver. |
| 92 |
.IP "\fB\-help\fP, \fB\-h\fP" |
| 93 |
Output this help message and exit. |
| 94 |
.P |
| 95 |
.SH "SECURITY RESTRICTIONS" |
| 96 |
.P |
| 97 |
The rrsync script validates the path arguments it is sent to try to restrict |
| 98 |
them to staying within the specified DIR. |
| 99 |
.P |
| 100 |
The rrsync script rejects rsync's \fB\-\-copy\-links\fP option (by |
| 101 |
default) so that a copy cannot dereference a symlink within the DIR to get to a |
| 102 |
file outside the DIR. |
| 103 |
.P |
| 104 |
The rrsync script rejects rsync's \fB\-\-protect\-args\fP (\fB\-s\fP) option |
| 105 |
because it would allow options to be sent to the server-side that the script |
| 106 |
cannot check. If you want to support \fB\-\-protect\-args\fP, use a daemon-over-ssh |
| 107 |
setup. |
| 108 |
.P |
| 109 |
The rrsync script accepts just a subset of rsync's options that the real rsync |
| 110 |
uses when running the server command. A few extra convenience options are also |
| 111 |
included to help it to interact with BackupPC and accept some convenient user |
| 112 |
overrides. |
| 113 |
.P |
| 114 |
The script (or a copy of it) can be manually edited if you want it to customize |
| 115 |
the option handling. |
| 116 |
.P |
| 117 |
.SH "BASH SECURITY ISSUE" |
| 118 |
.P |
| 119 |
If your users have bash set as their home shell, bash may try to be overly |
| 120 |
helpful and ensure that the user's login bashrc files are run prior to |
| 121 |
executing the forced command. This can be a problem if the user can somehow |
| 122 |
update their home bashrc files, perhaps via the restricted copy, a shared home |
| 123 |
directory, or something similar. |
| 124 |
.P |
| 125 |
One simple way to avoid the issue is to switch the user to a simpler shell, |
| 126 |
such as dash. When choosing the new home shell, make sure that you're not |
| 127 |
choosing bash in disguise, as it is unclear if it avoids the security issue. |
| 128 |
.P |
| 129 |
Another potential fix is to ensure that the user's home directory is not a |
| 130 |
shared mount and that they have no means of copying files outside of their |
| 131 |
restricted directories. This may require you to force the enabling of symlink |
| 132 |
munging on the server side. |
| 133 |
.P |
| 134 |
A future version of openssh may have a change to the handling of forced |
| 135 |
commands that allows it to avoid using the user's home shell. |
| 136 |
.P |
| 137 |
.SH "EXAMPLES" |
| 138 |
.P |
| 139 |
The \fB~/.ssh/authorized_keys\fP file might have lines in it like this: |
| 140 |
.RS 4 |
| 141 |
.P |
| 142 |
.nf |
| 143 |
command="rrsync client/logs" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAzG... |
| 144 |
command="rrsync -ro results" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAmk... |
| 145 |
.fi |
| 146 |
.RE |
| 147 |
.P |
| 148 |
.SH "FILES" |
| 149 |
.P |
| 150 |
~/.ssh/authorized_keys |
| 151 |
.P |
| 152 |
.SH "SEE ALSO" |
| 153 |
.P |
| 154 |
\fBrsync\fP(1), \fBrsyncd.conf\fP(5) |
| 155 |
.P |
| 156 |
.SH "VERSION" |
| 157 |
.P |
| 158 |
This manpage is current for version 3.4.3 of rsync. |
| 159 |
.P |
| 160 |
.SH "CREDITS" |
| 161 |
.P |
| 162 |
rsync is distributed under the GNU General Public License. See the file |
| 163 |
COPYING for details. |
| 164 |
.P |
| 165 |
An rsync web site is available at |
| 166 |
.UR https://rsync.samba.org/ |
| 167 |
.UE |
| 168 |
and its github |
| 169 |
project is |
| 170 |
.UR https://github.com/RsyncProject/rsync |
| 171 |
.UE . |
| 172 |
.P |
| 173 |
.SH "AUTHOR" |
| 174 |
.P |
| 175 |
The original rrsync perl script was written by Joe Smith. Many people have |
| 176 |
later contributed to it. The python version was created by Wayne Davison. |