@spec pipe!(
  Enumerable.t(),
  String.t()
  | [String.t(), ...]
  | {arg0 :: String.t(), argv :: [String.t(), ...]},
  module() | [phase()] | {module(), [phase()]},
  task: [config()],
  init: [config()],
  ops: [config()],
  onerror: [config()],
  onexit: [config()]
) :: Enumerable.t()

Pipe data into the standard input of a system process.

Input is a stream of binaries. Empty binaries are ignored.

See stream!/3 for arguments.

Examples

iex> Stream.unfold(1000, fn 0 -> nil; n -> {"#{n}\n", n - 1} end)
...> |> Stdio.pipe!("grep --line-buffered 442")
...> |> Enum.to_list()
[stdout: "442\n", exit_status: 0]

iex> Stdio.stream!("echo test; kill $$")
iex> |> Stream.transform(<<>>, &Stdio.Stream.stdout_to_stderr/2)
iex> |> Stdio.pipe!("sed -u 's/t/_/g'")
iex> |> Enum.to_list()
[stdout: "_es_\n", exit_status: 0]

iex> [<<>>, <<"a">>, <<>>] |> Stdio.pipe!("cat") |> Enum.to_list()
[stdout: "a", exit_status: 0]

@spec reap(Stdio.ProcessTree.t(), atom()) :: :ok

Terminate descendents of a supervisor process.

@spec reap(Stdio.ProcessTree.t(), :prx.pid_t(), atom()) :: :ok

Terminate descendents of a process.

reap signals subprocesses of a process identified by PID.

Background and daemonized subprocesses will also be terminated if supported by the platform.

Request system supervisor runs as root.

Some system calls require the process to be UID 0. These calls typically are operations like mounting filesystems or creating new namespaces (excluding user namespaces such as Stdio.Rootless) or putting a process into a jail(2) or a chroot(2).

Warning

Enabling privileges is a global setting: all system supervisor processes will run as UID 0.

Setuid Binary

Probably the simplest method for production use is adding the setuid bit to the prx binary (see :prx_drv.progname/0):

• create a group with privileges to run the supervisor (optional)

    # example: create an elixir group
    groupadd elixir

• find the location of the binary

    :prx_drv.progname()

• set the setuid bit

    sudo chown root:elixir /path/to/priv/prx
    sudo chmod 4750 /path/to/priv/prx

Using a Setuid Exec Chain

prx can be configured to use a setuid helper program such as sudo(8) or doas(1).

Stdio.setuid/0 is a noop if the prx binary is setuid.

Before launching any supervisors, run:

 Stdio.setuid()

sudo(8)

    $ sudo visudo
    elixiruser ALL = NOPASSWD: /path/to/prx/priv/prx
    Defaults!/path/to/prx/priv/prx !requiretty

doas(8)

    permit nopass setenv { ENV PS1 SSH_AUTH_SOCK } :elixirgroup

Errors

shell process exited with reason: {:error, {:error, :eagain}}

Check prx is executable:

$ ./deps/prx/priv/prx -h
prx 0.40.5
usage: prx -c <path> [<options>]

error attempting to fork subprocess: insufficient permissions (eperm)

Verify prx can be run using sudo:

$ sudo ./deps/prx/priv/prx -h
prx 0.40.5
usage: prx -c <path> [<options>]

@spec stream!(
  String.t()
  | [String.t(), ...]
  | {arg0 :: String.t(), argv :: [String.t(), ...]},
  module() | [phase()] | {module(), [phase()]},
  task: [config()],
  init: [config()],
  ops: [config()],
  onexit: [config()],
  onerror: [config()]
) :: Enumerable.t()

Stream standard I/O from system processes.

command

Commands are strings interpreted by /bin/sh or list of strings (an argv) passed directly to execve(2).

Warning

When using an argv, $PATH is not consulted. The path to the executable must be provided as the first argument.

behaviour

The process behaviour can be customized by passing in:

• a module implementing the callbacks

• a keyword list with functions of type phase/0

• a tuple consisting of a module and a list of phase/0 functions to override the module callbacks

config

For configuration options, see config/0.

Examples

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

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

iex> Stdio.stream!("ip --oneline -4 addr show dev lo", Stdio.Container) |> Enum.to_list()
[exit_status: 0]

iex> Stdio.stream!("ip --oneline -4 addr show dev lo", Stdio.Container, net: :host) |> Enum.to_list()
[
    stdout: "1: lo    inet 127.0.0.1/8 scope host lo\\       valid_lft forever preferred_lft forever\n",
    exit_status: 0
]

iex> Stdio.stream!("pwd", {Stdio.Process, ops: fn _ -> [{:chdir, ["/tmp"]}] end}) |> Enum.to_list()
[stdout: "/tmp\n", exit_status: 0]

@spec supervise(
  :prx.task(),
  :shutdown
  | :noshutdown
  | :noreap
  | (init :: :prx.task(), pipeline :: pipeline(), state :: map() -> any()),
  [:prx.call()] | {:allow, [:prx.call()]} | {:deny, [:prx.call()]}
) :: {:ok, t()} | {:error, :prx.posix()}

Configure a task to be a system process supervisor.

The task:

• becomes an init process (dependent on platform)

• sets the process name to supervise

• enables flow control for child stdout/stderr

• sets the shutdown/reaper behaviour

• terminates child processes if beam exits

• restricts the task to a limited set of calls required for supervision

@spec supervisor(
  :shutdown
  | :noshutdown
  | :noreap
  | (init :: :prx.task(), pipeline :: pipeline(), state :: map() -> any()),
  [:prx.call()] | {:allow, [:prx.call()]} | {:deny, [:prx.call()]}
) :: {:ok, t()} | {:error, :prx.posix()}

Create a supervisor task

Returns a Stdio.t/0 configured to act as a system process supervisor.

@spec with_supervisor(module(), t()) :: Keyword.t()

Use a previously created supervisor process.

The supervisor is not shutdown when the stream exits.

Examples

iex> {:ok, supervisor} = Stdio.supervisor(:noshutdown)
iex> Stdio.stream!("echo test", Stdio.with_supervisor(Stdio.Process, supervisor)) |> Enum.to_list()
[stdout: "test\n", exit_status: 0]
iex> Stdio.stream!("echo test", Stdio.with_supervisor(Stdio.Process, supervisor)) |> Enum.to_list()
[stdout: "test\n", exit_status: 0]
iex> :prx.stop(supervisor.init)

graph LR
    B([beam]) --> S[Supervise]
    S -.-> I0[[sh]]
    S --> I1[[sh]]
    I0 -.-> C0[[echo test]]
    I1 --> C1[[echo test]]