Version: 1.9
Behaviours: gen_server.
Authors: Serge Aleynikov (saleyn@gmail.com).
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
:
/etc/sudoers
file, so that it can execute exec-port
task as root
. (Preferred option)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"]}]
.
cmd() = binary() | string() | [string()]
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()}
cmd_options() = [cmd_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}, ...]}
exec_options() = [exec_option()]
osgid() = integer()
Representation of OS group ID.
ospid() = integer()
Representation of OS process ID.
output_dev_opt() = null | close | print | string() | pid() | fun((stdout | stderr, integer(), binary()) -> none())
output_file_opt() = append | {mode, Mode::integer()}
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 . |
debug(Level::integer()) -> {ok, OldLevel::integer()} | {error, timeout}
Set debug level of the port process.
kill(Pid::pid() | ospid(), Signal::atom() | integer()) -> ok | {error, any()}
Send a Signal
to a child Pid
, OsPid
or an Erlang Port
.
manage(Port, Options) -> any()
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(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(Exe, Options) -> any()
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(Exe, Options) -> any()
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(OsPid::ospid() | pid(), Data::binary() | eof) -> ok
Send Data
to stdin of the OS process identified by OsPid
.
Change group ID of a given OsPid
to Gid
.
signal(Num::integer()) -> atom() | integer()
Convert a signal number to atom
signal_to_int(X1) -> any()
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(Options::exec_options()) -> {ok, pid()} | {error, any()}
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(Status::integer()) -> {status, ExitStatus::integer()} | {signal, Singnal::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(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(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() -> [ospid(), ...]
Get a list of children managed by port program.
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.
Generated by EDoc