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