Process Management in FreePBX is handled by a central module. This module takes care of managing long running/background processes such as:
- Zulu
- UCP Node
- XMPP (Let's Chat)
- Rest Apps
- Queue Callback (VQPlus)
There are several core methods when using the Process Management module. Keep in mind that the Process Management module uses the nodejs library called PM2 https://github.com/Unitech/pm2
This does not mean your app has to be written in Node. In fact PM2 supports various formats for starting background processes.
There a five main methods to using PM2 in your application
Start
This method starts your application in the background. Your name must be unique! We suggest using your module's rawname or your module's rawname with a suffix
/**
* Start a process
* @method start
* @param string $name The name of the application
* @param string $process The process to run
* @return mixed Output of getStatus
*/
public function start($name, $process) {
FreePBX::PM2()->start("modulerawname-suffix","path to script");
Your application will be started in the directory where your script lives
Stop
To stop an application you need to simply provide the application name you declared in the start method.
Stopping an application does not remove it from the application list. Instead it puts the application in a "stopped" (non running) state. To remove an application from the list of applications you will need to use the delete method.
/**
* Stop process
* @method stop
* @param string $name The application name
*/
public function stop($name) {
FreePBX::PM2()->stop("modulerawname");
Delete
This will stop AND delete an application from the list of applications (retrieved from listProcesses).
This method should be used when uninstalling your module
/**
* Delete process
* @method delete
* @param string $name The application name
*/
public function delete($name) {
FreePBX::PM2()->delete("modulerawname");
Restart
This method will restart your application which will also increase the restart counter. This can only be used if the script was first started with the start method
/**
* Restart process
* @method restart
* @param string $name The application name
*/
public function restart($name) {
FreePBX::PM2()->restart("modulerawname");
getStatus
This will get the status of the application by name. If the application is unknown it will return false
/**
* Get status of a process
* @method getStatus
* @param string $name The process name
* @return mixed Return array of data if known or false if unknown
*/
public function getStatus($name) {
$out = FreePBX::PM2()->getStatus("ucpnode");
print_r($out);
Array
(
[pid] => 10048
[name] => ucpnode
[pm2_env] => Array
(
[exec_mode] => fork_mode
[log_date_format] => YYYY-MM-DD HH:mm Z
[watch] =>
[treekill] => 1
[autorestart] => 1
[automation] => 1
[pmx] => 1
[vizion] => 1
[merge_logs] => 1
[name] => ucpnode
[node_args] => Array
(
)
[pm_exec_path] => /usr/src/freepbx/ucpnode/node/index.js
[env] => Array
(
[PM2_USAGE] => CLI
[_] => /usr/src/freepbx/pm2/node/node_modules/pm2/bin/pm2
[G_BROKEN_FILENAMES] => 1
[LESSOPEN] => ||/usr/bin/lesspipe.sh %s
[CVS_RSH] => ssh
[QTLIB] => /usr/lib64/qt-3.3/lib
[LOGNAME] => asterisk
[HOME] => /home/asterisk
[SHLVL] => 1
[HISTCONTROL] => ignoredups
[NODE_PATH] => /home/asterisk/.node/lib/node_modules:
[LANG] => en_US.UTF-8
[PWD] => /usr/src/freepbx/ucpnode/node
[PATH] => /home/asterisk/.node/bin:/usr/lib64/qt-3.3/bin:/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin
[MAIL] => /var/spool/mail/asterisk
[PM2_HOME] => /home/asterisk/.pm2
[ASTLOGDIR] => /var/log/asterisk
[USER] => asterisk
[QTINC] => /usr/lib64/qt-3.3/include
[QTDIR] => /usr/lib64/qt-3.3
[HISTSIZE] => 1000
[TERM] => xterm-256color
[SHELL] => /bin/bash
[HOSTNAME] => localhost
[MANPATH] => /home/asterisk/.node/share/man:
[ucpnode] => Array
(
)
)
[pm_cwd] => /usr/src/freepbx/ucpnode/node
[exec_interpreter] => node
[instances] => 1
[pm_out_log_path] => /var/log/asterisk/ucpnode_out.log
[pm_err_log_path] => /var/log/asterisk/ucpnode_err.log
[pm_pid_path] => /home/asterisk/.pm2/pids/ucpnode-3.pid
[km_link] =>
[NODE_APP_INSTANCE] => 0
[vizion_running] =>
[PM2_USAGE] => CLI
[_] => /usr/src/freepbx/pm2/node/node_modules/pm2/bin/pm2
[G_BROKEN_FILENAMES] => 1
[LESSOPEN] => ||/usr/bin/lesspipe.sh %s
[CVS_RSH] => ssh
[QTLIB] => /usr/lib64/qt-3.3/lib
[LOGNAME] => asterisk
[HOME] => /home/asterisk
[SHLVL] => 1
[HISTCONTROL] => ignoredups
[NODE_PATH] => /home/asterisk/.node/lib/node_modules:
[LANG] => en_US.UTF-8
[PWD] => /usr/src/freepbx/ucpnode/node
[PATH] => /home/asterisk/.node/bin:/usr/lib64/qt-3.3/bin:/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin
[MAIL] => /var/spool/mail/asterisk
[PM2_HOME] => /home/asterisk/.pm2
[ASTLOGDIR] => /var/log/asterisk
[USER] => asterisk
[QTINC] => /usr/lib64/qt-3.3/include
[QTDIR] => /usr/lib64/qt-3.3
[HISTSIZE] => 1000
[TERM] => xterm-256color
[SHELL] => /bin/bash
[HOSTNAME] => localhost
[MANPATH] => /home/asterisk/.node/share/man:
[status] => online
[pm_uptime] => 1491954852420
[axm_actions] => Array
(
)
[axm_monitor] => Array
(
[Loop delay] => Array
(
[alert] => Array
(
)
[agg_type] => avg
[value] => 0.66ms
)
)
[axm_options] => Array
(
[default_actions] => 1
[transactions] =>
[http] =>
[http_latency] => 200
[http_code] => 500
[ignore_routes] => Array
(
)
[profiling] => 1
[errors] => 1
[alert_enabled] => 1
[custom_probes] => 1
[network] =>
[ports] =>
[ignoreFilter] => Array
(
[method] => Array
(
[0] => OPTIONS
)
[url] => Array
(
)
)
[excludedHooks] => Array
(
)
[module_conf] => Array
(
)
[module_name] => ucpnode
[module_version] => 2.4.4
[pmx_version] => 1.1.0
[error] => 1
)
[axm_dynamic] => Array
(
)
[created_at] => 1491954852420
[pm_id] => 3
[restart_time] => 0
[unstable_restarts] => 0
[versioning] =>
[node_version] => 0.12.18
[created_at_human_diff] => 6 hours, 20 minutes
)
[pm_id] => 3
[monit] => Array
(
[memory] => 77012992
[cpu] => 0
[human_memory] => 73.45MB
)
)
listProcesses
List Processes is similar to getStatus except it will return a list of all processes/applications currently under the control of PM2
/**
* Get all processes
* @method listProcesses
* @return array Return array of data
*/
public function listProcesses() {
FreePBX::PM2()->listProcesses();