Module exec

Version: 1.9

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.

• 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"]}].

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: Executing shell commands that incorporate unsanitized input from an untrusted source makes a program vulnerable to shell injection, a serious security flaw which can result in arbitrary command execution. For this reason, the use of shell is strongly discouraged in cases where the command string is constructed from external input:

   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!

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()]} |
    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

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_dev_opt() = 
    null | close | print |
    string() |
    pid() |
    fun((stdout | stderr, integer(), binary()) -> none())

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:

• https://man7.org/linux/man-pages/man3/termios.3.html
• https://datatracker.ietf.org/doc/html/rfc4254#section-8

{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_char() = 
    vintr | vquit | verase | vkill | veof | veol | veol2 |
    vstart | vstop | vsusp | vdsusp | vreprint | vwerase |
    vlnext | vflush | vswtch | vstatus | vdiscard

tty_mode()

tty_mode() = 
    ignpar | parmrk | inpck | istrip | inlcr | igncr | icrnl |
    xcase | iuclc | ixon | ixany | ixoff | imaxbel | iutf8 |
    isig | icanon | echo | echoe | echok | echonl | noflsh |
    tostop | iexten | echoctl | echoke | pendin | opost | olcuc |
    onlcr | ocrnl | onocr | onlret | cs7 | cs8 | parenb | parodd

tty_speed()

tty_speed() = tty_op_ispeed | tty_op_ospeed

Function Index

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

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.

run/2

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/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.

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

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.

stop_and_wait/2

stop_and_wait(Port :: pid() | ospid() | port(),
              Timeout :: integer()) ->
                 term() | {error, any()}

Terminate a managed Pid, OsPid, or Port process, like stop/1, and wait for it to exit.

which_children/0

which_children() -> [ospid(), ...]

Get a list of children managed by port program.

winsz/3

winsz(OsPid :: ospid() | pid(),
      Rows :: integer(),
      Cols :: integer()) ->
         ok | {error, Reason :: any()}

Set the pty terminal Rows and Cols of the OS process identified by OsPid.