support/rrsync.1.md

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