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.
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 executeexec-port
task asroot
. (Preferred option) - Setting
root
ownership onexec-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!
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 with arguments.
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()]} |
pty | 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 theReason
isnormal
, then process exited with status0
, otherwise there was an error. If the Reason is{status, Status}
the returnedStatus
can be decoded withstatus/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
Ifexecve(3)
call, the call takes the following arguments:(Executable, Args, Env)
. WhenCmd
argument passed to therun/2
function is specified as the list of strings, the executable replaces the first parameter in the call, and the original args provided in theCmd
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 asps
.Cmd
argument passed to therun/2
function is given as a string, on Unix theExecutable
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). IfValue
isfalse
then theVar
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 thekill
option is not specified, by default first the command is sent aSIGTERM
signal, followed bySIGKILL
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 theSIGKILL
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 byexec:send(OsPid, Data)
. When specified as a tuple,null
means redirection from/dev/null
,close
means to closestdin
stream, andFilename
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
- 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 isfalse
, then theName
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.
- 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)
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 . |
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.
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
.
setpgid/2
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.
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
Set the pty terminal Rows
and Cols
of the OS process identified by OsPid
.
pty
option.