Explicitly state what the downsides to sandboxing are.
PiperOrigin-RevId: 467160648
Change-Id: I62464908770c24c945befb6eabed4d6e880397be
diff --git a/site/en/docs/sandboxing.md b/site/en/docs/sandboxing.md
index eb53d4d..4b5839b 100644
--- a/site/en/docs/sandboxing.md
+++ b/site/en/docs/sandboxing.md
@@ -6,7 +6,7 @@
This article covers sandboxing in Bazel, installing `sandboxfs`, and debugging
your sandboxing environment.
-_Sandboxing_ is a permission restricting strategy that isolates processes from
+*Sandboxing* is a permission restricting strategy that isolates processes from
each other or from resources in a system. For Bazel, this means restricting file
system access.
@@ -95,6 +95,26 @@
strategies that Bazel tries to use (for example, `bazel build
--spawn_strategy=worker,linux-sandbox`).
+Dynamic execution usually requires sandboxing for local execution. To opt out,
+pass the `--experimental_local_lockfree_output` flag. Dynamic execution silently
+sandboxes [persistent workers](/persistent-workers.html).
+
+## Downsides to sandboxing {:#sandboxing_downsides}
+
+- Sandboxing incurs extra setup and teardown cost. How big this cost is
+ depends on many factors, including the shape of the build and the
+ performance of the host OS. For Linux, sandboxed builds are rarely more than
+ a few percent slower. Setting `--experimental_reuse_sandbox_directories` can
+ mitigate the setup and teardown cost.
+
+- Sandboxing effectively disables any cache the tool may have. You can
+ mitigate this by using [persistent workers](/persistent-workers.html), at
+ the cost of weaker sandbox guarantees.
+
+- [Multiplex workers](/multiplex-worker.html) require explicit worker support
+ to be sandboxed. Workers that do not support multiplex sandboxing run as
+ singleplex workers under dynamic execution, which can cost extra memory.
+
## sandboxfs {:#sandboxfs}
`sandboxfs` is a FUSE file system that exposes an arbitrary view of the
@@ -115,20 +135,21 @@
**Run `sandboxfs`**
-1. (macOS-only) [Install OSXFUSE](https://osxfuse.github.io/){: .external}.
-2. (macOS-only) Run:
+1. (macOS-only) [Install OSXFUSE](https://osxfuse.github.io/){: .external}.
+2. (macOS-only) Run:
- ```posix-terminal
- sudo sysctl -w vfs.generic.osxfuse.tunables.allow_other=1
- ```
- You will need to do this after installation and after every reboot to ensure
- core macOS system services work through sandboxfs.
+ ```posix-terminal
+ sudo sysctl -w vfs.generic.osxfuse.tunables.allow_other=1
+ ```
-3. Run a Bazel build with `--experimental_use_sandboxfs`.
+ You will need to do this after installation and after every reboot to ensure
+ core macOS system services work through sandboxfs.
- ```posix-terminal
- bazel build {{ '<var>' }}target{{ '</var>' }} --experimental_use_sandboxfs
- ```
+3. Run a Bazel build with `--experimental_use_sandboxfs`.
+
+ ```posix-terminal
+ bazel build {{ '<var>' }}target{{ '</var>' }} --experimental_use_sandboxfs
+ ```
**Troubleshooting**
@@ -143,23 +164,22 @@
### Deactivated namespaces {:#deactivated-namespaces}
-On some platforms, such as [Google Kubernetes
-Engine](https://cloud.google.com/kubernetes-engine/){: .external} cluster nodes
-or Debian, user namespaces are deactivated by default due to security
-concerns. If the `/proc/sys/kernel/unprivileged_userns_clone` file exists and
-contains a 0, you can activate user namespaces by running:
+On some platforms, such as
+[Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/){: .external}
+cluster nodes or Debian, user namespaces are deactivated by default due to
+security concerns. If the `/proc/sys/kernel/unprivileged_userns_clone` file
+exists and contains a 0, you can activate user namespaces by running:
- ```posix-terminal
+```posix-terminal
sudo sysctl kernel.unprivileged_userns_clone=1
- ```
+```
### Rule execution failures {:#rule-failures}
-The sandbox may fail to execute rules because of the system setup.
-If you see a message like `namespace-sandbox.c:633: execvp(argv[0], argv): No
-such file or directory`, try to deactivate the sandbox with
-`--strategy=Genrule=local` for genrules, and `--spawn_strategy=local`
-for other rules.
+The sandbox may fail to execute rules because of the system setup. If you see a
+message like `namespace-sandbox.c:633: execvp(argv[0], argv): No such file or
+directory`, try to deactivate the sandbox with `--strategy=Genrule=local` for
+genrules, and `--spawn_strategy=local` for other rules.
### Detailed debugging for build failures {:#debugging-build-failures}
