webCOMAND

webCOMAND Docs
Admin Guide CLI System Task

System Task CLI

webCOMAND is primarily run and accessed from a web browser.  However, some processes are launched and run in the background, even when there are no web browser requests.  There are a few CLI applications that are useful for managing and monitoring background processes.

  • Daemon - The primary COMAND background process, which will start and monitor other background processes, such as the web socket server.
  • Processes - Displays a list of System Tasks running in the background and their status.
  • Count - Displays a simple count of System Tasks running in the background.
  • Run - Run a Scheduled Task from the CLI.

Daemon

The daemon is an important application that runs in the background on a computer or server to:

  • Manage Scheduled Tasks - Start and monitor scheduled tasks.  For example, backups can be scheduled to run automatically each night.  If the daemon is not running, the backup will not be started.

  • Update the webCOMAND UI - Broker communication (using Web Sockets) between multiple webCOMAND users and browser windows to efficiently update the interface with repository changes, notifications and task progress.

Web Sockets

If enabled, the daemon will run a Web Socket Server process that communicates web browsers accessing webCOMAND over a "live connection" to efficiently update the webCOMAND interface with repository changes, notifications and task progress.

Web Socket ErrorIf a web browser cannot establish a Web Socket connection to the Web Socket Server, a yellow warning badge will appear in the lower-right of the user profile icon in the upper-right of the webCOMAND interface.  This indicates that there is a problem with either the socket server, the selected port, or the web server configuration.

Apache Web Server Configuration

To configure Apache web server to work with Web Sockets, add the following lines to the top level configuration file (i.e. in httpd.conf, not within a <VirtualHost> or <Directory>).

ProxyRequests Off
ProxyPass /com_webcomandwebsocket/ ws://localhost:8084
CacheDisable https://<account>.webcomand.com/com_webcomand/websocket/

A quick note on each line:

  • ProxyRequests is being set to off here, this may already have been off though so it may be redundant. This can be off and ProxyPass will still work.
  • ProxyPass redirects a connection request from the browser to the web socket server, listening on the configured port.  So, when a client requests to connect to wss://<account>.webcomand.com/com_webcomand/websocket/, this forwards the request to the webCOMAND Web Socket Server process listening on port 8084.
  • CacheDisable prevents the browser from caching the connected/disconnected state in the event that the Web Socket server goes on/offline. I may still need to tweak this a bit though.

    NOTE: CacheDisable requires mod_cache.so, so make sure to:
    LoadModule cache_module modules/mod_cache.so

Enable Web Socket Server

Once the web server is configured to proxy Web Socket requests, the webCOMAND Web Socket Server can be enabled and configured with the following lines in config/com_webcomand/framework.php.

/**
 * Web Socket Server Configuration
 */

/**
 * If defined and TRUE, this will direct web clients to attempt to
 * connect to the Web Socket Server for updates. If FALSE, webCOMAND
 * client instances will remain disconnected and not poll the socket
 * server for a connection (which keeps the browser console free of
 * errors). This will not impact whether the server side web socket
 * server will run, which is controlled by its Scheduled Task and the
 * COMAND Daemon.
 */
'web_socket_enabled' => true,

/**
 * The web socket host that the socket server will bind to.
 * 'localhost' is generally correct.
 */
'web_socket_host' => 'localhost',

/**
 * The web socket port that the socket server will bind to.
 * This must match what is defined in the Apache configuration for
 * incoming connections.
 */
'web_socket_port' => 8084,

/**
 * The buffer size, in bytes, that the socket server will use when
 * reading from incoming requests.
 */
'web_socket_buffer' => 2048,

/**
 * The web socket server will verify incoming connection requests
 * against logged in and authenticated users. This is the fully
 * qualified URL to verify them against, which should match the URL
 * to the CMS.
 */
'web_socket_auth_url' => 'https://<account>.webcomand.com',

Start the Daemon

To start the Daemon, from the command-line prompt:

php comand.php io_comand_systemtask daemon start

Help for the Daemon

To get help, from the command-line prompt:

php comand.php io_comand_systemtask daemon help

Stop the Daemon

All running scheduled tasks will complete on their own and no new tasks will be started.

To stop the Daemon, from the command-line prompt:

php comand.php io_comand_systemtask daemon stop

Cancel the Daemon

Stops the daemon and cancels all of its running scheduled tasks (all will gracefully cancel and exit at some point during execution).

