Sandbox - The build sandbox

Element plugins which want to interface with the sandbox need only understand this interface, while it may be given a different sandbox implementation, any sandbox implementation it is given will conform to this interface.

See also: Sandboxing.

class SandboxFlags

Bases: object

Flags indicating how the sandbox should be run.

ROOT_READ_ONLY = 1

The root filesystem is read only.

This is normally true except when running integration commands on staged dependencies, where we have to update caches and run things such as ldconfig.

NETWORK_ENABLED = 2

Whether to expose host network.

This should not be set when running builds, but can be allowed for running a shell in a sandbox.

INTERACTIVE = 4

Whether to run the sandbox interactively

This determines if the sandbox should attempt to connect the terminal through to the calling process, or detach the terminal entirely.

INHERIT_UID = 8

Whether to use the user id and group id from the host environment

This determines if processes in the sandbox should run with the same user id and group id as BuildStream itself. By default, processes run with user id and group id 0, protected by a user namespace where available.

CREATE_DEV_SHM = 16

Whether to create /dev/shm in the sandbox.

This allows plugins to create /dev/shm in the sandbox. This flag was added to fix a bug in which /dev/shm was not added in, meaning our sandbox was not POSIX compliant.

class Sandbox

Bases: object

Sandbox programming interface for Element plugins.

DEVICES = ['/dev/urandom', '/dev/random', '/dev/zero', '/dev/null']
get_directory()

Fetches the sandbox root directory

The root directory is where artifacts for the base runtime environment should be staged.

Returns:

The sandbox root directory

Return type:

(str)

set_environment(environment)

Sets the environment variables for the sandbox

Parameters:

directory (dict) – The environment variables to use in the sandbox

set_work_directory(directory)

Sets the work directory for commands run in the sandbox

Parameters:

directory (str) – An absolute path within the sandbox

mark_directory(directory, *, artifact=False)

Marks a sandbox directory and ensures it will exist

Parameters:

  • directory (str) – An absolute path within the sandbox to mark

  • artifact (bool) – Whether the content staged at this location contains artifacts

Note

Any marked directories will be read-write in the sandboxed environment, only the root directory is allowed to be readonly.

run(command, flags, *, cwd=None, env=None)

Run a command in the sandbox.

Parameters:

  • command (list) – The command to run in the sandboxed environment, as a list of strings starting with the binary to run.

  • flags (SandboxFlags) – The flags for running this command.

  • cwd (str) – The sandbox relative working directory in which to run the command.

  • env (dict) – A dictionary of string key, value pairs to set as environment variables inside the sandbox environment.

Returns:

The program exit code.

Return type:

(int)

:raises (ProgramNotFoundError): If a host tool which the given sandbox implementation requires is not found.

Note

The optional cwd argument will default to the value set with set_work_directory()