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] DIR
   9 ```
  10
  11 # DESCRIPTION
  12
  13 A user's ssh login can be restricted to only allow the running of an rsync
  14 transfer in one of two easy ways: forcing the running of the rrsync script
  15 or forcing the running of an rsync daemon-over-ssh command.
  16
  17 To use the rrsync script, add a prefix like one of the following (followed by a
  18 space) in front of each ssh-key line in the user's `~/.ssh/authorized_keys`
  19 file that should be restricted:
  20
  21 > ```
  22 > command="rrsync DIR"
  23 > command="rrsync -ro DIR"
  24 > command="rrsync -munge -no-del DIR"
  25 > ```
  26
  27 Then, ensure that the rrsync script has your desired option restrictions. You
  28 may want to copy the script to a local bin dir with a unique name if you want
  29 to have multiple configurations. One or more rrsync options can be specified
  30 prior to the `DIR` if you want to further restrict the transfer.
  31
  32 To use an rsync daemon setup, add one of the following prefixes (followed by a
  33 space) in front of each ssh-key line in the user's `~/.ssh/authorized_keys`
  34 file that should be restricted:
  35
  36 > ```
  37 > command="rsync --server --daemon ."
  38 > command="rsync --server --daemon --config=/PATH/TO/rsyncd.conf ."
  39 > ```
  40
  41 Then, ensure that the rsyncd.conf file is created with one or more module names
  42 with the appropriate path and option restrictions.  If the `--config` option is
  43 omitted, it defaults to `~/rsyncd.conf`.  See the `rsyncd.conf` man page for
  44 details of how to configure an rsync daemon.
  45
  46 The remainder of this man page is dedicated to using the rrsync script.
  47
  48 # OPTION SUMMARY
  49
  50 ```
  51 -ro        Allow only reading from the DIR. Implies -no-del.
  52 -wo        Allow only writing to the DIR.
  53 -no-del    Disable rsync's --delete* and --remove* options.
  54 -munge     Enable rsync's --munge-links on the server side.
  55 -help, -h  Output this help message and exit.
  56 ```
  57
  58 A single non-option argument specifies the restricted DIR to use. It can be
  59 relative to the user's home directory or an absolute path.
  60
  61 # SECURITY RESTRICTIONS
  62
  63 The rrsync script validates the path arguments it is sent to try to restrict
  64 them to staying within the specified DIR.
  65
  66 The rrsync script rejects rsync's `--copy-links`` option (by default) so that a
  67 copy cannot dereference a symlink within the DIR to get to a file outside the
  68 DIR.
  69
  70 The rrsync script rejects rsync's `--protect-args` (`-s`) option because it
  71 would allow options to be sent to the server-side that the script could not
  72 check.  If you want to support `--protect-args`, use a daemon-over-ssh setup.
  73
  74 The rrsync script accepts just a subset of rsync's options that the real rsync
  75 uses when running the server command.  A few extra convenience options are also
  76 included to help it to interact with BackupPC and accept some convenient user
  77 overrides.
  78
  79 The script (or a copy of it) can be manually edited if you want it to customize
  80 the option handling.
  81
  82 # EXAMPLES
  83
  84 The `.ssh/authorized_keys` file might have lines in it like this:
  85
  86 > ```
  87 > command="rrsync client/logs" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAzG...
  88 > command="rrsync -ro results" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAmk...
  89 > ```