isolate/isolate.1.txt

   1 ISOLATE(1)
   2 ==========
   3
   4 NAME
   5 ----
   6 isolate - Isolate a process using Linux Containers
   7
   8 SYNOPSIS
   9 --------
  10 *isolate* 'options' *--init*
  11
  12 *isolate* 'options' *--run* +--+ 'program' 'arguments'
  13
  14 *isolate* 'options' *--cleanup*
  15
  16 DESCRIPTION
  17 -----------
  18 Run 'program' within a sandbox, so that it cannot communicate with the
  19 outside world and its resource consumption is limited. This can be used
  20 for example in a programming contest to run untrusted programs submitted
  21 by contestants in a controlled environment.
  22
  23 The sandbox is used in the following way:
  24
  25 * Run *isolate --init*, which initializes the sandbox, creates its working directory and
  26 prints its name to the standard output.
  27
  28 * Populate the directory with the executable file of the program and its
  29 input files.
  30
  31 * Call *isolate --run* to run the program. A single line describing the
  32 status of the program is written to the standard error stream.
  33
  34 * Fetch the output of the program from the directory.
  35
  36 * Run *isolate --cleanup* to remove temporary files.
  37
  38 Please note that by default, the program is not allowed to start multiple
  39 processes of threads. If you need that, turn on the control group mode
  40 (see below).
  41
  42 OPTIONS
  43 -------
  44 *-M, --meta=*'file'::
  45         Output meta-data on the execution of the program to a given file.
  46         See below for syntax of the meta-files.
  47
  48 *-m, --mem=*'size'::
  49         Limit address space of the program to 'size' kilobytes. If more processes
  50         are allowed, this applies to each of them separately.
  51
  52 *-t, --time=*'time'::
  53         Limit run time of the program to 'time' seconds. Fractional numbers are allowed.
  54         Time in which the OS assigns the processor to different tasks is not counted.
  55
  56 *-w, --wall-time=*'time'::
  57         Limit wall-clock time to 'time' seconds. Fractional values are allowed.
  58         This clock measures the time from the start of the program to its exit,
  59         so it does not stop when the program has lost the CPU or when it is waiting
  60         for an external event. We recommend to use *--time* as the main limit,
  61         but set *--wall-time* to a much higher value as a precaution against
  62         sleeping programs.
  63
  64 *-x, --extra-time=*'time'::
  65         When a time limit is exceeded, wait for extra 'time' seconds before
  66         killing the program. This has the advantage that the real execution time
  67         is reported, even though it slightly exceeds the limit. Fractional
  68         numbers are again allowed.
  69
  70 *-k, --stack=*'size'::
  71         Limit process stack to 'size' kilobytes. By default, the whole address
  72         space is available for the stack, but it is subject to the *--mem* limit.
  73
  74 *-q, --quota=*'blocks'*,*'inodes'::
  75         Set disk quota to a given number of blocks and inodes. This requires the
  76         filesystem to be mounted with support for quotas.
  77
  78 *-i, --stdin=*'file'::
  79         Redirect standard input from 'file'. The 'file' has to be accessible
  80         inside the sandbox.
  81
  82 *-o, --stdout=*'file'::
  83         Redirect standard output to 'file'. The 'file' has to be accessible
  84         inside the sandbox.
  85
  86 *-r, --stderr=*'file'::
  87         Redirect standard error output to 'file'. The 'file' has to be accessible
  88         inside the sandbox.
  89
  90 *-p, --processes*[*=*'max']::
  91         Permit the program to create up to 'max' processes and/or threads. Please
  92         keep in mind that time and memory limit do not work with multiple processes
  93         unless you enable the control group mode. If 'max' is not given, an arbitrary
  94         number of processes can be run.
  95
  96 *-v, --verbose*::
  97         Tell the sandbox manager to be verbose and report on what is going on.
  98         Using *-v* multiple times produces even more jabber.
  99
 100 ENVIRONMENT RULES
 101 -----------------
 102 UNIX processes normally inherit all environment variables from their parent. The
 103 sandbox however passes only those variables which are explicitly requested by
 104 environment rules:
 105
 106 *-E, --env=*'var'::
 107         Inherit the variable 'var' from the parent.
 108
 109 *-E, --env=*'var'*=*'value'::
 110         Set the variable 'var' to 'value'. When the 'value' is empty, the
 111         variable is removed from the environment.
 112
 113 *-e, --full-env*::
 114         Inherit all variables from the parent.
 115
 116 The rules are applied in the order in which they were given, except for
 117 *--full-env*, which is applied first.
 118
 119 The list of rules is automatically initialized with *-ELIBC_FATAL_STDERR_=1*.
 120
 121 DIRECTORY RULES
 122 ---------------
 123 The sandboxed process gets its own filesystem namespace, which contains only subtrees
 124 requested by directory rules:
 125
 126 *-d, --dir=*'in'*=*'out'[*:*'options']::
 127         Bind the directory 'out' as seen by the caller to the path 'in' inside the sandbox.
 128         If there already was a directory rule for 'out', it is replaced.
 129
 130 *-d, --dir=*'dir'[*:*'options']::
 131         Bind the directory +/+'dir' to 'dir' inside the sandbox.
 132         If there already was a directory rule for 'out', it is replaced.
 133
 134 *-d, --dir=*'in'*=*::
 135         Remove a directory rule for the path 'in' inside the sandbox.
 136
 137 By default, all directories are bound read-only and restricted (no devices,
 138 no setuid binaries). This behavior can be modified using the 'options':
 139
 140 *rw*::
 141         Allow read-write access.
 142
 143 *dev*::
 144         Allow access to character and block devices.
 145
 146 *noexec*::
 147         Disallow execution of binaries.
 148
 149 *maybe*::
 150         Silently ignore the rule if the directory to be bound does not exist.
 151
 152 *fs*::
 153         Instead of binding a directory, mount a device-less filesystem called 'in'.
 154         For example, this can be 'proc' or 'sysfs'.
 155
 156 The default set of directory rules binds +/bin+, +/dev+ (with devices allowed), +/lib+,
 157 +/lib64+ (if it exists), and +/usr+. It also binds the working directory to +/box+ (read-write)
 158 and mounts the proc filesystem at +/proc+.
 159
 160 CONTROL GROUPS
 161 --------------
 162 Isolate can make use of system control groups provided by the kernel
 163 to constrain programs consisting of multiple processes. Please note
 164 that this feature needs special system setup described in the REQUIREMENTS
 165 section.
 166
 167 *-c, --cg*::
 168         Enable use of control groups.
 169
 170 *--cg-mem=*'size'::
 171         Limit total memory usage by the whole control group to 'size' kilobytes.
 172
 173 *--cg-timing*::
 174         Use control groups for timing, so that the *--time* switch affects the
 175         total run time of all processes and threads in the control group.
 176
 177 META-FILES
 178 ----------
 179 The meta-file contains miscellaneous meta-information on execution of the
 180 program within the sandbox. It is a textual file consisting of lines
 181 of format 'key'*:*'value'. The following keys are defined:
 182
 183 *cg-mem*::
 184         When control groups are enabled, this is the total memory use
 185         by the whole control group (in kilobytes).
 186 *csw-forced*::
 187         Number of context switches forced by the kernel.
 188 *csw-voluntary*::
 189         Number of context switches caused by the process giving up the CPU
 190         voluntarily.
 191 *exitcode*::
 192         The program has exited normally with this exit code.
 193 *exitsig*::
 194         The program has exited after receiving this fatal signal.
 195 *killed*::
 196         Present when the program was terminated by the sandbox
 197         (e.g., because it has exceeded the time limit).
 198 *max-rss*::
 199         Maximum resident set size of the process (in kilobytes).
 200 *message*::
 201         Status message, not intended for machine processing.
 202         E.g., "Time limit exceeded."
 203 *status*::
 204         Two-letter status code:
 205         * *RE* -- run-time error, i.e., exited with a non-zero exit code
 206         * *SG* -- program died on a signal
 207         * *TO* -- timed out
 208         * *XX* -- internal error of the sandbox
 209 *time*::
 210         Run time of the program in fractional seconds.
 211 *time-wall*::
 212         Wall clock time of the program in fractional seconds.
 213
 214 RETURN VALUE
 215 ------------
 216 When the program inside the sandbox finishes correctly, the sandbox returns 0.
 217 If it finishes incorrectly, it returns 1.
 218 All other return codes signal an internal error.
 219
 220 REQUIREMENTS
 221 ------------
 222 Isolate depends on several advanced features of the Linux kernel. Please
 223 make sure that your kernel supports
 224 PID namespaces (+CONFIG_PID_NS+),
 225 IPC namespaces (+CONFIG_IPC_NS+), and
 226 network namespaces (+CONFIG_NET_IS+).
 227 If you want to use control groups, you need
 228 the cpusets (+CONFIG_CPUSETS+),
 229 CPU accounting controller (+CONFIG_CGROUP_CPUACCT+), and
 230 memory resource controller (+CONFIG_CGROUP_MEM_RES_CTLR+).
 231
 232 LICENSE
 233 -------
 234 Isolate was written by Martin Mares and Bernard Blackham.
 235 It can be distributed and used under the terms of the GNU
 236 General Public License version 2.