php comand.php io_comand_systemtask daemon cancel

Restart the Daemon

To stop and then immediately start the Daemon, from the command-line prompt:

php comand.php io_comand_systemtask daemon restart

Kill the Daemon

To kill the Daemon when it is no longer responding, from the command-line prompt:

php comand.php io_comand_systemtask daemon kill

Get Daemon Status

To get the status of the Daemon, including whether or not it is running and it's process ID, from the command-line prompt:

php comand.php io_comand_systemtask daemon status

The resulting output lists the daemon PID and any scheduled and running tasks, with task broken into the following columns.

  • OID - The System Task OID, which you can access in webCOMAND.
  • Title - Human readable task title assigned when the System Task was started.
  • Status - Status of the System Task:
    • Running - Actively running.
    • Scheduled - Scheduled to run at a future time listed in the Time/Since column.
  • PID - Operating System Process ID, as it will appear in the standard  "ps" command output, if the task is currently running.
  • Time/Since - If Status is Schedule, the Date and Time the task will be started next.  If Status is Running, Date and time the process was started in (YYYY-MM-DD HH:MM:SS) format.

Example Output

PID: 12345
Scheduled Tasks:
OID       Title              Status     PID   Time/Since
-------------------------------------------------------------------------
1945655   Web Socket Server  Running    1899  2017-04-27 17:02:02 (since)
1955858   Send Candidate CVs Scheduled  ---   2017-04-29 14:47:53 (sched)

Check & Restart Daemon

To check if the Daemon is running, and start it if it is not, from the command-line prompt:

php comand.php io_comand_systemtask daemon check

When the Daemon is not running and a start is required, an email will be sent to the email address(es) configured for EmailBCC in config/server.php.

These commands will be shortened to: comand daemon [start | stop | status | check ]

Monitor and Restart Daemon

Since the Daemon is so important to the function of webCOMAND and scheduled tasks, it is a good idea to ensure it is running and has not terminated or crashed.

One way to do this on Linux is to set up a "cron job" to check and restart the Daemon if it is not running.  In CentOS 7+, simply create a file named something like "daemon_check" in /etc/cron.d/ with the following line:

* * * * * root /usr/bin/php comand.php io_comand_systemtask daemon check

That will check to ensure the Daemon is running each minute, and restart if necessary.

Count

The following command will list the number of background System Tasks COMAND is running, which includes both scheduled tasks managed by the COMAND daemon (like nightly publishes and the web socket server) and publishes started manually through webCOMAND by clicking "Publish".

php comand.php io_comand_systemtask count

The resulting output looks like:

There is currently 1 running SystemTask

Processes

List Background COMAND Processes

The following command will show all background System Tasks COMAND is running, which includes both scheduled tasks managed by the COMAND daemon (like nightly publishes and the web socket server) and publishes started manually through webCOMAND by clicking "Publish".

php comand.php io_comand_systemtask ps

The resulting output lists one task per line with each line broken into the following columns.

  • OID - The System Task OID, which you can access in webCOMAND.
  • Title - Human readable task title assigned when the System Task was started.
  • WC User - The webCOMAND User the System Task is running as, which means it will be limited to that users authorizations.  admin is the default super user.
  • PID - Operating System Process ID, as it will appear in "ps" command output.
  • VMem - Virtual Memory used by the system task, as it will appear in "ps" command output.
  • %Mem - Percent of total virtual memory available, as it will appear in "ps" command output.
  • %CPU - Percent of total CPU utilization, as it will appear in the standard "ps" command output.
  • Since - Time the process was started and how long it has been running, in (HH:MM:SS) format.

Example Output

OID       Title               WC User   PID     VMem    %Mem  %CPU  Since
--------------------------------------------------------------------------------------------------
1955858   Send Candidate CVs  admin     30797   455.6M  7     2.3   2017-04-29 14:47:53 (00:03:40)
1945655   Web Socket Server   admin     18999   366.8M  1.3   0     2017-04-27 17:02:02 (45:49:31)

Run

Run a scheduled task, as if it's scheduled time has come up.  When run from the CLI it leaves STDOUT open and echos SystemLog.  --task can be the OID of a ScheduledTask, SystemTask or Runnable (run).

php comand.php io_comand_systemtask run --task <Scheduled Task OID>

Page last updated .

Copyright © 2013-2024, COMAND Systems, Inc.