SANDBOXCTL.CONF(5)

NAME
sandboxctl.conf - configuration file format for the sandboxctl tool

DESCRIPTION
Configuration files for sandboxctl(8) are plain shell scripts that define a set of recognized variables and can optionally provide a set of hooks for the actions offered by the tool.

  Configuration variables
The following generic variables configure the sandbox:

SANDBOX_TYPE
    The name of the configuration type to use for the sandbox. There is at least one type for every supported operating system but there may be more than one.

    You can find a subsection below for each of the supported types, in which you will find all necessary details on how to use that particular type.

    Default: ‘empty’.

SANDBOX_ROOT
    Path to the sandbox to be handled by this configuration file. This variable must be set in the configuration file.

    The directory pointed at by this variable cannot exist upon sandbox creation and will be deleted when the sandbox is destroyed.

    Default: not set.

  Configuration variables for the empty sandbox type
The ‘empty’ sandbox type sets up a completely empty sandbox.

Empty sandboxes are not useful in practice, but this type comes in handy to define custom sandbox types. To define a custom sandbox, you can use this type and then define pre/post hooks for the various stages of the sandbox construction.

  Configuration variables for the netbsd-native sandbox type
The ‘netbsd-native’ sandbox type sets up a NetBSD sandbox on a NetBSD host and replicates the host system under the sandbox using null mounts. Sandboxes created using this type mimic the host system and are fast to create and destroy.

The following variables configure this type:

NETBSD_NATIVE_RELEASEDIR
    Path to the directory containing the release that matches the host system. The distribution sets are expected to live within a binary/sets/ subdirectory of the given path.

    Even though this sandbox type uses the native host system as a reference for the setup of the sandbox, these sets are needed to unpack fresh configuration and support files that cannot be inherited from the host.

    Default: /home/sysbuild/release/$(uname -m)

  Configuration variables for the netbsd-release sandbox type
The ‘netbsd-release’ sandbox type sets up a NetBSD sandbox on a NetBSD host using release sets. Sandboxes created in this manner are "clean" in the sense that they reproduce a freshly installed system and are completely decoupled from the host system. If the kernel contains the correct backwards-compatibility options (the default), you can even use release sets for different NetBSD versions to create a sandbox for older operating system versions.

The following variables configure this type:

NETBSD_RELEASE_RELEASEDIR
    Path to the directory containing the release to be unpacked inside the sandbox. The distribution sets are expected to live within a binary/sets/ subdirectory of the given path.

    Default: /home/sysbuild/release/$(uname -m)

NETBSD_RELEASE_SETS
    Basename of the sets to unpack inside the sandbox, without their extension.

    If this variable is unset, sandboxctl(8) will automatically determine the sets to extract based on the contents of the NETBSD_RELEASE_RELEASEDIR directory. In particular, all available userland sets will be extracted. As for the kernel, ‘kern-GENERIC’ will be preferred over any other kernel set but, if not present, the first kernel set in lexicographical order will be used.

    A reasonable setting to set up a barebones sandbox would be to list ‘base etc kern-GENERIC’ in this variable.

    Default: not set.

  Hooks
Hooks are user-provided routines invoked at particular points of the sandbox manipulation. These are defined as shell functions and have direct access to the configuration variables in the file. Hooks must return a success error code and they cannot contain unprotected shell commands.

The following hooks can be defined:

post_create_hook()
    Function executed after creating the sandbox.

pre_destroy_hook()
    Function executed before starting to destroy the sandbox.

post_mount_hook()
    Function executed after finishing to mount filesystems within the sandbox.

pre_unmount_hook()
    Function executed before starting to unmount filesystems within the sandbox.

  Helper functions
Hooks have access to the following helper functions:

sandbox_bindfs [-o ro|rw] source mount_point
    Remounts the host directory source within the sandbox in then mount_point directory using a bindfs-like file system. The specific file system used to perform this operation depends on the underlying operating system. The ro and rw arguments to the -o option specify whether to mount the directory in read-only mode (the default) or in read-write mode.

    Note that mount_point is an absolute path, so you must prefix it with ‘${SANDBOX_ROOT}’ to point to the correct location within the sandbox.

    This function is typically used in post_mount_hook(). There is no need to manually unmount the file systems in the pre_unmount_hook(); the unmount happens automatically.

sandbox_extract tar_file dir [file1 .. fileN]
    Extracts the compressed tarball given in tar_file into the dir directory. If specified, file1 .. fileN indicate the subset of files to extract from the tarball.

    Note that dir is an absolute path, so you must prefix it with ‘${SANDBOX_ROOT}’ to point to the correct location within the sandbox.

    This function is typicall used in post_create_hook(). There is no need to manually remove the extracted files; the removal happens automatically.

SEE ALSO
sandboxctl(8)