* Overview

This document describes the default GNU rush setup on Debian systems.  It
is not intended as a replacement for rush documentation, which is
available as info document by running

   info rush

(provided that the info package is also installed), or online from

   https://www.gnu.org.ua/software/rush/manual.html

A condensed version of the documentation is available in form of a
manual page rush(8).

* Introduction

The default Debian setup for GNU rush assumes that it operates in
a chroot area located under /srv/rush, and provides the following
services:

** Read-write access to user home directories.

These are located under /srv/rush/home.  Users are allowed to access
them via scp, sftp or rsync, for both reading and writing.

** Download areas

These are located in /srv/rush/srv/incoming/{alpha,ftp}.  Users are
allowed only to upload files there using scp, sftp or rsync, at their option.

** Version control system repositories

Three VCS are supported: git, svn and cvs.  The top-level directories for
hosting the corresponding repositories are:

  - /srv/rush/srv/gitroot
  - /srv/rush/srv/svnroot
  - /srv/rush/srv/cvsroot

* Initial setup

The script /usr/share/doc/rush/scripts/mkchroot can be used to create and
setup a chroot file system.  A configuration script for doing so resides
in the same directory.  You will only need to specify login names of the
system users to import from the system user database.  These are users that
will be able to access services provided by rush.  They are supposed to
have "/usr/sbin/rush" as their shell in the host system "/etc/passwd" file.
You can either add their login names in the "Users" stanza of mkchroot.conf
file, or supply them as a comma-separated list with the "--users" option
when invoking mkchroot, e.g.:

  cd /usr/share/doc/rush/scripts/
  ./mkchroot --users smith,coon,mbr ./mkchroot.conf

This will create /srv/rush populate it with the directories and files necessary
for normal rush operation.

The mkchroot script is extensively documented.  Run

  mkchroot --help

to access its documentation.

* Home directory access

Once set up, each user can access their home directory using sftp, scp, or
rsync commands.  For example:

   rsync login@hostname:

to obtain the home directory listing

   rsync -a login@hostname:subdir .

to copy the directory "subdir" from it to the local disk, etc.

* Upload locations

To create the upload directories, do:

  mkdir /srv/rush/incoming/ftp /srv/rush/incoming/alpha
  chown :GROUP /srv/rush/incoming/ftp /srv/rush/incoming/alpha
  chmod g+w /srv/rush/incoming/ftp /srv/rush/incoming/alpha

where GROUP is the group to which a user must belong in order to be able to
upload files to these locations.  The group must be imported to the chrooted
filesystem upon its creation, by specifying it in --groups command line option
to mkchroot, or by adding it to the Groups stanza of its configuration file.

To upload files to one of the upload locations, the following commands
can be used:

  scp FILE login@hostname:/incoming/ftp
  rsync -a FILE login@hostname:/incoming/ftp/FILE

or

  $ sftp login@hostname
  sftp> cd /incoming/ftp
  sftp> put FILE

The actual use of these locations is beyond the scope of this document.
Supposedly, the files will be made accessible for download from another
locations by some other means.

* VCS directories

The VCS top-level directories should be create manually after the chrooted
filesystem has been set up.  Particular repositories for each VCS type
can then be created by users remotely, using the corresponding VCS commands,
if the access permissions of the top-level directory allow such usage.
Otherwise, system administrator can create the repositories as needed and
grant access to them as necessary.
