/usr/share/doc/sbox-dtc/README.html

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>sbox: Put CGI Scripts in a Box</title>
<link rel="stylesheet" href="http://stein.cshl.org/stylesheets/default.css">
</head>

<body bgcolor="#FFFFFF">
<!--NAVBAR-->

<hr>
    
<h1><em>sbox</em>: Put CGI Scripts in a Box</h1>

<h2>Abstract</h2>

<p>

<i>sbox</i> is a CGI wrapper script that allows Web site hosting
services to safely grant CGI authoring privileges to untrusted
clients.  In addition to changing the process privileges of client
scripts to match their owners, it goes beyond other wrappers by
placing configurable ceilings on script resource usage, avoiding
unintentional (as well as intentional) denial of service attacks.  It
also optionally allows the Webmaster to place client's CGI scripts in
a chroot'ed shell restricted to the author's home directories.

<p>

<i>sbox</i> is compatible with all Web servers running under
BSD-derived flavors of Unix.  You can use and redistribute it freely.

<p>

<strong>The current release is 1.10</strong>. Download it from the Web
at <a
href="http://stein.cshl.org/WWW/software/sbox/sbox.tar.gz">http://stein.cshl.org/WWW/software/sbox/</a>.
<p>

<a href="http://stein.cshl.org/WWW/software/sbox/old/">Older versions</a>
are also available.

<h2>Introduction</h2>

<p>

Poorly-written CGI scripts are the single major source of server
security holes on the World Wide Web.  Every CGI script should be
scrutinized and extensively tested before installing it on a server,
and subject to periodic review thereafter.

<p>

For Web hosting services, however, this advice is impractical.
Hosting services must sponsor multiple Web authors of different levels
of competence and reliability.  Web authors do not trust each other,
and the Web hosting service does not trust the authors.  In such a
situation, CGI scripts are even more problematic than usual.  Because
all CGI scripts run under the Web server's user ID, one author's
scripts can interfere with another's.  For example a malicious author
could create a script that deletes files created by another author's
script, or even cause another author's script to crash by sending it a
kill signal.  A poorly written script that contains a security hole
can compromise the entire site's security by, for example,
transmitting the contents of the system password file to a malicious
remote user.  The same problems are faced by large academic sites
which provide Web pages for students.

<p>

For most Web hosting services it would be impossible to subject each
and every author's CGI scripts to code review.  Nor is it practical to
cut off CGI scripting privileges entirely.  In the competitive world
of ISP's, customers will just move elsewhere.

<p>

The most popular solution to this problem is the use of "wrapper"
scripts.  In this system, untrusted author's CGI scripts are never
invoked directly.  Instead a small wrapper script is called on to
execute the author's script, the <cite>target</cite>.  The wrapper is
SUID to root.  When the wrapper runs, it subjects the target to
certain safety checks (for example, checking that the script is not
world-writable).  The wrapper then changes its process ID to match the
owner of the target and executes it.  The result is that the author's
script is executed with his own identity and privileges, preventing it
from interfering with other author's scripts.  The system also leads
to increased accountability.  Any files that an misbehaving script
creates or modifies will bear the fingerprints of its creator.
Without a wrapper, it can be impossible to determine which author's
script is causing problems.

<p>

The limitations of wrapper scripts are three-fold:

<ol>
  <li>Wrappers provide little protection against attacks that involve
      reading confidential information on the site, for example
      sensitive system files or protected documents.
  <li>Wrappers expose the author to increased risk from buggy
      scripts.  By running the author's script with his owner
      permissions, the wrapper grants it the ability to read, write or
      delete any file in the author's home directory.
  <li>There is no protection against denial-of-service attacks.  A
      buggy script can go into an endless loop, write a huge file into
      /usr/tmp, or allocate an array as large as virtual memory,
      adversely affecting system responsiveness.
</ol>

A better solution is to <strong>box</strong> author's CGI scripts.  In
this solution, the CGI script is executed in a restricted environment
in which its access to the file system and to other system resources
is limited.  This is what <cite>sbox</cite> (Secure Box) accomplishes.
When run, it does several things:

<ol>
  <li>It checks the environment for sanity.  For example, the script
      must be run by the Web user and group, and not by anyone else.
  <li>It checks the target script for vulnerabilities, such as being
      world writable or being located in a world writable directory.
  <li>It performs a chroot to a directory that contains both the script and
	the author's HTML files, sealing the script off from the rest
	of the system.
  <li>It changes its user ID and/or group ID to that of the target
      script.
  <li>It sets ceilings on the target script's CPU, disk, memory and
      process usage.
  <li>It lowers the priority of its process.
  <li>It cleanses the environment so that only variables which are
      part of the CGI protocol are available to the script.
  <li>It invokes the target script in this restricted context.
</ol>
<p>

<cite>sbox</cite> is highly configurable.  It can be configured to
chroot without changing its process ID, to change its process ID
without performing the chroot, to change its group ID without changing
its user ID, to establish resource ceilings without doing anything
else, or any other combination that suits you.

<h2>System Requirements</h2>

<p>

<cite>sbox</cite> is designed to run with any Unix-based Web server.
The package should compile correctly on any standard Unix system;
however the resource limits use the BSD-specific <i>setrlimit()</i>
and <i>setpriority()</i> calls.  If you do not know whether your
system supports these calls, check for the existence of the file
<i>/usr/include/system/resource.h</i>.  If this file does not exist,
then chances are slim that you can use the resource limits.  You can
run <i>sbox</i> without the limits by setting the preprocessor define
<i>SET_LIMITS</i> to FALSE (see below).

