:: Version 3.2.0 ::

Background tasks

In order to operate properly, iTop maintenance operations and asynchronous tasks must be executed on a regular basis. In order to ease the installation, all the background tasks have been grouped to be launched from a single file: webservices/cron.php

The following features rely on the activation of cron.php

  • Notification when a ticket reach a threshold (TTO/TTR) will not happen without this web service to be called. (Task:CheckStopWatchThresholds)
  • Check ticket SLA. Tickets reaching the limits will be passed into Escalation TTO/TTR states.
  • Automated Backups.
  • Automatic deletion of useless attachments and in-line images, created during an object creation or edition which was cancelled (Task: InlineImageGC which runs hourly)
  • Asynchronous emails. By default, this option is disabled. To enable it, set 'email_asynchronous' to 1 in the configuration file (Task: ExecAsyncTask)
  • Many Extensions rely on this cron as well, for exemple: Ticket Creation from Email, Approval Automation, Communication to Customers,…

All background tasks are processed sequentially by cron.php.
The script will loops until the max time (see cron_max_execution_time in the parameters) is elapsed. This max time is useful to avoid memory leaks.

Warning : a background task launched just before max time is elapsed could consume more than the remaining time to finish. In such conditions the script can last more than cron_max_execution_time duration !

When cron.php script is launched a lock is set, and will be released on script exit. So any concurrent run on the same iTop instance will exit immediately if the lock is set.

In consequence, we recommend to :
  • Set cron_max_execution_time parameter not to low, something like 600 (10 minutes) : this will allow to process correctly tasks that take a long time to finish
  • Launch the cron.php script every minute for example

Scheduling on Windows

Use schedtask.exe or the 'at' command to schedule cron.php to run every 5 minutes.

schtasks.exe /create /sc minute /mo 1 /tn "iTop CRON" /tr "\"C:\www\itop\webservices\cron.cmd\""

Note: Replace C:\www\itop with your path to the iTop directory

Scheduling on Linux

Edit the crontab to execute the script every 1 minutes:

 */1 * * * * www-data /usr/bin/php /var/www/html/itop/webservices/cron.php --param_file=/etc/itop-cron.params >>/var/log/itop-cron.log 2>&1

Note: Replace /var/www/html/itop with your path to the iTop directory

Do not run cron.php using root user! You must launch the command with the same user that is used by the web server running iTop.

Scheduling from the web

The page cron.php can also be executed through the web server. This is useful if you don't have access to the system (for example on shared hosting systems). In such a case you can rely on a web cron service to run it for you. But the frequency and execution times will probably be restricted compared to a natively scheduled job.

Arguments

Argument Description Defaut value
param_file Path to the parameters file
auth_user User login - CLI mode only, if no parameters file is used -
auth_pwd User password - CLI mode only, if no parameters file is used -
verbose if set to 1, more information will be given, use this for troubleshooting. Beware: since the process runs continuously in background, the log files tend to become big pretty quickly. Don't set this options to 1 for a long period of time. 0
status_only (New in iTop 2.0.1) if set to 1, a status about the scheduled tasks is displayed and the process stops immediatly (can be launched in parallel to the normal execution of cron.php). 0

Parameter file

Since the arguments passed to cron.php on the command line are visible to other users on the system, a recommended practice is to move all the sensitive parameters away from the command line. This is the purpose of the “parameter file”.

The argument param_file can be used with most of the REST/CLI web services. By convention, the cron.php service searches for a parameter file name « cron.params » to read its parameters from.

  • A parameter file contains key/value pairs.
  • Comments start with a # (any character found after `#` will be ignored)
The iTop package contains a file named cron.distrib that can be used as a template for creating your own parameter file.

Example:

itop-cron.params
# This is a parameter file
#
# If a parameter is given both in the file and in the arguments,
# then the value given as argument is retained
#
 
# Authentication
auth_user = qwertyuiop
auth_pwd = ded!catedL0g1n
Make sure that the parameter file is not reachable from the web! Either move it to a directory outside of the web server's scope (for example /etc/itop/ on Linux systems would be a good location) or make a special exclusion rule in your webserver's configuration. Only the process that runs cron.php from the command line should be able to access this file.

Settings

Those settings are configured into the main iTop configuration file: “itop-config.php”

Setting Description Defaut value
cron_max_execution_time Duration (seconds) of the cron.php script : if exceeded the script will exit even if there are remaining tasks to process. Must be shorter than php max_execution_time setting (note than when using CLI, this is set to 0 by default which means unlimited). If cron.php is ran via web, it must be shorter than the web server response timeout. 600
cron_sleep Duration (seconds) before cron.php checks again if something must be done 2
email_asynchronous If set to 1, the emails are sent off line, which requires cron.php to be activated. Exception: some features like the email test utility will force the serialized mode 0

Allowed users

Only administrators are allowed to execute cron.php.

Troubleshooting

When a task is no more running, there are a few things to know:

What is the cron.php doing?

  • The cron.php program, when started, ask for Tasks which implements this php interface, and log them in the table priv_backgroundtask.
  • The entries present in this table depends on the iTop installed extensions.
  • priv_backgroundtask contains multiple information for each task, such as:
    • when it run for the last time,
    • when is the next run supposed to start,
    • what is the average execution time of this task,
    • Is the task currently active or paused as requested by an administrator (field status)
  • The cron.php program, look for tasks which are active and next run is passed,
    • execute the tasks one after the other asking each task to stop its execution after cron_max_execution_time. The task would of course stops at a point where it makes sense, for example for Mail To Ticket Automation, it could stop between the processing of 2 received Mails.
    • ask the task when should be the next run and store that info in the table,
  • Then it checks if it-self was started more than cron_max_execution_time, if yes it commits suicide (this is because a never ending process usually consumes memory which is not totally freed)
  • else it waits for cron_sleep second before checking the table again for tasks ready to be executed.

What can be done when...

A task seems to never be executed:

When a particular task encounters an issue which make it hangs in an infinite loop, cron.php might be stopped by the php max_execution_time (usually not when running in CLI); in all cases the tasks which are following that one will never be executed. In the following run of cron.php, as the tasks are always executed in the same order, the same issue will probably occur again. For identifying the faulty task, you should paused one after the other the tasks which you suspect to have this issue by setting their status in the priv_backgroundtask table and see if you have stopped the faulty one. Such situation is usually due to a bug of the extension bringing that task, the task facing an unplanned situation.

The logfile should be monitored to generate alarm to get advanced notice of such issue.

3_2_0/admin/cron.txt · Last modified: 2024/09/10 10:25 (external edit)
Back to top
Contact us