package bwrap

  1. Overview
  2. Docs
package bwrap
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module BwrapSource

This module launches processes isolated from the main environment using sandboxing technology.

Sourcetype conf

Sandbox configuration.

You can create one using the functions below. Example: conf() |> mount "/usr".

Sourceval bare : conf

Configuration with all sharing disabled and an empty environment.

Sourceval conf : ?uid:int -> ?gid:int -> unit -> conf

Create a configuration with all sharing disabled, mounting in read-only mode /bin, /usr, /lib, /lib32 and /lib64 (if they exist) and on tmpfs /tmp, /run and /var. The hostname is set to "OCaml".

Sourceval share_user : bool -> conf -> conf
Sourceval share_ipc : bool -> conf -> conf
Sourceval share_pid : bool -> conf -> conf
Sourceval share_net : bool -> conf -> conf
Sourceval share_uts : bool -> conf -> conf
Sourceval share_cgroup : bool -> conf -> conf
Sourceval uid : int -> conf -> conf

uid c id use a custom user id in the sandbox. Automatically implies share_user c false. If id < 0, unset it.

Sourceval gid : int -> conf -> conf

gid c id use a custom group id in the sandbox. Automatically implies share_user c false. If id < 0, unset it.

Sourceval hostname : string -> conf -> conf

hostname c h use the custom hostname h in the sandbox. Automatically implies share_uts c false. If h = "", unset it.

Sourceval setenv : string -> string -> conf -> conf

setenv c var v add the variable var with value v to the environment of the process.

Sourceval unsetenv : string -> conf -> conf

unsetenv c var remove the environment variable var.

Sourceval mount : ?dev:bool -> ?src:string -> ?rw:bool -> string -> conf -> conf

mount c src dest mount the host path src on dest in the sandbox. The mounts are applied in the order they are set, the latter ones being able undo what the previous ones did. Any missing parent directories that are required to create a specified destination are automatically created as needed.

  • parameter src

    if not provided, it defaults to dest.

  • parameter dev

    If true, allow device access.

  • parameter rw

    If true, mount in read and write (default, mount read-only).

Example: let c = mount c "/a" "/a" in mount c ~rw:true "/a/b" "/a/b"

Sourceval remount_ro : string -> conf -> conf

remount_ro c dest remount the path dest as readonly. It works only on the specified mount point, without changing any other mount point under the specified path.

Sourceval proc : string -> conf -> conf

proc c dest mount procfs on dest. Example: proc c "/proc".

Sourceval dev : string -> conf -> conf

dev c dest mount new devtmpfs on dest. Example: dev c "/dev".

Sourceval tmpfs : string -> conf -> conf

tmpfs c dest mount new tmpfs on dest. Example: tmpfs c "/var" or tmpfs c "/tmp".

Sourceval mqueue : string -> conf -> conf

mqueue c dest mount new mqueue on dest.

Sourceval dir : string -> conf -> conf

dir c dest create directory dest in the sandbox.

symlink c src dest create a symlink at dest with target src.

  • parameter src

    If not provided, it defaults to dest.

Sourceval chdir : string -> conf -> conf

chdir dir change directory to dir in the sandboxed environment.

Sourceval new_session : bool -> conf -> conf

new_session c b when b is true, create a new terminal session for the sandbox (calls setsid()). This disconnects the sandbox from the controlling terminal which means the sandbox can't for instance inject input into the terminal.

Note: In a general sandbox, if you don't use new_session c true, it is recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise the application can feed keyboard input to the terminal.

Sourceval die_with_parent : bool -> conf -> conf

die_with_parent c b: when b is true, ensures that the sandboxed command dies when the program using this library dies. Kills (SIGKILL) all sandbox processes in sequence from parent to child including the sandboxed command process when the process using this library dies.

Launch sandboxed processes

Sourceval open_process_in : conf -> string -> string list -> in_channel

open_process_in c cmd args runs the command cmd with arguments args in a sandbox in parallel with the program. The standard output of the program can be read on the returned channel.

Sourceval close_process_in : in_channel -> Unix.process_status
Sourceval open_process_out : conf -> string -> string list -> out_channel

open_process_out c cmd args runs the command cmd with arguments args in a sandbox in parallel with the program.

Sourceval close_process_out : out_channel -> Unix.process_status
Sourceval open_process : conf -> string -> string list -> in_channel * out_channel

open_process c cmd args runs the command cmd with arguments args in a sandbox in parallel with the program.

Sourceval open_process_full : conf -> string -> string list -> in_channel * out_channel * in_channel

open_process_full c cmd args runs the command cmd with arguments args in a sandbox in parallel with the program. The result is a triple of channels connected respectively to the standard output, standard input, and standard error of the command.