<hr>

<h2>Installation</h2>

<p>

After unpacking the package, you should have the following files:

<pre>
Makefile
README.html (this file)
README.txt  (this file as text)
sbox.h
sbox.c
env.c
</pre>

You will first examine and edit the Makefile, then change sbox.h to
suit your site configuration and preferences.  It is suggested that
you keep copies of the unaltered files for future reference.

<hr>

<h3>Adjusting the Makefile</h3>

<p>

Using your favorite text editor, examine and change the value of the
INSTALL_DIRECTORY variable.  This is the location in which
<cite>sbox</cite> will be installed, and should correspond to your
site-wide CGI directory.

<p>

You may also need to fiddle with the options for the
<cite>install</cite> program.  The default is to make
<cite>sbox</cite> owned by user "root" and group "bin", and installed
with permissions <tt>-rws--x--x</tt>.  This configuration is SUID to
root, necessary in order for the chroot and process ID changing
functions to work.

<p>

If you wish to adjust the C compiler and its flags, change the CC and
CFLAGS variables as needed.

<hr>

<h3>Adjusting sbox.h</h3>

<p>
This is the fun part.  <cite>sbox.h</cite> contains several dozen
flags that affect the script's features.  These flags are implemented
as compile-time defines rather than as run-time configuration
variables for security reasons.  There is less chance that the
behavior of <cite>sbox</cite> can be maliciously altered if it has no
dependences on external configuration files. </p>

<p>
You should review <cite>sbox.h</cite> with a text editor and change
the settings as needed.  A typical entry looks like this:</p>

<blockquote><pre>
/*
 * ECHO_FAILURES  -- If set to TRUE, will echo fatal error messages
 *              to the browser.  Set to FALSE to inhibit error messages.
 */
#ifndef ECHO_FAILURES
#define ECHO_FAILURES TRUE
#endif
</pre></blockquote>

<p>
This section sets a feature called ECHO_FAILURES to TRUE.  To change
the value to FALSE, simply edit the line that begins with "#define" to 
read like this:

<blockquote><pre>
#define ECHO_FAILURES FALSE
</pre></blockquote>

<h4>General Settings</h4>

<p>

These variables correspond to general <cite>sbox</cite> settings such
as logging and environment consistency checking.

<dl>
  <dt>WEB_USER (default "nobody")
  <dd>This defines the name of the user that the Web server runs
      under, "nobody" by default.  If your Web server uses a different
      user ID, you must change this define to match.
      <p>
  <dt>WEB_GROUP (default "nobody")
  <dd>This defines the name of the group that the Web server runs
      under, "nobody" by default.  If your Web server uses a different
      group ID, you must change this define to match.
      <p>
  <dt>UID_MIN, GID_MIN (defaults 100,100)
  <dd>These define the lowest UID and GID that the script will run a
      target CGI script as.  On most systems, low-numbered user and group
      IDs correspond to users with special privileges.  Change these
      values to be the lowest valid unprivileged user and group ID.
      Under no circumstances will <cite>sbox</cite> run a target
      script as root (UID 0.)
      <p>
  <dt>SAFE_PATH (default "/bin:/usr/bin:/usr/local/bin")
  <dd>This defines the search path that will be passed to the author's
      CGI scripts, overriding whatever was there before.
      <p>
  <dt>USE_ABSOLUTE_ROOT (no default)
  <dd>If set to an absolute path, sbox will chroot to a hard-coded
      directory and use that as its root.  Use this if you want to
      have sbox work on a particular directory not related to a user's
      directory or the web root.
  <dd>NOTE: the sbox binary you compile will work for that directory ONLY.
      If you want to use it for another directory, recompile and use a
      different binary
</dl>

<h4>Logging Settings</h4>
<p>

<cite>sbox</cite> can be set to log all its actions, including both
failures and successful launches of author's scripts.  Log entries are
time stamped and labeled with the numeric IDs of the user and group
that the target script was launched under.

<dl>
  <dt>LOG_FILE (default none)
  <dd>This specifies a file to which <cite>sbox</cite> will log its
      successes and failures.  Set this to the full path name of the
      file to log to.  An empty string ("") will make
      <cite>sbox</cite> log to standard error, which will cause its
      log messages to be directed to the ordinary server error log.
      Leaving LOG_FILE undefined will cause <cite>sbox</cite> not to
      log any messages.
      <p>
  <dt>ECHO_FAILURES (default TRUE)
  <dd>If this define is set to a true value, any fatal errors
      encountered during <cite>sbox's</cite> execution will be turned
      into a properly-formatted HTML message that is displayed for the
      remote user's benefit.  Otherwise, the standard "An Internal
      Error occurred" message is displayed.
</dl>

<h4>Chroot Settings</h4>

<p>

These variables controls <cite>sbox's</cite> chroot functionality.
The path names are relative to the document root.  In the case of
virtual hosts, this will be whatever is specified by the DocumentRoot
directive in the server's configuration file.  In the case of
user-supported directories, it will be the user's public_html
directory.

