The Task Queue System in cPanel & WHM

Events in cPanel & WHM often cause one or more services to restart. For example, adding a subdomain causes a restart of Apache and the nameserver daemon.

On busy servers, such restart requests can degrade the quality of service.

To handle these requests, cPanel & WHM includes a task queueing and processing system. Subsystems that are aware of the task queue submit their requests to it, rather than directly issuing the restart (or other request).

A benefit of the task queue system is that multiple instances of an outstanding request are handled as a single action. This improves server response time.

Task Queue-Aware Functions

The system queues requests made by the following functions in cPanel & WHM:

• Apache-related functions in Tweak Settings (WHM)
• Create a New Account (WHM)
• Modify Account Properties (WHM)
• Terminate an Account (WHM)
• Upgrade/Downgrade an Account (WHM)
• Change Site's IP Address (WHM)
• Copy an account from another server (Transfers area in WHM)
• Add or remove an addon domain (Addon Domains area in cPanel)
• Create or remove a subdomain (Subdomains area in cPanel)
• Create or remove a parked domain (Parked Domains area in cPanel)

How Task Queueing Works

There are two aspects of the task queueing system:

1. the queueing mechanism
2. the queue processor

The Queueing Mechanism

Queueing of tasks is handled via the /usr/local/cpanel/bin/servers_queue script, which has the following usage:

/usr/local/cpanel/bin/servers_queue [queue $command] [unqueue $task_id]

queue $command

The queue parameter requires a command string as an argument. The command string should be quoted. For example:

root@example [~]# /usr/local/cpanel/bin/servers_queue queue 'apache_restart' 
Id: TQ:TaskQueue:4

Only commands known to the task queueing system are accepted. If you provide an unknown command, the system returns an error. For example:

root@example [~]# /usr/local/cpanel/bin/servers_queue queue 'buildapacheconf' 
ERROR: No known processor for 'buildapacheconf'. at /usr/local/lib/perl5/site_perl/5.8.8/

unqueue $task_id

The unqueue parameter requires a task ID number. This number is output when you queue a task. You can also find it by examining the /var/cpanel/taskqueue/servers_queue.yaml file.

For example:

root@pxe [~]# /usr/local/cpanel/bin/servers_queue queue 'apache_restart' 
Id: TQ:TaskQueue:8 
root@pxe [~]# /usr/local/cpanel/bin/servers_queue unqueue TQ:TaskQueue:8 
1 tasks unqueued

The Queue Processor

Queued tasks are stored in YAML files in /var/cpanel/taskqueue.

The task queue is processed periodically by the queueprocd daemon. This daemon resides in /usr/local/cpanel/libexec and is prompted by the cPanel startup process. You can manage it using /usr/local/cpanel/scripts/restartsrv_queueprocd. This daemon is monitored by chkservd.