SANDBOXCTL(8)

NAME
sandboxctl - creates and manages chroot-based sandboxed environments

SYNOPSIS
sandboxctl [-c config_name] [-o variable=value] [-v] config [variable]
sandboxctl [-c config_name] [-o variable=value] [-v] create
sandboxctl [-c config_name] [-o variable=value] [-v] destroy
sandboxctl [-c config_name] [-o variable=value] [-v] mount
sandboxctl [-c config_name] [-o variable=value] [-v] run ...
sandboxctl [-c config_name] [-o variable=value] [-v] shell
sandboxctl [-c config_name] [-o variable=value] [-v] unmount [-f] [-f]

DESCRIPTION
sandboxctl creates and manages chroot-based sandboxed environments in a portable manner based on a simple configuration file.

Because chroot(8) is a privileged system command, you must be root to use this tool.

The following options apply to all commands:

-c config_name
    Specifies the configuration file to use. The format of the file is described in sandboxctl.conf(5).

    If config_name includes any directory separator (i.e. one or more slashes) or the ‘.conf’ suffix, then the argument specifies the path to the configuration file.

    If config_name is a bare name without any directory components nor the extension, then the configuration file will be looked up in /usr/pkg/etc/sandboxctl/<config_name>.conf. The file must exist in this case.

-o variable=value
    Applies an override to the loaded configuration.

    The variable part of the argument must be any of the recognized configuration variables described in sandboxctl.conf(5). The value, if not empty, specifies the value to set the configuration variable to. If value is empty, then the configuration variable is unset.

-v  Enables verbose mode.

  Sandbox types
Sandboxes managed by sandboxctl have a type associated to them. The sandbox type etermines how the sandbox is constructed and provides all the operating system-specific knowledge to do so. There is one or more sandbox types for every supported operating system.

For example: on NetBSD, there is sandbox type to create an environment that reproduces the host system, and there also is a sandbox type that recreates a fresh installation of the system. Sandbox types are described in sandboxctl.conf(5) along with all the settings that affect their behavior.

  Sandbox lifecycle
A sandbox managed by sandboxctl goes through these operations:

1.  Configure: The administrator sets up a configuration file to define the sandbox. See sandboxctl.conf(5) for details.

2.  Create: Prepares the on-disk layout but does not mount any file systems within it (which may be necessary depending on the type of the sandbox). This operation happens once per sandbox. The sandbox is created with the ‘create’ command.

3.  Enter or mount: Performs preparatory work to enter the sandbox, such as mounting any filesystems within the sandbox or copying dynamic files. This operation happens every time the sandbox is entered for interaction as described in the next command. The sandbox can be manually mounted with the ‘mount’ command, which is provided for convenience, but you should rarely do this by hand.

4.  Interact: The administator can issue commands within the sandbox via the ‘run’ command or open a shell via the ‘shell’ command.

5.  Leave or unmount: Performs the opposite work of the Enter step. In particular, unmounts any file systems that may be left mounted in the sandbox. This operation happens every time the interaction step completes. The sandbox can be manually unmounted with the ‘unmount’ command, which is provided for convenience, but you should rarely do this by hand.

6.  Destroy: The on-disk layout for the sandbox is completely removed. This operation cannot be executed while there is any active sandbox in the Interact stage. The sandbox is destroyed with the ‘destroy’ command.

Note that sandbox entry/leave operations are reference-counted and can happen concurrently. sandboxctl ensures that only the first concurrent interaction step executes the entry step and that only the last concurrent interaction step executes the leave step. If you get a warning saying that the sandbox is still in use, it means that another instance of sandboxctl is still running for the given sandbox.

  The config command
The config command dumps the loaded configuration to the standard output. The format of the output is not a script, so it cannot be fed back into sandboxctl. The purpose of this command is to aid in debugging the configuration of the tool, particularly for those configuration files that use shell logic to determine the value of the variables they define.

A single variable name can be provided as an argument to this command, in which case the value of this variable is printed verbatim to the standard output. It is an error if the given variable is not defined.

Note that the output of this command varies across operating systems depending on the sandbox types available.

  The create command
Creates the sandbox, which must not yet exist.

  The destroy command
Destroys the sandbox, which must exist and must not be active. In other words, no other sandboxctl instance may be running the ‘run’ or ‘shell’ commmands.

  The mount command
Mounts sandbox-specific file systems and prepares the sandbox to be usable. This command is only provided for completeness and convenience; you should not need to use it by hand: the ‘run’ and ‘shell’ commands take care of automatically doing this for you at startup time.

  The run command
Executes a given command inside the sandbox. The sandbox must exist. This operation always mounts the sandbox before running the command and unmounts it after completion. The shell is forced to /bin/sh and the environment is completely cleaned except for a few key variables.

  The shell command
Executes an interactive shell inside the sandbox. The sandbox must exist. This operation always mounts the sandbox before running the shell and unmounts it after completion. The shell is forced to /bin/sh and the environment is completely cleaned except for a few key variables.

  The unmount command
Unmounts sandbox-specific file systems. This command is only provided for completeness and convenience; you should not need to use it by hand: the ‘run’ and ‘shell’ commands take care of automatically doing this for you at exit time.

The following options apply to the ‘unmount’ command:

-f  If given once, causes sandboxctl to disregard any existing locks on the sandbox and unmounts the file systems within it. If given twice, causes the unmount operations to also be forced; see the -f flag in umount(8) for more details about what this involves.

    You can use this flag to clean up the state of the sandbox if it ever becomes inconsistent, which is a (rare) possibility because sandboxctl cannot make hard guarantees on the consistency of the sandbox in case of failures during a regular unmount.

    Warning: You should only use this flag if you are certain that no other concurrent instances of sandboxctl are still running for the given sandbox.

FILES

/usr/pkg/etc/sandboxctl/
    Directory containing all system-wide configuration files.

/usr/pkg/etc/sandboxctl/default.conf
    Default configuration file to load if the user does not specify any other.

SEE ALSO
sandboxctl.conf(5), chroot(8)

AUTHORS
The sandboxctl utility was developed by Julio Merino <jmmv@google.com>.