Add documentation on sandbox option

2 files changed, 53 insertions, 0 deletions

diff --git a/doc/source/format.rst b/doc/source/format.rst
index 693ab75a6..36467f994 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -50,6 +50,12 @@ Here is a rather complete example using the autotools element kind and git sourc
        integration-commands:
        - /usr/bin/update-fancy-feature-cache
 
+   # Specify a user id and group id to use in the build sandbox.
+   sandbox:
+     build-uid: 0
+     build-gid: 0
+
+
 For most use cases you would not need to specify this much detail, we've provided
 details here in order to have a more complete initial example.
 
@@ -152,6 +158,8 @@ declared and overridden in the :ref:`projectconf`
 See `Using Variables`_ below for a more in depth discussion on variables in BuildStream.
 
 
+.. _format_environment:
+
 Environment
 ~~~~~~~~~~~
 
@@ -215,6 +223,33 @@ may specify additional domains to be understood and processed by their own eleme
 plugins.
 
 
+.. _format_sandbox:
+
+Sandbox
+~~~~~~~
+Configuration for the build sandbox (other than :ref:`environment variables <format_environment>`)
+can be placed in the ``sandbox`` configuration. At present, only the
+UID and GID used by the user in the group can be specified.
+
+.. code:: yaml
+
+   # Specify a user id and group id to use in the build sandbox.
+   sandbox:
+     build-uid: 1003
+     build-gid: 1001
+
+BuildStream normally uses uid 0 and gid 0 (root) to perform all
+builds. However, the behaviour of certain tools depends on user id,
+behaving differently when run as non-root. To support those builds,
+you can supply a different uid or gid for the sandbox. Only
+bwrap-style sandboxes support custom user IDs at the moment, and hence
+this will only work on Linux host platforms.
+
+.. note::
+
+   The ``sandbox`` configuration is available since :ref:`format version 6 <project_format_version>`
+
+
 .. _format_dependencies:
 
 Dependencies
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst
index 248f140ab..8ee939590 100644
--- a/doc/source/projectconf.rst
+++ b/doc/source/projectconf.rst
@@ -144,6 +144,24 @@ URLs which are to be used in the individual ``.bst`` files.
      bar: http://bar.com/downloads/
 
 
+Sandbox options
+~~~~~~~~~~~~~~~
+Sandbox options for the whole project can be supplied in
+``project.conf`` in the same way as in an element. See :ref:`element configuration <format_sandbox>`
+for more detail.
+
+.. code:: yaml
+
+   # Specify a user id and group id to use in the build sandbox.
+   sandbox:
+     build-uid: 1003
+     build-gid: 1001
+
+.. note::
+
+   The ``sandbox`` configuration is available since :ref:`format version 6 <project_format_version>`
+
+
 .. _project_essentials_artifacts:
 
 Artifact Server