# `Stdio.Jail`
[🔗](https://github.com/msantos/stdio/blob/v0.4.6/lib/stdio/jail.ex#L1)

Jailed FreeBSD processes

Runs a process in a
[jail(2)](https://www.freebsd.org/cgi/man.cgi?jail(2)).

## Privileges

To use this behaviour, the system process supervisor must have root
privileges. These privileges are dropped before running the command.

See `Stdio.setuid/0`.

### sysctl(8)

[sysctl(8)](https://www.freebsd.org/cgi/man.cgi?sysctl(8)) settings
control the behaviour of the jail. For example, to allow ping/traceroute
from the jail:

    sysctl security.jail.allow_raw_sockets=1

See [jail(8)](https://www.freebsd.org/cgi/man.cgi?jail(8)).

## Operations

See `t:Stdio.config/0` for configuration options.

* creates a new session

* sets the process priority [:priority=0]

* puts the process into a `jail(2)`

* sets resource limits [:rlimit=coredumps disabled]

* sets additional groups [:groups=additional groups removed]

* drops privileges to the value of `uid` and `gid` or a high UID system
  user [:uid/:gid=65536-131071]

* disables the capability to elevate privileges [:setuid=false]

> #### Warning {: .warning}
> The generated UID/GID may overlap with existing users.

## Examples

    iex> Stdio.stream!(["./echo", "test"], Stdio.Jail, path: "/rescue")
    ...> |> Enum.to_list()
    [stdout: "test\n", exit_status: 0]

    iex> Stdio.stream!(
    ...> ["sh", "-c", "export PATH=/; ping -c 1 127.0.0.1 | head -1"],
    ...> Stdio.Jail,
    ...> uid: 0, path: "/rescue", setuid: true, net: :host
    ...>) |> Enum.to_list()
    [stdout: "PING 127.0.0.1 (127.0.0.1): 56 data bytes\n", exit_status: 0]

---

*Consult [api-reference.md](api-reference.md) for complete listing*
