MuonTrap (muontrap v2.0.0-rc.0)

Copy Markdown View Source

MuonTrap protects you from lost and out of control OS processes.

You can use it as a System.cmd/3 replacement or to pull OS processes into an Erlang supervision tree via MuonTrap.Daemon. Either way, if the Erlang process that runs the command dies, then the OS processes will die as well.

MuonTrap tries very hard to kill OS processes so that remnants don't hang around the system when your Erlang code thinks they should be gone. MuonTrap can use the Linux kernel's cgroup feature to contain the child process and all of its children. From there, you can limit CPU and memory and other resources to the process group.

MuonTrap does not require cgroups but keep in mind that OS processes can escape. It is, however, still an improvement over System.cmd/3 which does not have a mechanism for dealing it OS processes that do not monitor their stdin for when to close.

For more information, see the documentation for MuonTrap.cmd/3 and MuonTrap.Daemon

Configuring cgroups

MuonTrap uses cgroup v2 (the unified hierarchy at /sys/fs/cgroup). It does not support cgroup v1. v2 is the default on every mainstream distribution since 2021–2022 (Ubuntu 22.04+, Debian 11+, RHEL 9+, recent Nerves systems).

Two pieces of setup are needed at some point before MuonTrap uses a cgroup — there's no need to do them at boot, just before the first cgroup-using call:

  1. The controllers you want (e.g., cpu, memory, pids) must be enabled in the root cgroup's cgroup.subtree_control. On systemd hosts this is managed for you via slices. Otherwise:

    echo +cpu +memory +pids | sudo tee /sys/fs/cgroup/cgroup.subtree_control

  2. A parent cgroup directory you can write to. MuonTrap creates a sub-cgroup underneath it for each spawned process. For example:

    sudo mkdir -p /sys/fs/cgroup/muontrap
sudo chown -R $(whoami) /sys/fs/cgroup/muontrap

On Nerves, where the BEAM runs as root, both steps can run from your application's start callback (or any helper module) the first time you need cgroups. Pass the parent's name (here, "muontrap") as :cgroup_base.

See the project README for worked examples (capping CPU and memory, fork-bomb protection, sandboxing with bwrap) and pointers to the kernel cgroup v2 docs.

Summary

Functions

cmd(command, args, opts \\ [])

Executes a command like System.cmd/3 via the muontrap wrapper.

muontrap_path()

Return the absolute path to the muontrap executable.

Functions

cmd(command, args, opts \\ [])

@spec cmd(binary(), [binary()], keyword()) ::
  {Collectable.t(), exit_status :: non_neg_integer() | :timeout}

Executes a command like System.cmd/3 via the muontrap wrapper.

Options

  • :cgroup - a map of cgroup v2 settings to apply (e.g. %{cpu_weight: 50, memory_max: 500_000_000, pids_max: 256}). Keys mirror the cgroup v2 interface file names with . replaced by _. Controllers are enabled automatically based on which keys are present. See MuonTrap.Daemon.cgroup_config/1 for the supported keys and value shapes; pass the map it returns to start a new daemon with the same settings.
  • :cgroup_base - create a temporary path under the specified cgroup path
  • :cgroup_path - explicitly specify a path to use. Use :cgroup_base, unless you must control the path.
  • :delay_to_sigkill - milliseconds before sending a SIGKILL to a child process if it doesn't exit with a SIGTERM (default 500 ms)
  • :uid - run the command using the specified uid or username. When a username is given, supplementary groups are loaded from /etc/group. When a numeric uid is given, supplementary groups inherit from the parent. See :groups to override.
  • :gid - run the command using the specified gid or group
  • :groups - explicit list of supplementary group ids or names (as integers or binaries). Pass [] to drop all supplementary groups. Overrides default behavior depending on username :uid setting.
  • :timeout - milliseconds to wait for the command to complete. If the command does not exit before the timeout, the return value will contain the output up to that point and :timeout as the exit status. The child process will be sent SIGTERM

The following System.cmd/3 options are also available:

  • :into - injects the result into the given collectable, defaults to ""
  • :cd - the directory to run the command in
  • :env - an enumerable of tuples containing environment key-value as binary
  • :arg0 - sets the command arg0
  • :stderr_to_stdout - redirects stderr to stdout when true
  • :capture_stderr_only - when true, captures only stderr and ignores stdout (useful for capturing errors while ignoring normal output)
  • :parallelism - when true, the VM will schedule port tasks to improve parallelism in the system. If set to false, the VM will try to perform commands immediately, improving latency at the expense of parallelism. The default can be set on system startup by passing the "+spp" argument to --erl.

Examples

Run a command:

iex> MuonTrap.cmd("echo", ["hello"])
{"hello\n", 0}

The next examples only run on Linux. To try this out, create a parent cgroup and ensure cpu/memory are enabled in the root subtree (see the Configuring cgroups section above):

sudo mkdir -p /sys/fs/cgroup/muontrap
sudo chown -R $(whoami) /sys/fs/cgroup/muontrap

Run a command, but limit memory so severely that it can't allocate (for demo purposes, obviously):

iex-donttest> MuonTrap.cmd("echo", ["hello"], cgroup_path: "muontrap/test", cgroup: %{memory_max: 1_048_576})
{"", 1}

Run a command with a timeout:

iex> MuonTrap.cmd("/bin/sh", ["-c", "echo start && sleep 10 && echo end"], timeout: 100) {"start\n", :timeout}

muontrap_path()

Return the absolute path to the muontrap executable.

Call this if you want to invoke the muontrap port binary manually.