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 *-i, --stdin=*'file'::
  75         Redirect standard input from 'file'. The 'file' has to be accessible
  76         inside the sandbox.
  77
  78 *-o, --stdout=*'file'::
  79         Redirect standard output to 'file'. The 'file' has to be accessible
  80         inside the sandbox.
  81
  82 *-r, --stderr=*'file'::
  83         Redirect standard error output to 'file'. The 'file' has to be accessible
  84         inside the sandbox.
  85
  86 *-p, --processes*[*=*'max']::
  87         Permit the program to create up to 'max' processes and/or threads. Please
  88         keep in mind that time and memory limit do not work with multiple processes
  89         unless you enable the control group mode. If 'max' is not given, an arbitrary
  90         number of processes can be run.
  91
  92 *-v, --verbose*::
  93         Tell the sandbox manager to be verbose and report on what is going on.
  94         Using *-v* multiple times produces even more jabber.
  95
  96 ENVIRONMENT RULES
  97 -----------------
  98 UNIX processes normally inherit all environment variables from their parent. The
  99 sandbox however passes only those variables which are explicitly requested by
 100 environment rules:
 101
 102 *-E, --env=*'var'::
 103         Inherit the variable 'var' from the parent.
 104
 105 *-E, --env=*'var'*=*'value'::
 106         Set the variable 'var' to 'value'. When the 'value' is empty, the
 107         variable is removed from the environment.
 108
 109 *-e, --full-env*::
 110         Inherit all variables from the parent.
 111
 112 The rules are applied in the order in which they were given, except for
 113 *--full-env*, which is applied first.
 114
 115 The list of rules is automatically initialized with *-ELIBC_FATAL_STDERR_=1*.
 116
 117 DIRECTORY RULES
 118 ---------------
 119 The sandboxed process gets its own filesystem namespace, which contains only subtrees
 120 requested by directory rules:
 121
 122 *-d, --dir=*'in'*=*'out'[*:*'options']::
 123         Bind the directory 'out' as seen by the caller to the path 'in' inside the sandbox.
 124         If there already was a directory rule for 'out', it is replaced.
 125
 126 *-d, --dir=*'dir'[*:*'options']::
 127         Bind the directory +/+'dir' to 'dir' inside the sandbox.
 128         If there already was a directory rule for 'out', it is replaced.
 129
 130 *-d, --dir=*'in'*=*::
 131         Remove a directory rule for the path 'in' inside the sandbox.
 132
 133 By default, all directories are bound read-only and restricted (no devices,
 134 no setuid binaries). This behavior can be modified using the 'options':
 135
 136 *rw*::
 137         Allow read-write access.
 138
 139 *dev*::
 140         Allow access to character and block devices.
 141
 142 *noexec*::
 143         Disallow execution of binaries.
 144
 145 *maybe*::
 146         Silently ignore the rule if the directory to be bound does not exist.
 147
 148 *fs*::
 149         Instead of binding a directory, mount a device-less filesystem called 'in'.
 150         For example, this can be 'proc' or 'sysfs'.
 151
 152 The default set of directory rules binds +/bin+, +/dev+ (with devices allowed), +/lib+,
 153 +/lib64+ (if it exists), and +/usr+. It also binds the working directory to +/box+ (read-write)
 154 and mounts the proc filesystem at +/proc+.
 155
 156 CONTROL GROUPS
 157 --------------
 158 Isolate can make use of system control groups provided by the kernel
 159 to constrain programs consisting of multiple processes. Please note
 160 that this feature needs special system setup described in the REQUIREMENTS
 161 section.
 162
 163 *-c, --cg*::
 164         Enable use of control groups.
 165
 166 *--cg-mem=*'size'::
 167         Limit total memory usage by the whole control group to 'size' kilobytes.
 168
 169 *--cg-timing*::
 170         Use control groups for timing, so that the *--time* switch affects the
 171         total run time of all processes and threads in the control group.
 172
 173 META-FILES
 174 ----------
 175 The meta-file contains miscellaneous meta-information on execution of the
 176 program within the sandbox. It is a textual file consisting of lines
 177 of format 'key'*:*'value'. The following keys are defined:
 178
 179 *cg-mem*::
 180         When control groups are enabled, this is the total memory use
 181         by the whole control group (in kilobytes).
 182 *csw-forced*::
 183         Number of context switches forced by the kernel.
 184 *csw-voluntary*::
 185         Number of context switches caused by the process giving up the CPU
 186         voluntarily.
 187 *exitcode*::
 188         The program has exited normally with this exit code.
 189 *exitsig*::
 190         The program has exited after receiving this fatal signal.
 191 *killed*::
 192         Present when the program was terminated by the sandbox
 193         (e.g., because it has exceeded the time limit).
 194 *max-rss*::
 195         Maximum resident set size of the process (in kilobytes).
 196 *message*::
 197         Status message, not intended for machine processing.
 198         E.g., "Time limit exceeded."
 199 *status*::
 200         Two-letter status code:
 201         * *RE* -- run-time error, i.e., exited with a non-zero exit code
 202         * *SG* -- program died on a signal
 203         * *TO* -- timed out
 204         * *XX* -- internal error of the sandbox
 205 *time*::
 206         Run time of the program in fractional seconds.
 207 *time-wall*::
 208         Wall clock time of the program in fractional seconds.
 209
 210 RETURN VALUE
 211 ------------
 212 When the program inside the sandbox finishes correctly, the sandbox returns 0.
 213 If it finishes incorrectly, it returns 1.
 214 All other return codes signal an internal error.
 215
 216 REQUIREMENTS
 217 ------------
 218 Isolate depends on several advanced features of the Linux kernel. Please
 219 make sure that your kernel supports
 220 PID namespaces (+CONFIG_PID_NS+),
 221 IPC namespaces (+CONFIG_IPC_NS+), and
 222 network namespaces (+CONFIG_NET_IS+).
 223 If you want to use control groups, you need
 224 the cpusets (+CONFIG_CPUSETS+),
 225 CPU accounting controller (+CONFIG_CGROUP_CPUACCT+), and
 226 memory resource controller (+CONFIG_CGROUP_MEM_RES_CTLR+).
 227
 228 LICENSE
 229 -------
 230 Isolate was written by Martin Mares and Bernard Blackham.
 231 It can be distributed and used under the terms of the GNU
 232 General Public License version 2.