| Overview |  |
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
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 | Manage an existing external process. |
| ospid/1 | Get OsPid of the given Erlang Pid. |
| pid/1 | Get Pid of the given OsPid. |
| run/2 | Run an external program. |
| run_link/2 | 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. |
| 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::integer()) -> ok | {error, any()}
Send a Signal to a child Pid, OsPid or an Erlang Port.
manage(Pid::ospid() | port(), Options::cmd_options()) -> {ok, pid(), ospid()} | {error, any()}
Manage an existing external process. OsPid is the OS process
identifier of the external OS process or an Erlang Port that
would be managed by erlexec.
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::cmd(), Options::cmd_options()) -> {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::cmd(), Options::cmd_options()) -> {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
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