Isolate: Document --box-id and installation

[eval.git] / isolate / isolate.1.txt

diff --git a/isolate/isolate.1.txt b/isolate/isolate.1.txt
index f5ffaef4f3d3ef76c6433e518ef3a1f2da139e53..b3252de92d3e032a3c39e4b15f41a438f12b526b 100644 (file)
--- a/isolate/isolate.1.txt
+++ b/isolate/isolate.1.txt
@@ -67,10 +67,19 @@ OPTIONS
        is reported, even though it slightly exceeds the limit. Fractional
        numbers are again allowed.
 
        is reported, even though it slightly exceeds the limit. Fractional
        numbers are again allowed.
 

+*-b, --box-id=*'id'::
+       When you run multiple sandboxes in parallel, you have to assign each unique
+       IDs to them by this option. See the discussion on UIDs in the INSTALLATION
+       section. The ID defaults to 0.
+

 *-k, --stack=*'size'::
        Limit process stack to 'size' kilobytes. By default, the whole address
        space is available for the stack, but it is subject to the *--mem* limit.
 
 *-k, --stack=*'size'::
        Limit process stack to 'size' kilobytes. By default, the whole address
        space is available for the stack, but it is subject to the *--mem* limit.
 

+*-q, --quota=*'blocks'*,*'inodes'::
+       Set disk quota to a given number of blocks and inodes. This requires the
+       filesystem to be mounted with support for quotas.
+

 *-i, --stdin=*'file'::
        Redirect standard input from 'file'. The 'file' has to be accessible
        inside the sandbox.
 *-i, --stdin=*'file'::
        Redirect standard input from 'file'. The 'file' has to be accessible
        inside the sandbox.


@@ -83,10 +92,11 @@ OPTIONS
        Redirect standard error output to 'file'. The 'file' has to be accessible
        inside the sandbox.
 
        Redirect standard error output to 'file'. The 'file' has to be accessible
        inside the sandbox.
 

-*-p, --processes=*'max'::
+*-p, --processes*[*=*'max']::

        Permit the program to create up to 'max' processes and/or threads. Please
        keep in mind that time and memory limit do not work with multiple processes
        Permit the program to create up to 'max' processes and/or threads. Please
        keep in mind that time and memory limit do not work with multiple processes

-       unless you enable the control group mode.
+       unless you enable the control group mode. If 'max' is not given, an arbitrary
+       number of processes can be run.

 
 *-v, --verbose*::
        Tell the sandbox manager to be verbose and report on what is going on.
 
 *-v, --verbose*::
        Tell the sandbox manager to be verbose and report on what is going on.


@@ -154,10 +164,13 @@ and mounts the proc filesystem at +/proc+.
 
 CONTROL GROUPS
 --------------
 
 CONTROL GROUPS
 --------------

-TODO
+Isolate can make use of system control groups provided by the kernel
+to constrain programs consisting of multiple processes. Please note
+that this feature needs special system setup described in the REQUIREMENTS
+section.

 
 *-c, --cg*::
 
 *-c, --cg*::

-       TODO
+       Enable use of control groups.

 
 *--cg-mem=*'size'::
        Limit total memory usage by the whole control group to 'size' kilobytes.
 
 *--cg-mem=*'size'::
        Limit total memory usage by the whole control group to 'size' kilobytes.


@@ -168,12 +181,70 @@ TODO
 
 META-FILES
 ----------
 
 META-FILES
 ----------

-TODO
+The meta-file contains miscellaneous meta-information on execution of the
+program within the sandbox. It is a textual file consisting of lines
+of format 'key'*:*'value'. The following keys are defined:
+
+*cg-mem*::
+       When control groups are enabled, this is the total memory use
+       by the whole control group (in kilobytes).
+*csw-forced*::
+       Number of context switches forced by the kernel.
+*csw-voluntary*::
+       Number of context switches caused by the process giving up the CPU
+       voluntarily.
+*exitcode*::
+       The program has exited normally with this exit code.
+*exitsig*::
+       The program has exited after receiving this fatal signal.
+*killed*::
+       Present when the program was terminated by the sandbox
+       (e.g., because it has exceeded the time limit).
+*max-rss*::
+       Maximum resident set size of the process (in kilobytes).
+*message*::
+       Status message, not intended for machine processing.
+       E.g., "Time limit exceeded."
+*status*::
+       Two-letter status code:
+       * *RE* -- run-time error, i.e., exited with a non-zero exit code
+       * *SG* -- program died on a signal
+       * *TO* -- timed out
+       * *XX* -- internal error of the sandbox
+*time*::
+       Run time of the program in fractional seconds.
+*time-wall*::
+       Wall clock time of the program in fractional seconds.

 
 RETURN VALUE
 ------------
 
 RETURN VALUE
 ------------

-TODO
+When the program inside the sandbox finishes correctly, the sandbox returns 0.
+If it finishes incorrectly, it returns 1.
+All other return codes signal an internal error.

 
 

-REQUIREMENTS
+INSTALLATION

 ------------
 ------------

-TODO
+Isolate depends on several advanced features of the Linux kernel. Please
+make sure that your kernel supports
+PID namespaces (+CONFIG_PID_NS+),
+IPC namespaces (+CONFIG_IPC_NS+), and
+network namespaces (+CONFIG_NET_IS+).
+If you want to use control groups, you need
+the cpusets (+CONFIG_CPUSETS+),
+CPU accounting controller (+CONFIG_CGROUP_CPUACCT+), and
+memory resource controller (+CONFIG_CGROUP_MEM_RES_CTLR+).
+
+Isolate is designed to run setuid to root. The sub-process inside the sandbox
+then switches to a non-privileged user ID (different for each *--box-id*).
+The range of UIDs available and several filesystem paths are embedded in the
+isolate's binary during compilation; please see +default.cfg+ in the source
+tree for description.
+
+Before you run isolate with control groups, you have to mount the control group
+filesystem by doing "+mount -t cgroup none -o cpuset,cpuacct,memory /sys/fs/cgroup+".
+
+LICENSE
+-------
+Isolate was written by Martin Mares and Bernard Blackham.
+It can be distributed and used under the terms of the GNU
+General Public License version 2.