Debian Codegraph @

upstream/debian-unstable/man1/rrsync.1

raw
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.