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
============

Execute a remote command:
    sbrsh [-t|--target <target>]
          [-c|--config <path>]
          [-d|--directory <dir>]
          [<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 "/")

  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]
           [-i|--ident]
           [-r|--allow-root]
           [-d|--debug <path>]
           [-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
  --ident       uses identd for validating incoming connections
  --allow-root  allow commands to be run with user and group id 0
  --debug       enables debugging to a log file
  --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>]

Here's an example configuration:

ARM  172.16.6.76:1202
  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 is /etc/sbrshd.conf. It lists all client IP
addresses and user accounts that are granted access. The user account list
can be replaced with "*" to permit all users from a host. The "*" wildcard
can also be used at the end of an IP address. "#" is a line end comment
character.

The layout is:
  <ip> <username1> <username2> <...> <usernameN>

Here's an example configuration:

172.16.6.10 john bob alice
172.16.6.85 *
172.16.6.*  guest
192.168.*   *


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 "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