Module exec

Description
Data Types
Function Index
Function Details

OS shell command runner.

Version: /bin/sh: line 1: git: command not found

Behaviours: gen_server.

Authors: Serge Aleynikov (saleyn@gmail.com).

Description

OS shell command runner. It communicates with a separate C++ port process exec-port spawned by this module, which is responsible for starting, killing, listing, terminating, and notifying of state changes.

The port program serves as a middle-man between the OS and the virtual machine to carry out OS-specific low-level process control. The Erlang/C++ protocol is described in the exec.cpp file. The exec application can execute tasks by impersonating as a different effective user. This impersonation can be accomplished in one of the following two ways (assuming that the emulator is not running as root:

Having the user account running the erlang emulator added to the /etc/sudoers file, so that it can execute exec-port task as root. (Preferred option)
Setting root ownership on exec-port, and setting the SUID bit: chown root:root exec-port; chmod 4755 exec-port. (This option is discouraged as it's less secure).

In either of these two cases, exec:start_link/2 must be started with options [root, {user, User}, {limit_users, Users}], so that exec-port process will not actually run as root but will switch to the effective User, and set the kernel capabilities so that it's able to start processes as other effective users given in the Users list and adjust process priorities.

Though, in the initial design, exec prohibited such use, upon user requests a feature was added (in order to support docker deployment and CI testing) to be able to execute exec-port as root without switching the effective user to anying other than root. To accomplish this use the following options to start exec: [root, {user, "root"}, {limit_users, ["root"]}].

At exit the port program makes its best effort to perform clean shutdown of all child OS processes. Every started OS process is linked to a spawned light-weight Erlang process returned by the run/2, run_link/2 command. The application ensures that termination of spawned OsPid leads to termination of the associated Erlang Pid, and vice versa.

Data Types

cmd()

cmd() = binary() | string() | [string()]

Command to be executed. If specified as a string, the specified command will be executed through the shell. The current shell is obtained from environment variable SHELL. This can be useful if you are using Erlang primarily for the enhanced control flow it offers over most system shells and still want convenient access to other shell features such as shell pipes, filename wildcards, environment variable expansion, and expansion of ~ to a user's home directory. All command arguments must be properly escaped including whitespace and shell metacharacters.

Any part of the command string can contain unicode characters.

Warning:

shell injection

shell

   1> {ok, Filename} = io:read("Enter filename: ").
   Enter filename: "non_existent; rm -rf / #".
   {ok, "non_existent; rm -rf / #"}
   2> exec(Filename, []) % Argh!!! This is not good!

When command is given in the form of a list of strings, it is passed to execve(3) library call directly without involving the shell process, so the list of strings represents the program to be executed given with a full path, followed by the list of arguments (e.g. ["/bin/echo", "ok"]). In this case all shell-based features are disabled and there's no shell injection vulnerability.

cmd_option()

cmd_option() = monitor | sync | link | {executable, string() | binary()} | {cd, WorkDir::string() | binary()} | {env, [string() | clear | {Name::string() | binary(), Val::string() | binary() | false}, ...]} | {kill, KillCmd::string() | binary()} | {kill_timeout, Sec::non_neg_integer()} | kill_group | {group, GID::string() | binary() | integer()} | {user, RunAsUser::string() | binary()} | {nice, Priority::integer()} | {success_exit_code, ExitCode::integer()} | stdin | {stdin, null | close | string() | binary()} | stdout | stderr | {stdout, stderr | output_dev_opt()} | {stderr, stdout | output_dev_opt()} | {stdout | stderr, string() | binary(), [output_file_opt()]} | {winsz, {Rows::non_neg_integer(), Cols::non_neg_integer()}} | pty | {pty, pty_opts()} | pty_echo | debug | {debug, integer()}

Command options:

monitor: Set up a monitor for the spawned process. The monitor is not a standard erlang:montior/2 function call, but it's emulated by ensuring that the monitoring process receives notification in the form: {'DOWN', OsPid::integer(), process, Pid::pid(), Reason}. If the Reason is normal, then process exited with status 0, otherwise there was an error. If the Reason is {status, Status} the returned Status can be decoded with status/1 to determine the exit code of the process and if it was killed by signal.
sync: Block the caller until the OS command exits
{executable, Executable::string()}: Specifies a replacement program to execute. It is very seldom needed. When the port program executes a child process using execve(3) call, the call takes the following arguments: (Executable, Args, Env). When Cmd argument passed to the run/2 function is specified as the list of strings, the executable replaces the first parameter in the call, and the original args provided in the Cmd parameter are passed as as the second parameter. Most programs treat the program specified by args as the command name, which can then be different from the program actually executed. On Unix, the args name becomes the display name for the executable in utilities such as ps.
If Cmd argument passed to the run/2 function is given as a string, on Unix the Executable specifies a replacement shell for the default /bin/sh.
{cd, WorkDir}: Working directory
{env, Env :: [{Name,Value}|string()|clear]}: List of "VAR=VALUE" environment variables or list of {Name, Value} tuples or strings (like "NAME=VALUE") or clear. clear will clear environment of a spawned child OS process (so that it doesn't inherit parent's environment). If Value is false then the Var env variable is unset.
{kill, KillCmd}: This command will be used for killing the process. After a 5-sec timeout if the process is still alive, it'll be killed with SIGKILL. The kill command will have a CHILD_PID environment variable set to the pid of the process it is expected to kill. If the kill option is not specified, by default first the command is sent a SIGTERM signal, followed by SIGKILL after a default timeout.
{kill_timeout, Sec::integer()}: Number of seconds to wait after issuing a SIGTERM or executing the custom kill command (if specified) before killing the process with the SIGKILL signal
kill_group: At process exit kill the whole process group associated with this pid. The process group is obtained by the call to getpgid(3).
{group, GID}: Sets the effective group ID of the spawned process. The value 0 means to create a new group ID equal to the OS pid of the process.
{user, RunAsUser}: When exec-port was compiled with capability (Linux) support enabled and has a suid bit set, it's capable of running commands with a different RunAsUser effective user. Passing "root" value of RunAsUser is prohibited.
{success_exit_code, IntExitCode}: On success use IntExitCode return value instead of default 0.
{nice, Priority}: Set process priority between -20 and 20. Note that negative values can be specified only when exec-port is started with a root suid bit set.
stdin | {stdin, null | close | Filename}: Enable communication with an OS process via its stdin. The input to the process is sent by exec:send(OsPid, Data). When specified as a tuple, null means redirection from /dev/null, close means to close stdin stream, and Filename means to take input from file.
stdout: Same as {stdout, self()}.
stderr: Same as {stderr, self()}.
{stdout, output_device()}: Redirect process's standard output stream
{stderr, output_device()}: Redirect process's standard error stream
{stdout | stderr, Filename::string(), [output_dev_opt()]}: Redirect process's stdout/stderr stream to file
{winsz, {Rows, Cols}}: Set the (psudo) terminal's dimensions of rows and columns
pty: Use pseudo terminal for the process's stdin, stdout and stderr
pty_echo: Allow the pty to run in echo mode, disabled by default
debug: Same as {debug, 1}
{debug, Level::integer()}: Enable debug printing in port program for this command

cmd_options()

cmd_options() = [cmd_option()]

exec_option()

exec_option() = debug | {debug, integer()} | root | {root, boolean()} | verbose | {args, [string() | binary(), ...]} | {alarm, non_neg_integer()} | {user, string() | binary()} | {limit_users, [string() | binary(), ...]} | {portexe, string() | binary()} | {env, [{string() | binary(), string() | binary() | false}, ...]}

Options passed to the exec process at startup. They can be specified in the sys.config file for the erlexec application to customize application startup.

debug: Same as {debug, 1}
{debug, Level}: Enable port-programs debug trace at Level.
verbose: Enable verbose prints of the Erlang process.
root | {root, Boolean}: Allow running child processes as root.
{args, Args}: Append Args to the port command.
{alarm, Secs}: Give Secs deadline for the port program to clean up child pids before exiting
{user, User}: When the port program was compiled with capability (Linux) support enabled, and is owned by root with a a suid bit set, this option must be specified so that upon startup the port program is running under the effective user different from root. This is a security measure that will also prevent the port program to execute root commands.
{limit_users, LimitUsers}: Limit execution of external commands to these set of users. This option is only valid when the port program is owned by root.
{portexe, Exe}: Provide an alternative location of the port program. This option is useful when this application is stored on NFS and the port program needs to be copied locally so that root suid bit can be set.
{env, Env}: Extend environment of the port program by using Env specification. Env should be a list of tuples {Name, Val}, where Name is the name of an environment variable, and Val is the value it is to have in the spawned port process. If Val is false, then the Name environment variable is unset.

exec_options()

exec_options() = [exec_option()]

osgid()

osgid() = integer()

Representation of OS group ID.

ospid()

ospid() = integer()

Representation of OS process ID.

output_dev_opt()

Output device option:

null: Suppress output.
close: Close file descriptor for writing.
print: A debugging convenience device that prints the output to the console shell
Filename: Save output to file by overwriting it.
pid(): Redirect output to this pid.
fun((Stream, OsPid, Data) -> none()): Execute this callback on receiving output data

output_file_opt()

output_file_opt() = append | {mode, Mode::integer()}

Defines file opening attributes:

append: Open the file in append mode
{mode, Mode}: File creation access mode specified in base 8 (e.g. 8#0644)

pty_opt()

pty_opt() = {tty_char(), byte()} | {tty_mode(), boolean() | 0 | 1} | {tty_speed(), non_neg_integer()}

Pty options, see:

{tty_char(), Byte}: A special character with value from 0 to 255
{tty_mode(), Enable}: Enable/disable a tty mode
{tty_speed(), Speed}: Specify input or output baud rate. Provided for completeness. Not useful for pseudo terminals.

pty_opts()

pty_opts() = [pty_opt()]

List of pty options.

tty_char()

tty_mode()

tty_speed()

tty_speed() = tty_op_ispeed | tty_op_ospeed

Function Index

debug/1	Set debug level of the port process.
kill/2	Send a `Signal` to a child `Pid`, `OsPid` or an Erlang `Port`.
manage/2
ospid/1	Get `OsPid` of the given Erlang `Pid`.
pid/1	Get `Pid` of the given `OsPid`.
pty_opts/2	Set the pty terminal options of the OS process identified by `OsPid`.
run/2
run/3	Run an external program.
run_link/2
run_link/3	Run an external program and link to the OsPid.
send/2	Send `Data` to stdin of the OS process identified by `OsPid`.
setpgid/2	Change group ID of a given `OsPid` to `Gid`.
signal/1	Convert a signal number to atom.
signal_to_int/1
start/0	Start of an external program manager without supervision.
start/1
start_link/1	Supervised start an external program manager.
status/1	Decode the program's exit_status.
stop/1	Terminate a managed `Pid`, `OsPid`, or `Port` process.
stop_and_wait/2	Terminate a managed `Pid`, `OsPid`, or `Port` process, like `stop/1`, and wait for it to exit.
which_children/0	Get a list of children managed by port program.
winsz/3	Set the pty terminal `Rows` and `Cols` of the OS process identified by `OsPid`.

Function Details

debug/1

debug(Level::integer()) -> {ok, OldLevel::integer()} | {error, timeout}

Set debug level of the port process.

kill/2

kill(Pid::pid() | ospid(), Signal::atom() | integer()) -> ok | {error, any()}

Send a Signal to a child Pid, OsPid or an Erlang Port.

manage/2

manage(Port, Options) -> any()

ospid/1

ospid(Pid::pid()) -> ospid() | {error, Reason::any()}

Get OsPid of the given Erlang Pid. The Pid must be created previously by running the run/2 or run_link/2 commands.

pid/1

pid(OsPid::ospid()) -> pid() | undefined | {error, timeout}

Get Pid of the given OsPid. The OsPid must be created previously by running the run/2 or run_link/2 commands.

pty_opts/2

pty_opts(OsPid::ospid() | pid(), Opts::pty_opts()) -> ok | {error, Reason::any()}

Set the pty terminal options of the OS process identified by OsPid.

The process must have been created with the pty option.

run/2

run(Exe, Options) -> any()

run/3

run(Exe::cmd(), Options::cmd_options(), Timeout::integer()) -> {ok, pid(), ospid()} | {ok, [{stdout | stderr, [binary()]}]} | {error, any()}

Run an external program. OsPid is the OS process identifier of the new process. If sync is specified in Options the return value is {ok, Status} where Status is OS process exit status. The Status can be decoded with status/1 to determine the process's exit code and if it was killed by signal.

run_link/2

run_link(Exe, Options) -> any()

run_link/3

run_link(Exe::cmd(), Options::cmd_options(), Timeout::integer()) -> {ok, pid(), ospid()} | {ok, [{stdout | stderr, [binary()]}]} | {error, any()}

Equivalent to run / 2.

Run an external program and link to the OsPid. If OsPid exits, the calling process will be killed or if it's trapping exits, it'll get {'EXIT', OsPid, Status} message. If the calling process dies the OsPid will be killed. The Status can be decoded with status/1 to determine the process's exit code and if it was killed by signal.

send/2

send(OsPid::ospid() | pid(), Data::binary() | eof) -> ok

Send Data to stdin of the OS process identified by OsPid.

Sending eof instead of binary Data causes close of stdin of the corresponding process. Data sent to closed stdin is ignored.

setpgid/2

setpgid(OsPid::ospid(), Gid::osgid()) -> ok | {error, any()}

Change group ID of a given OsPid to Gid.

signal/1

signal(Num::integer()) -> atom() | integer()

Convert a signal number to atom

signal_to_int/1

signal_to_int(X1) -> any()

start/0

start() -> {ok, pid()} | {error, any()}

Equivalent to start_link / 1.

Start of an external program manager without supervision. Note that the port program requires SHELL environment variable to be set.

start/1

start(Options::exec_options()) -> {ok, pid()} | {error, any()}

start_link/1

start_link(Options::exec_options()) -> {ok, pid()} | {error, any()}

Supervised start an external program manager. Note that the port program requires SHELL environment variable to be set.

status/1

status(Status::integer()) -> {status, ExitStatus::integer()} | {signal, Signal::integer() | atom(), Core::boolean()}

Decode the program's exit_status. If the program exited by signal the function returns {signal, Signal, Core} where the Signal is the signal number or atom, and Core indicates if the core file was generated.

stop/1

stop(Pid::pid() | ospid() | port()) -> ok | {error, any()}

Terminate a managed Pid, OsPid, or Port process. The OS process is terminated gracefully. If it was given a {kill, Cmd} option at startup, that command is executed and a timer is started. If the program doesn't exit, then the default termination is performed. Default termination implies sending a SIGTERM command followed by SIGKILL in 5 seconds, if the program doesn't get killed.

The process must have been created with the pty option.

Generated by EDoc