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.
  90
  91 *-v, --verbose*::
  92         Tell the sandbox manager to be verbose and report on what is going on.
  93         Using *-v* multiple times produces even more jabber.
  94
  95 ENVIRONMENT RULES
  96 -----------------
  97 UNIX processes normally inherit all environment variables from their parent. The
  98 sandbox however passes only those variables which are explicitly requested by
  99 environment rules:
 100
 101 *-E, --env=*'var'::
 102         Inherit the variable 'var' from the parent.
 103
 104 *-E, --env=*'var'*=*'value'::
 105         Set the variable 'var' to 'value'. When the 'value' is empty, the
 106         variable is removed from the environment.
 107
 108 *-e, --full-env*::
 109         Inherit all variables from the parent.
 110
 111 The rules are applied in the order in which they were given, except for
 112 *--full-env*, which is applied first.
 113
 114 The list of rules is automatically initialized with *-ELIBC_FATAL_STDERR_=1*.
 115
 116 DIRECTORY RULES
 117 ---------------
 118 The sandboxed process gets its own filesystem namespace, which contains only subtrees
 119 requested by directory rules:
 120
 121 *-d, --dir=*'in'*=*'out'[*:*'options']::
 122         Bind the directory 'out' as seen by the caller to the path 'in' inside the sandbox.
 123         If there already was a directory rule for 'out', it is replaced.
 124
 125 *-d, --dir=*'dir'[*:*'options']::
 126         Bind the directory +/+'dir' to 'dir' inside the sandbox.
 127         If there already was a directory rule for 'out', it is replaced.
 128
 129 *-d, --dir=*'in'*=*::
 130         Remove a directory rule for the path 'in' inside the sandbox.
 131
 132 By default, all directories are bound read-only and restricted (no devices,
 133 no setuid binaries). This behavior can be modified using the 'options':
 134
 135 *rw*::
 136         Allow read-write access.
 137
 138 *dev*::
 139         Allow access to character and block devices.
 140
 141 *noexec*::
 142         Disallow execution of binaries.
 143
 144 *maybe*::
 145         Silently ignore the rule if the directory to be bound does not exist.
 146
 147 *fs*::
 148         Instead of binding a directory, mount a device-less filesystem called 'in'.
 149         For example, this can be 'proc' or 'sysfs'.
 150
 151 The default set of directory rules binds +/bin+, +/dev+ (with devices allowed), +/lib+,
 152 +/lib64+ (if it exists), and +/usr+. It also binds the working directory to +/box+ (read-write)
 153 and mounts the proc filesystem at +/proc+.
 154
 155 CONTROL GROUPS
 156 --------------
 157 TODO
 158
 159 *-c, --cg*::
 160         TODO
 161
 162 *--cg-mem=*'size'::
 163         Limit total memory usage by the whole control group to 'size' kilobytes.
 164
 165 *--cg-timing*::
 166         Use control groups for timing, so that the *--time* switch affects the
 167         total run time of all processes and threads in the control group.
 168
 169 META-FILES
 170 ----------
 171 TODO
 172
 173 RETURN VALUE
 174 ------------
 175 TODO
 176
 177 REQUIREMENTS
 178 ------------
 179 TODO