Configuring Cron Jobs and Agents in 1C-Bitrix

Configuring Cron Jobs and Agents in 1C-Bitrix

An agent in 1C-Bitrix is a PHP function scheduled to run at defined intervals. When agents operate in "hit mode" — triggered on each HTTP request — tasks on low-traffic projects may go unexecuted for hours. Why? Because a hit-based agent waits for the next visitor. If no one visits at night, scheduled mailings are not sent, search indexes are not updated, and stock levels are not synchronized.

How Agents Work in Bitrix

Agents are stored in the b_agent table. Each record contains: the agent function name, the execution interval (PERIOD), the next scheduled execution time (NEXT_EXEC), and an active flag.

Two operating modes:

Hit mode. On every HTTP request, Bitrix checks the b_agent table for agents where NEXT_EXEC <= NOW(). If found, they are executed within the current HTTP request. Advantage: requires no server configuration. Disadvantage: no guaranteed execution time, increases page response time, and on low-traffic sites agents run with significant delays.

Cron mode. Agents are launched via the system cron independently of HTTP traffic. The script /bitrix/modules/main/tools/agent_exec.php is called by crontab, checks b_agent, and runs overdue agents. This is the correct approach for any production project.

Configuring Cron for Agents

Standard crontab entry to run agents every minute:

* * * * * /usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/agent_exec.php > /dev/null 2>&1

Additionally — to ensure execution of agents tied to precise timing (e.g., scheduled email sending):

*/5 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/event_exec.php > /dev/null 2>&1

event_exec.php is the mail event queue handler. Without it, email sending from the queue depends on hits.

In Bitrix settings, the mode must be switched: "Settings → Module Settings → Main Module → Use cron for agents" — enable. After this, agents will no longer run on hits.

Custom Cron Tasks

In addition to Bitrix agents, a production server often requires custom cron tasks:

Scheduled cache clearing. If cache is not invalidated automatically:

0 4 * * * /usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/clear_cache.php > /dev/null 2>&1

1C import. If the exchange is scheduled rather than push-based — the CommerceML import launch script:

0 */2 * * * /usr/bin/php -f /home/bitrix/www/local/php_interface/import_1c.php >> /var/log/bitrix_import.log 2>&1

Search reindexing.

0 2 * * 0 /usr/bin/php -f /home/bitrix/www/bitrix/modules/search/tools/index.php > /dev/null 2>&1

Agent Monitoring

To check agent status:

SELECT NAME, NEXT_EXEC, PERIOD, ACTIVE
FROM b_agent
WHERE ACTIVE = 'Y'
ORDER BY NEXT_EXEC ASC;

Agents with NEXT_EXEC several hours in the past indicate that cron is not running or the agent crashed with an error. Agent errors are written to the log: "Settings → Event Log" (event type AGENT).

Timeline

Setting up cron for agents and basic tasks — 2–4 hours: diagnosing the current mode, configuring crontab, switching the mode in Bitrix, verifying execution. For complex cron scenarios with monitoring — 1–2 business days.