
General Information
===================

Scratchbox Remote Shell is an rsh/ssh-like utility for Linux that supports
terminal emulation, automated mounting of network shares, chroot, etc.

sbrsh is distributed under the General Public License version 2. See COPYING
for the full license.


Client Usage
============

Executing remote command:
  sbrsh <target> [-c|--config <path>] [-d|--directory <dir>]
                 [<command> [<args>]]

Unmounting all filesystems of a TARGET (see Client Config):
  sbrsh <target> [-c|--config <path>]
                 --umount-all

  --config      specifies the absolute path to the user's configuration file
                (default is "$HOME/.sbrsh")
  --directory   the user's current directory at the target device
                (default is "/")

  target        symbolic name of the target configuration; must be specified
                before any options (see Client Config)
  command       name of the command to be executed (may be looked up from
                PATH); if command is not specified, the user's login shell at
                the remote host is executed
  args          zero or more command line arguments for the command


Daemon Usage
============

  sbrshd [-p|--port <port>] [-d|--debug <path>] [-m|--mount-bin <path>]
         [-u|--umount-bin <path>] [-t|--mount-tab <path>]
         [-b|--bind-opt <options>] [-e|--mount-expiration <minutes>|none]
         [-s|--shells <path>] [-S|--shell-list <paths>]

  --port        sets a custom port number (default is 1202)
  --debug       enables debugging to a log file
  --mount-bin   specifies the mount binary path (default is "/bin/mount")
  --umount-bin  specifies the umount binary path (default is "/bin/umount")
  --mount-tab   specifies the mount table path (default is "/etc/mtab")
  --bind-opt    specifies the option used when binding a path to a mount point
                (default is "--bind", or "-obind" if mount binary is Busybox)
  --mount-expiration
                specifies the number of minutes to wait before expiring unused
                mount points (default is 15); 0 means that filesystems are
                unmounted immediately after commands exit; "none" means that
                filesystems are unmounted only when sbrshd exits
  --shells      specifies the path to a file that lists all valid login shells
                (default is "/etc/shells")
  --shell-list  specifies a colon-separated list of valid login shells;
                "/etc/shells" is not read if this is specified

--shells and --shell-list shouldn't be defined at the same time.

The pid of the daemon process is printed to stdout. The command exits
immediately.

The debug log can be opened and closed at run-time by sending the daemon
process the SIGUSR1 (open log) and SIGUSR2 (close log) signals. If the
debug log was not opened at startup with the --debug option, the debug log
will be written to "/tmp/sbrshd-<port>.log" (where <port> is the value of the
--port option).


Client Config
=============

The client configuration file lists all known TARGETs (see Client Usage).
The first line of a TARGET block must not contain whitespaces before the
name of the TARGET. The subsequent lines must be indented. # is a line end
comment character. The root path of the command is $HOME/IPADDR-TARGET.

The layout of the first line:
  <target> [<username>@]<ip>[:<port>] <password>

The subsequent lines define the mounts needed by the TARGET (TYPE is either
"nfs" or "bind"):
  <type> <share/path> <point> [<nfs options>]

Here's an example configuration:

ARM  john@172.16.6.76  killr0y
  nfs   1.2.3.4:/playground  /      rw,nolock,noac
  bind  /dev                 /dev
  bind  /proc                /proc
  bind  /var/tmp             /tmp


Daemon Config
=============

The daemon configuration file lists all known client IPs and passwords. Each
user has her own .sbrshd file in her home directory. # is a line end comment
character.

The layout is:
  <ip> <password>


Environment Variables
=====================

The command execution environment at the target device can be controlled via
a few environment variables.

"SBOX_ENV_" prefix will be stripped from all variables having one. If a
corresponding variable without the prefix exists, it will be overridden.
If the variable's value is "(UNSET)", the corresponding variable will be
removed from environment. For example the dynamic linker can be controlled
this way (via the LD_* variables) without affecting the sbrsh client itself.

The resource limits can be set using variables with the "SBRSH_RLIMIT_"
prefix. The value can be either an integer or "unlimited". The supported
setting are:

  SBRSH_RLIMIT_CPU      CPU time in seconds
  SBRSH_RLIMIT_FSIZE    max filesize
  SBRSH_RLIMIT_DATA     max data size
  SBRSH_RLIMIT_STACK    max stack size
  SBRSH_RLIMIT_CORE     max core file size
  SBRSH_RLIMIT_RSS      max resident set size
  SBRSH_RLIMIT_NPROC    max number of processes
  SBRSH_RLIMIT_NOFILE   max number of open files
  SBRSH_RLIMIT_MEMLOCK  max locked-in-memory address space
  SBRSH_RLIMIT_AS       address space (virtual memory) limit