<dl>
  <dt>DO_CHROOT (default TRUE)
  <dd>If set to a true value, <cite>sbox</cite> will perform a chroot
      to a restricted directory prior to executing the CGI script.  
	Otherwise no chroot will be performed.
      <p>
  <dt>ROOT (default "<tt>..</tt>")
  <dd>This tells <cite>sbox</cite> where to chroot to relative to the 
	document root.  This directory should ordinarily be a level or
	two above the document tree so that the script can get access to the
	author's HTML documents for processing.
      <p>
  <dt>CGI_BIN (default "<tt>../cgi-bin</tt>")
  <dd>This define tells sbox where to look for the author's scripts
	directory, relative to his site's document tree.  This
	directory should be contained within the directory specified 
	by ROOT.  For best security, you should specify a directory
	that is outside the document tree.  The default is a directory
	named "cgi-bin" located at the same level as the document root.
</dl>

<h4>SUID/SGID Settings</h4>

<p>

<dl>
  <dt>DO_SUID, DO_SGID (defaults TRUE, TRUE)
  <dd>These defines control whether the script will perform an SUID
      and/or an SGID to the user and group of the target CGI script.
      From the author's point of view it's safer to perform an SGID 
      than an SUID, and usually is more than adequate.  If no SUID or SGID
      is performed, the author's script will be run with the Web server's
      privileges.
      <p>
  <dt>SID_MODE (default DIRECTORY)
  <dd>This define controls whether <cite>sbox</cite>
      should use the ownership of the target script or the
      <em>directory</em> containing the target script to determine
      whose user ID and/or group ID to run under.  Use directory mode
      if several users have authoring privileges for a single virtual
      host.
</dl>

<h4>Resource Limitation Settings</h4>
<p>

<dl>
  <dt>SET_LIMITS (default TRUE)
  <dd>If set to a true value, <cite>sbox</cite> will set
      resource usage ceilings before running the target CGI script.
      You may need to set this to FALSE if you are using a system that
      does not implement the setpriority() and/or setrlimit() calls.
      <p>
  <dt>PRIORITY (default 10)
  <dd>This controls the priority with which target scripts are run.
      Values can range from -20 to 20.  Higher numbers have
      <strong>less</strong> priority.
      <p>
  <dt>LIMIT_CPU_HARD, LIMIT_CPU_SOFT, LIMIT_FSIZE_HARD, LIMIT_FSIZE_SOFT...
  <dd>These and similar defines control the resource ceilings.
      The definitions set caps on CPU usage, the number of processes
      the script can spawn, the amount of memory it can use,
      the size of the largest file it can create, and other
      attributes.  For each resource there are two caps, one
      hard, the other soft.  Soft resources can be increased by any
      program that desires to do so by making the appropriate calls to
      setrlimit().  Hard limits are inviolable ceilings that cannot be
      lifted once established, even by a privileged user.  The
      hard limits should be rather liberal, the soft limits more
      strict.  See the setrlimit() man page for details on each of
      these resources.
            <p>
            If you use LIMIT_FSIZE_HARD or _SOFT and are logging to stderr,
            be careful!  If your web server error log is larger than the
            limit, no logging will occur.
      
</dl>

<hr>

<h3>Making and Installing the Binary</h3>

<p>

Compile the sbox binary by typing <strong>make</strong>.  If it
compiles successfully, become root and type <strong>make
install</strong> to install it in your site's cgi-bin directory (at
the location specified in the Makefile.)

<p>

You can also install <cite>sbox</cite> manually by copying it into
your cgi-bin directory and settings its permissions to
<tt>---s--x--x</tt>.  This can be done with the following commands
while logged in as the root user:

<blockquote><pre>
# chown root sbox
# chgrp bin  sbox
# chmod 4111 sbox
</pre></blockquote>

<hr>

<h3>Configuring the Server and User Directories</h3>
<p>

In order for <cite>sbox</cite> to be effective, CGI scripts should be
turned off in all user-supported directories and document directories.
All CGI scripts should be placed in the main cgi-bin directory.  No
one but authorized site administrators should have write or listing
privileges for this directory.  If you are using the Apache server, a
typical entry for a virtual host will look like this:

<blockquote>
<pre>
&lt;VirtualHost *&gt;
ServerName www.fred.com
ServerAdmin  fred@fred.com

DocumentRoot /home/fred/sbox_root/html
TransferLog  /home/fred/sbox_root/logs/access_log
ErrorLog     /home/fred/sbox_root/logs/error_log

&lt;Directory /home/fred/sbox_root&gt;
    Options        MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
    AllowOverride Options AuthConfig Limit
    order allow,deny
    allow from all
&lt;/Directory&gt;

&lt;/VirtualHost&gt;
</pre>
</blockquote>

<p><em>(Please be sure to use Options and AllowOverride directives
that match the security policy of your site.)</em> <p>

