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

Scratchbox Remote Shell is an rsh/ssh-like utility for Linux that supports
terminal emulation, automated mounting of network shares, chroot, etc.  Please
note that sbrsh is extremely insecure--do not use it on an untrusted network or
on multi-user systems!

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


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

Execute a remote command:
    sbrsh [-t|--target <target>]
          [-c|--config <path>]
          [-d|--directory <dir>]
          [-r|--remote <uid>,<gid>,<username>]
          [<command> [<arguments>]]

Mount or unmount all filesystems of a target:
    sbrsh [-t|--target <target>]
          [-c|--config <path>]
          --mount|--umount

  --target      symbolic name of the target configuration; the first target
                in the config file will be used by default
  --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 "/")
  --remote      specify the identity of the user on the target side
                (usually pair this with, e.g., sshfs 'idmap=user,uid=<uid>,
                gid=<gid>' mountopts); this allows you to avoid making
                matching accounts on both the host and target

  command       name of the binary to be executed (may be looked up from
                PATH); if command is not specified, the SHELL environment
                variable is used; if SHELL is not set, "/bin/sh" is used
  arguments     zero or more arguments for the command


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

    sbrshd [-p|--port <port>]
           [-l|--local-only]
           [-n|--no-sandbox]
           [-r|--allow-root]
           [-d|--debug <path>]
           [-V|--debug-verbose]
           [-e|--mount-expiration <minutes>|none]
           [-m|--mount-bin <path>]
           [-u|--umount-bin <path>]
           [-t|--mount-tab <path>]
           [-b|--bind-opt <options>]

  --port        sets a custom port number (default is 1202)
  --local-only  makes sbrshd only accept connections from the local host
  --no-sandbox  does not create a sandbox directory, create mounts or chroot
  --allow-root  allow commands to be run with user and group id 0
  --debug       enables debugging to a log file
  --debug-verbose  enables debugging of stdin/stdout/select polling
  --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
  --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)

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 layout of the first line:
  <target> <ip>[:<port>]

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

See "sbrsh.conf" for examples.


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

The daemon configuration file is /etc/sbrshd.conf. It lists all client IP
addresses that are granted access. The "*" wildcard can be used at the end of
an IP address. "#" is a line end comment character.

Here's an example configuration:

172.16.6.10
172.16.6.*
192.168.*


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

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

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

  SBOX_RLIMIT_CPU       CPU time in seconds
  SBOX_RLIMIT_FSIZE     max filesize
  SBOX_RLIMIT_DATA      max data size
  SBOX_RLIMIT_STACK     max stack size
  SBOX_RLIMIT_CORE      max core file size
  SBOX_RLIMIT_RSS       max resident set size
  SBOX_RLIMIT_NPROC     max number of processes
  SBOX_RLIMIT_NOFILE    max number of open files
  SBOX_RLIMIT_MEMLOCK   max locked-in-memory address space
  SBOX_RLIMIT_AS        address space (virtual memory) limit

