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