<p> For a site that uses UserDir-style home pages
(http://www.your.site/~username), a typical configuration is:</p>


<blockquote><pre>
UserDir sbox_root/html

&lt;Directory /home/*/sbox_root&gt;
    Options       MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
    AllowOverride Options AuthConfig Limit
    order allow,deny
    allow from all
&lt;/Directory&gt;
</pre></blockquote>


<p>

Note that in both cases, the user's document root (where his HTML
files go) is "~fred/sbox_root/html", that is, two directory levels
below his home directory.  When <cite>sbox</cite> runs, it uses the
position of the user's document root to find its root and the cgi-bin
directory. The suggested defaults defined in sbox.h make the ROOT
equal to "..", and CGI_BIN equal to "../cgi-bin", both relative to the
document root. Hence in the examples given above, sbox's root will be
~fred/sbox_root, and sbox will look for his CGI scripts in the
directory ~fred/sbox_root/cgi-bin. When sbox runs in chroot mode,
~fred/sbox_root becomes the new top level ("/") directory, insulating
the user's CGI script from the rest of his home directory, as well as
the rest of the file system. This prevents the CGI script from
inadvertently (or deliberately) doing something antisocial, but gives
the script access to the user's HTML files, for filtering and
templating.

<p>

Because the user's CGI script is cut off from the rest of the
filesystem after the chroot call, dynamically linked programs
(including interpreters and the like) will not be happy unless they
can find the shared libraries they rely on.  Therefore, the sbox root
directory should be set up like a miniature root directory, and
contain whatever binaries, configuration files and shared libraries
are necessary for programs to run.  This list is different from system
to system.  See <a href="#miniroot">Using the Miniroot</a> and <a
href="#tips">Tips</a> for advice on setting this directory up.

<p>

Below is the structure of Fred's directory, assuming that the virtual
host uses ~fred/sbox_root/html as its document root.

<pre>
<b>% ls -l ~fred/sbox_root</b>
total 10
drwxr-xr-x   2 fred   users  1024 Oct 23 06:27 bin/     <i>system binaries</i>
drwxr-xr-x   3 fred   users  1024 Oct 19 20:44 cgi-bin/ <i>CGI scripts</i>
drwxr-xr-x   2 fred   users  1024 Oct 12 16:59 dev/     <i>device special files</i>
drwxr-xr-x   2 fred   users  1024 Oct 19 17:57 etc/     <i>configuration files</i>
drwxr-xr-x   2 fred   users  1024 Oct 22 19:14 html/    <i>HTML document root</i>
drwxr-xr-x   3 fred   users  1024 Oct 19 20:35 lib/     <i>shared libraries</i>
drwxr-xr-x   3 fred   users  1024 Oct 19 20:35 logs/    <i>log files</i>
drwxr-xr-x   2 fred   users  1024 Oct 23 05:48 tmp/     <i>temporary files</i>
drwxr-xr-x   2 fred   users  1024 Oct 23 05:48 usr/     <i>files that belong in usr</i>
drwxr-xr-x   2 fred   users  1024 Oct 23 05:48 var/     <i>files that belong in var</i>
</pre>

<p>

If you do not take advantage of <cite>sbox's</cite> chroot feature,
but just use it for its ability to change to the user's UID and GID,
then you do not have to do any special directory setup.

<p>

See <a href="#htaccess">Supporting Apache .htaccess files</a> and <a
href="#rewrite">Rewrite-Rule Tricks</a> for additional common
configuration setups that make sbox more transparent to use.


<hr>

<h3>Calling <cite>sbox</cite></h3>

<p>

To use <cite>sbox</cite> create URLs like this one:

<blockquote>
<pre>
http://www.virtual.host.com/cgi-bin/sbox/script_name
       ^^^^^^^^^^^^^^^^^^^^              ^^^^^^^^^^^
        virtual host name               user's script
</pre>
</blockquote>

<p>

The first part of the URL is the path to the <cite>sbox</cite>
script.  The second part is the path to the user's script, relative
to the cgi-bin directory in his home directory.  If the user's
script needs access to additional path information, you can append it
in the natural way:

<blockquote>
<i>
http://www.virtual.host.com/cgi-bin/sbox/script_name/additional/path/info
</i>
</blockquote>

<p>

For user-supported directories, use this format:

<blockquote>
<i>
http://www.virtual.host.com/cgi-bin/sbox/~fred/script_name
</i>
</blockquote>

<p>

Users are free to organize their script directories into a hierarchy.
They need only modify script URLs to reflect the correct path:

<blockquote>
<i>
http://www.virtual.host.com/cgi-bin/sbox/foo/bar/script_name
</i>
</blockquote>

<hr>

<h3><a name="htaccess">Supporting Apache .htaccess files</a></h3>

<p>

If you are using the Apache web server and wish the user to be able to
password-protect or otherwise modify access to his cgi-bin directory
using a .htaccess file, then you will need to activate and use
Apache's mod_rewrite module. Otherwise any .htaccess file located in
the user's cgi-bin directory will be ignored. This method will also
make it so that if the requested executable is not found in the
cgi-bin directory, the error condition will fall through to Apache's
error handling system (using ErrorDocument) rather than raising an
sbox error.</p>

<p>First make sure that Apache was compiled with the mod_rewrite
module and that the module is loaded at startup time. The relevant
directive is:</p>

<pre>
LoadModule rewrite_module lib/apache/mod_rewrite.so
</pre>

<p>Now assuming that user cgi-bin directories are installed in
~user/sbox_root/cgi-bin, that the sbox executable is installed in
/cgi-bin/sbox, and that user directories are located at
/home/username, enter the following into your httpd.conf file:</p>

<h4>For Virtual Hosts</h4>

<blockquote><pre>
RewriteEngine on
RewriteLog "/var/log/apache/rewrite_log"
RewriteLogLevel 0

RewriteCond %{REQUEST_FILENAME} ^/cgi-bin/sbox/(.+)
RewriteCond %{DOCUMENT_ROOT}/../cgi-bin/%1 !-F
RewriteRule ^/cgi-bin/sbox/(.+) %{DOCUMENT_ROOT}/../cgi-bin/$1  [L]
RewriteRule ^(/cgi-bin/sbox/.+) $1 [PT,NS]
</pre></blockquote>

(This goes into each VirtualHost section)

<h4>For User Directories</h4>

<blockquote><pre>
RewriteEngine on
RewriteLog "/var/log/apache/rewrite_log"
RewriteLogLevel 0

RewriteCond %{REQUEST_FILENAME} ^/cgi-bin/sbox/~([^/]+)/(.+)
RewriteCond /home/%1/sbox_root/cgi-bin/%2 !-F
RewriteRule ^/cgi-bin/sbox/~([^/]+)/(.+) /home/$1/sbox_root/cgi-bin/$2  [L]
RewriteRule ^(/cgi-bin/sbox/~.+/.+) $1 [PT,NS]
</pre></blockquote>

<p>(This goes into the main section of httpd.conf)</p>


<p> These pretty complicated looking pieces of code says that for URLs
that begin with /cgi-bin/sbox/~username/filename, first check whether
the file /home/username/sbox_root/cgi-bin/filename exists and is
available via Apache's access rules. If it isn't available, then
rewrite the URL as /home/username/sbox_root/cgi-bin/filename and
perform the usual processing as if it were a file (which will result
in a 403 or 404 error). Otherwise, don't rewrite the URL and pass it
through to the CGI handler. You will need to tweak these a bit if
users' home directories are somewhere else than /home/user or if you
have changed the names or positions of the sbox root and cgi-bin
directories from their defaults.</p>

<p> To support users' ability to change access rights using .htaccess,
make sure to enable AuthConfig and Limit in sbox_root if you haven't
done so already: </p>

<blockquote><pre>
&lt;Directory /home/*/sbox_root&gt;
    AllowOverride +Options +AuthConfig +Limit
&lt;/Directory&gt;
</pre></blockquote>

<hr>


<h3><a name="miniroot">Using the Miniroot (Linux only)</a></h3>

<p>

For the convenience of Linux system administrators wishing to use the
chroot features of sbox, I have placed a miniature root directory at
<a
href="http://stein.cshl.org/software/sbox/miniroot.img.gz">stein.cshl.org/software/sbox/miniroot.img.gz</a>.
This is a gzipped ext2 filesystem image that contains essential system
device files, shared libraries, and executables, including Perl
version 5.8.7 and the most commonly used Perl libraries. The
filesystem image is based on the one distributed with <a
href="http://www.oss.cc.gatech.edu/pub/linux/system/recovery">RIP</a>.

<p>

You can use this image in several ways:

<h4>Install a copy of the image into each user's directory:</h4>

<p>

This way gives each user a skeleton root directory that he is free to
modify, providing him with considerable flexibility. The downside is
that you may not wish users to have so much flexibility; it also takes
up about 45 megabytes of space per user directory:

<ol>
  <li>Download the miniroot from <a
href="http://stein.cshl.org/software/sbox/miniroot.img.gz">stein.cshl.org/software/sbox/miniroot.img.gz</a>.
  <li>Unzip it:
      <pre>
      gunzip miniroot.img.gz
      </pre>
  <li>Mount the resulting disk image in loopback mode (you must be root to do this):
      <pre>
      mkdir /mnt/miniroot
      mount ./miniroot.img /mnt/miniroot -o ro,loop
      </pre>
  <li>Copy the contents of the miniroot into each user's sbox root
      directory (assuming in this example that it is ~fred/sbox_root):
      <pre>
      cd /mnt/miniroot
      find . | cpio -p ~fred/sbox_root
      </pre>
  <li>Create the user's html, cgi-bin and log directories:
      <pre>
      mkdir ~fred/sbox_root/{html,cgi-bin,log}
      </pre>
  <li>Fix permissions of these directories:
      <pre>
      chown fred.users ~fred/sbox_root/{html,cgi-bin,log}
      </pre>
</ol>

<h4>Mounting a copy of the miniroot in each user's directory</h4>

<p>The alternative method avoids the waste of putting a complete copy
of the root into each user's directory. One copy of the miniroot is
mounted read-only into each user's sbox root, giving them read-only
access to the mount. The main disadvantage of this strategy is that it
generates a mount for each user, which in the case of very many user
accounts might bump up against kernel limitations.</p>

<ol>
  <li>Download the miniroot from <a
href="http://stein.cshl.org/software/sbox/miniroot.img.gz">stein.cshl.org/software/sbox/miniroot.img.gz</a>.
  <li>Unzip it:
      <pre>
      gunzip miniroot.img.gz
      </pre>
  <li>Create the user's html and cgi-bin directories, as well as a directory called "mnt":
      <pre>
      mkdir ~fred/sbox_root/html
      mkdir ~fred/sbox_root/cgi-bin
      mkdir ~fred/sbox_root/mnt
      </pre>
   <li>Mount the miniroot read-only on the user's mnt/ directory:
       <pre>
       mount ./miniroot.img ~fred/sbox_root/mnt -o ro,loop
       </pre>
   <li>Create symlinks to the directories of the mounted filesystem:
       <pre>
       cd ~fred/sbox_root
       ln -s mnt/* .
       </pre>
   <li>Fix permissions of html, cgi-bin and log.
</ol>

<p>At the end of this process, you should have a directory structure that looks
like this:</p>

<blockquote><pre>
lrwxrwxrwx  1 root root     7 Dec  4 18:18 bin -> mnt/bin
drwxrwxr-x  2 fred users   96 Dec  4 18:15 cgi-bin/
lrwxrwxrwx  1 root root     7 Dec  4 18:18 dev -> mnt/dev
lrwxrwxrwx  1 root root     7 Dec  4 18:18 etc -> mnt/etc
drwxr-xr-x  5 fred users 1136 Dec  4 18:15 html/
lrwxrwxrwx  1 root root     7 Dec  4 18:18 lib -> mnt/lib
lrwxrwxrwx  1 fred users    7 Dec  4 18:15 log/
drwxrwxr-x  2 root root    48 Dec  4 18:16 mnt/
lrwxrwxrwx  1 root root     7 Dec  4 18:18 tmp -> mnt/tmp
lrwxrwxrwx  1 root root     7 Dec  4 18:18 usr -> mnt/usr
lrwxrwxrwx  1 root root     7 Dec  4 18:18 var -> mnt/var
</pre></blockquote>

<p>If you ever wish to modify the miniroot image, simply mount it
read/write and make the changes you need. If you run out of space on
the miniroot, you can create a new one with the following series of
commands:</p>

<blockquote><pre>
mount ./miniroot.img /mnt/miniroot -o ro,loop
dd if=/dev/zero of=./new_miniroot.img bs=1M count=100  # or whatever you want
mke2fs -F ./new_miniroot.img
mount ./new_miniroot.img /mnt/new_miniroot -o rw,loop
cd /mnt/miniroot
find . | cpio -p /mnt/new_miniroot
</pre></blockquote>

<p>

You are also free to burn the miniroot into a CDROM image, create a
cramfs image, etc.

<hr>

<h2><a name="tips">Tips</a></h2>

<p>

Here are a few pieces of advice and tips on making best use of
<cite>sbox</cite>.

<h3>Setting up the Chroot directory</h3>

<p>

Many CGI scripts will not run correctly in a chroot environment unless
they can find the resources they need.  Compiled C programs often need
access to shared libraries and/or device special files.  Interpreted
scripts need access to their interpreters, for example Perl.
Feature-rich programs like sendmail depend on their configuration
files being present in /etc.  

<p>

As described above, you will need to turn the chroot directory into a
miniature root file system, complete with /etc, /lib, /bin, /tmp and
/dev directories.  If the web server is running on a Linux system,
then one option is to use the <a href="#miniroot">miniroot image</a>
provided with sbox as the basis for the root file system. If you
prefer to do it yourself, I recommend that you create and test a
chroot directory for one virtual host, then use it as a master copy
for creating new virtual hosts every time you add a new user account.
Both the cpio and the tar commands can be used to copy shared
libraries and device special files safely.

<p>

Programs that check file ownerships may need access to password and/or
group files in order for them to translate from numeric uid's and
gid's to text names.  In order to support CGI scripts that perform
this type of action, you should place dummy copies of /etc/passwd and
/etc/group in the author's /etc directory.  These files <strong>should
not contain real passwords</strong>, and should only contain standard
system user accounts (e.g. "bin" and "mail"), plus any needed by the
script.  You probably don't want to make the complete list of user
account names available to authors' CGI scripts!

<p>

If CGI scripts require access to the DNS system in order to resolve
host names and IP addresses, you should place a copy of
/etc/resolv.conf into the chroot directory. You may need to copy other
configuration files to use certain feature-rich programs.  For
example, if scripts send e-mail using the sendmail program, you will
need to install its configuration program, sendmail.cf.

<p>

Many programs redirect their output to the device special file
/dev/null.  Other programs need access to /dev/zero or other special
files.  You can copy these files from the real /dev directory using
either cpio or tar.  Alternately you can create the files from scratch
using mknod, but only if you know what you're doing.  You'll need to
have superuser privileges to accomplish either of these tasks.

<p>

The Unix time system expects to find information about the local
timezone in a compiled file named <tt>/etc/localtime</tt>.  You may
need to copy this into your chroot directory in order for the timezone
to be correctly displayed.  You can confirm that the correct timezone
is being found by examining the output of the "env" executable.

<p>


There are two ways to finesse the problem of shared libraries.  For
compiled C scripts, one option is to link the program statically (by
providing the <tt>-static</tt> flag to the linker).  A less laborious
solution is to place copies of the required shared libraries in the
new root's /lib directory (or /slib, for systems that use that
directory for shared libraries).  Many systems have a utility that
lists the shared libraries required by a binary.  Use this program to
determine which shared libraries are required, and copy them over into
each author's /lib directory.  In addition to the shared libraries,
you may need to copy the dynamic linker itself into the /lib
directory.  On my linux system, this file is "ld-linux.so".

<p>

If a executable cannot find its shared libraries at run time, it will
usually fail with a specific error message that will lead you to the
problem -- look in the server error log.  If you get silent failures,
it's probably the dynamic linker itself that can't be found.

<p>

Linux, and possibly some other systems, uses a cache file named
/etc/ld.so.cache to resolve the location of library files.  If this
file isn't found at run time, the system will generate a warning but
find the correct shared libraries nevertheless.  The quick and dirty
way to get rid of this warning is to copy the current cache file from
the real /etc directory to the chroot one. However, this may have bad
side effects (I haven't actually encountered any, but I worry about
it.)  It's better to make this cache file from scratch in the chroot
environment itself.  To do this, run the ldconfig program with the
command-line version of chroot.  You'll need to be root to do this:

<blockquote>
<pre>
# cd /sbin
# chroot ~fred/pub ./ldconfig
</pre>
</blockquote>

<p>

Perl scripts, in addition to requiring the Perl interpreter, will
often need access to the Perl lib directory in order to get at useful
modules (such as <a
href="http://stein.cshl.org/WWW/software/CGI/">CGI.pm</a>).  It's
easiest to copy the whole Perl library tree to the correct location in
the chroot directory, being careful to get the path right.  For
example, if the real Perl library is located in /usr/local/lib/perl5,
you'll need to create a parallel /usr hierarchy in the chroot
directory.  On my system, I recompiled Perl to use /lib/perl5 and
dumped the modules into that directory.  If things get bolluxed up,
you can always tell Perl where to look for its libraries by appending
something like this to the top of CGI scripts:

<blockquote>
<pre>
#!/bin/perl
BEGIN { push(@INC,'/lib/perl5','/lib/perl5/i586-linux/5.004'); }
</pre>
</blockquote>

<h3>The Document Root and the chroot() directory</h3>

<p>
Some CGI scripts act as filters on static HTML documents.  Examples
include PHP and various guestbook scripts.  Such scripts often include
the path to the static document appended to the end of the script's
URL as "additional path information."  For example:
</p>

<blockquote>
   http://your.site/~fred/guestbook.cgi/~fred/guestbook/data.txt
</blockquote>

<p>
The script will be passed two environment variables, PATH_INFO,
containing the additional path information, and PATH_TRANSLATED,
containing the path information translated into an absolute filename.
In the example above, the values of these variables might be:
</p>

<p><table>
  <TR><TH ALIGN=RIGHT>PATH_INFO</TH><TD>/~fred/guestbook/data.txt</TD> </TR>
  <TR><TH ALIGN=RIGHT>PATH_TRANSLATED</TH><TD>/home/fred/public_html/guestbook/data.txt</TD> </TR>
</table></p>
    
<p>
When sbox is running it interprets the additional path information as
relative to the user's document root.  This means that a document
located in Fred's public_html directory can be referred to this way:
</P>

<blockquote>
 http://your.site/cgi-bin/sbox/~fred/guestbook.cgi/guestbook/data.txt
</blockquote>

<p>
After performing the chroot(), sbox attempts to adjust PATH_TRANSLATED
so that it continues to point to a valid file.  If the user's document
root is located within the chroot directory, then PATH_TRANSLATED is
trimmed so that it is relative to the new root directory:
</p>

<p><table>
  <TR><TH ALIGN=RIGHT>PATH_INFO</TH><TD>/guestbook/data.txt</TD> </TR>
  <TR><TH ALIGN=RIGHT>PATH_TRANSLATED</TH><TD>/public_html/guestbook/data.txt</TD> </TR>
</table>
</p>
  
<p>
However, if the document root is entirely outside the new root
directory, then sbox will simply use the same value for PATH_INFO and
PATH_TRANSLATED:
</p>

<p><table>
  <TR><TH ALIGN=RIGHT>PATH_INFO</TH><TD>/guestbook/data.txt</TD> </TR>
  <TR><TH ALIGN=RIGHT>PATH_TRANSLATED</TH><TD>/guestbook/data.txt</TD> </TR>
</table>
</p>

Users and Webmasters should be aware of this behavior, as it can cause
some confusion.

<h3>The Resource Limitations</h3>

<p>

The default resource limits are reasonable. Most authors won't have
problems with them unless they need to do number crunching or
manipulate many files simultaneously.  If need be, authors can raise
the soft resource limits up to the levels imposed by the hard limit
ceilings, which are very liberal.  C programmers can do this directly
by making calls to setrlimit().  Perl scripters should download and
install Jarkko Hietaniemi's BSD::Resource module from <a
href="http://www.perl.com/CPAN/modules/">CPAN</a>.

<h3>Server-Side Includes</h3>

<p>Because of design conflicts, the "#exec" style server-side include
do not work correctly with <cite>sbox</cite>.  However, the "#include
virtual" command, which does almost exactly the same thing, does work
correctly.  To include the output of <cite>sbox</cite>-wrapped CGI
scripts in server-side-include files, just write something like
this:</p>

<blockquote><xmp>
&lt;!--#include virtual="/cgi-bin/sbox/~fred/guestbook"--&gt;
</xmp></blockquote>

<h3><a name="rewrite">Rewrite-Rule Tricks</a></h3>

<p>

If you are running Apache 1.2 or higher, you can take advantage of the
rewrite rule module to make <cite>sbox</cite> transparent.  For
virtual hosts, you can add something like the following to main or the
&lt;VirtualHost&gt; section:

<blockquote>
<pre>
RewriteEngine on
RewriteRule ^/cgi/(.*) /cgi-bin/sbox/$1 [PT,NS]
</pre>
</blockquote>

This replaces all URLs that start with "/cgi" with "/cgi-bin/sbox".
This lets authors refer to their scripts with:

<blockquote>
<i>http://www.virtual.host.com/cgi/script_name</i>
</blockquote>

and to main Web server scripts with:

<blockquote>
<i>http://www.virtual.host.com/cgi-bin/guestbook</i>
</blockquote>

For user-supported directories, this rewrite rule will allow users to
refer to their scripts using
<i>http://www.host.com/~username/cgi/script_name</i>:

<blockquote>
<pre>
RewriteEngine on
RewriteRule ^/~([^/]+)/cgi/(.+) /cgi-bin/sbox/~$1/$2 [PT,NS]
</pre>
</blockquote>

<p>

If you are already using rewrite rules to allow users to control
access with <a href="#htaccess">a .htaccess file</a>, place the
appropriate RewriteRule before the first RewriteCond and omit the
[PT,NS] flags. The following two examples show RewriteRule blocks that
will correctly respect .htaccess files:

<h4>For Virtual Hosts</h4>

<blockquote><pre>
RewriteRule ^/cgi/(.+) /cgi-bin/sbox/$1
RewriteCond %{REQUEST_FILENAME} ^/cgi-bin/sbox/(.+)
RewriteCond %{DOCUMENT_ROOT}/../cgi-bin/%1 !-F
RewriteRule ^/cgi-bin/sbox/(.+) %{DOCUMENT_ROOT}/../cgi-bin/$1  [L]
RewriteRule ^(/cgi-bin/sbox/.+) $1 [PT,NS]
</pre></blockquote>

<h4>For User Directories</h4>
<blockquote><pre>
RewriteRule ^/~([^/]+)/cgi/(.+) /cgi-bin/sbox/~$1/$2
RewriteCond %{REQUEST_FILENAME} ^/cgi-bin/sbox/~([^/]+)/(.+)
RewriteCond /home/%1/sbox_root/cgi-bin/%2 !-F
RewriteRule ^/cgi-bin/sbox/~([^/]+)/(.+) /home/$1/sbox_root/cgi-bin/$2  [L]
RewriteRule ^(/cgi-bin/sbox/~.+/.+) $1 [PT,NS]
</pre></blockquote>


<h3>The env Script</h3>

<p>

This distribution comes with a small statically linked binary called
"env" that you can call as a CGI script.  It prints out some
information about the current environment, including the user and
group ID's, the current working directory, and the environment
variables, to help you determine whether <cite>sbox</cite> is
configured correctly and working as expected.

<hr>

<h2>Author Information</h2>

<p>

This utility is &copy;1997-2005 Lincoln D. Stein.  It can be used freely
and redistributed in source code and binary form.  I request that this
documentation, including the copyright statement, remain attached to
the utility if you redistribute it.  You are free to make
modifications, but please attach a note stating the changes you made.

<hr>
<h2>Change History</h2>

<dl>
  <dt>Version 1.10
  <dd>Revamped documentation to show how to get .htaccess and 404 Not Found errors to work correctly.
  <dd>Added an example root directory for use in chroot mode.
  <dt>Versions 1.08-1.09
  <dd>Never released.
  <dt>Version 1.07
  <dd>Patch from Jukka Forsgren to cause script to chdir() into target directory in the same
      manner as Apache does.
<p>

  <dt>Version 1.06
  <dd>Fixed cross-scripting security vulnerability identified by Ivan Schmid (ivan.schmid@astalavista.ch)
      <p>
  <dt>Version 1.05
  <dd>Lost version.
      <p>
  <dt>Version 1.04
  <dd>Changes to make sbox compile with egcs version 1.1.2
  <dd>Fixed problem of CGI scripts not being able to access command line variables
      (courtesy Sean Gabriel Heacock)
  <dd>If logfile can't be opened, logs to standard error instead.
      <p>
  <dt>Version 1.03
  <dd>Added USE_ABSOLUTE_ROOT functionality, contributed by Grant
      Kaufmann.
      <p>
  <dt>Version 1.02
  <dd>Fixed a crash that occurred when configured userid or groupid is not in
      passwd/group file (patch provided by Terry Lorrah &lt;delikon@itw.net&gt;).
      <p>  
  <dt>Version 1.01
  <dd>Fixed minor bug in webmaster's error message.
  <dd>Fixed minor bug in reporting gid to log file
      <p>
  <dt>Version 1.00
  <dd>Replaced all occurrences of strcpy() and strcat() with strncpy()
      and strncat().
  <dd>Changes to string constants to make more ANSI-compatible.
  <dd>Code cleanup
      <p>

  <dt>Versons 0.98-0.99
  <dd>Documentation fixes.
<p>
      
  <dt>Version 0.97
  <dd>     Fixed bugs relating to automounter confusion.
      <p>
  <dt>Version 0.95
  <dd>Fixes to compile and run on Solaris systems.  Still not
      extensively tested, but no bug reports yet.
  <p>
  <dt>Version 0.90
  <dd>Beta release.  Use with caution.
</dl>

<hr>

<address><a href="http://stein.cshl.org/~lstein/">Lincoln
D. Stein</a>, lstein@cshl.org<br>

<a href="http://www.cshl.org/">Cold Spring Harbor Laboratory</a></address>

<!-- hhmts start -->
Last modified: Mon Dec  5 15:58:19 EST 2005
<!-- hhmts end -->
</body> </html>
sbox-dtc 1.11.7-1+b1 / usr / share / doc / sbox-dtc / README.html
