docs/linux_suid_sandbox_development.md

   1 # Linux SUID Sandbox Development
   2
   3 For context see [LinuxSUIDSandbox](linux_suid_sandbox.md)
   4
   5 We need a SUID helper binary to turn on the sandbox on Linux.
   6
   7 In most cases, you can run `build/update-linux-sandbox.sh` and it'll install
   8 the proper sandbox for you in `/usr/local/sbin` and tell you to update your
   9 `.bashrc` if needed.
  10
  11 ## Installation instructions for developers
  12
  13 *   If you have no setuid sandbox at all, you will see a message such as:
  14
  15     ```
  16     Running without the SUID sandbox!
  17     ```
  18
  19 *   If your setuid binary is out of date, you will get messages such as:
  20
  21     ```
  22     The setuid sandbox provides API version X, but you need Y
  23     You are using a wrong version of the setuid binary!
  24     ```
  25
  26 Run the script mentioned above, or do something such as:
  27
  28 *   Build `chrome_sandbox` whenever you build chrome
  29     (`ninja -C xxx chrome chrome_sandbox` instead of `ninja -C xxx chrome`)
  30 *   After building, run something similar to (or use the provided
  31     `update-linux-sandbox.sh`):
  32
  33     ```shell
  34     # needed if you build on NFS!
  35     sudo cp out/Debug/chrome_sandbox /usr/local/sbin/chrome-devel-sandbox
  36     sudo chown root:root /usr/local/sbin/chrome-devel-sandbox
  37     sudo chmod 4755 /usr/local/sbin/chrome-devel-sandbox
  38     ```
  39
  40 *   Put this line in your `~/.bashrc` (or `.zshenv` etc):
  41
  42     ```
  43     export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
  44     ```
  45
  46 ## Try bots and waterfall
  47
  48 If you're installing a new bot, always install the setuid sandbox (the
  49 instructions are different than for developers, contact the Chrome troopers). If
  50 something does need to run without the setuid sandbox, use the
  51 `--disable-setuid-sandbox` command line flag.
  52
  53 The `SUID` sandbox must be enabled on the try bots and the waterfall. If you
  54 don't use it locally, things might appear to work for you, but break on the
  55 bots.
  56
  57 (Note: as a temporary, stop gap measure, setting `CHROME_DEVEL_SANDBOX` to an
  58 empty string is equivalent to `--disable-setuid-sandbox`)
  59
  60 ## Disabling the sandbox
  61
  62 If you are certain that you don't want the setuid sandbox, use
  63 `--disable-setuid-sandbox`. There should be very few cases like this. So if
  64 you're not absolutely sure, run with the setuid sandbox.
  65
  66 ## Installation instructions for "[Raw builds of Chromium](https://commondatastorage.googleapis.com/chromium-browser-continuous/index.html)"
  67
  68 If you're using a "raw" build of Chromium, do the following:
  69
  70     sudo chown root:root chrome_sandbox && sudo chmod 4755 chrome_sandbox && \
  71         export CHROME_DEVEL_SANDBOX="$PWD/chrome_sandbox"
  72     ./chrome
  73
  74 You can also make such an installation more permanent by following the
  75 [steps above](#Installation-Instructions-for-developers) and installing
  76 `chrome_sandbox` to a more permanent location.
  77
  78 ## System-wide installations of Chromium
  79
  80 The `CHROME_DEVEL_SANDBOX` variable is intended for developers and won't work
  81 for a system-wide installation of Chromium. Package maintainers should make sure
  82 the `setuid` binary is installed and defined in GYP as `linux_sandbox_path`.