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