Running CMS Bitrix Agents via cron

Agents in 1C-Bitrix are a built-in mechanism for automating recurring tasks: sending emails, search indexing, cache cleanup, event processing, and much more.

By default, agents run on hit (every time a user visits the site). This works well for small projects, but under high load or with many agents, it significantly slows down the site and increases server load.

Switching agents to cron is the recommended approach for all projects on shared hosting, VPS, and dedicated servers. It offloads the site and ensures stable task execution on schedule.

Step 1: Disable agents on hit

Connect to the server via SSH and run these commands in PHP console (or edit /bitrix/.settings.php):

COption::SetOptionString("main", "agents_use_crontab", "N");
echo COption::GetOptionString("main", "agents_use_crontab", "N");

COption::SetOptionString("main", "check_agents", "N");
echo COption::GetOptionString("main", "check_agents", "Y");

Expected output: NN

Step 2: Edit dbconn.php

Open the file /bitrix/php_interface/dbconn.php:

nano /bitrix/php_interface/dbconn.php

Remove (or comment out) these lines:

define("BX_CRONTAB_SUPPORT", true);
define("BX_CRONTAB", true);

Add instead:

if (!(defined("CHK_EVENT") && CHK_EVENT === true)) {
    define("BX_CRONTAB_SUPPORT", true);
}

Save the file (Ctrl+O → Enter → Ctrl+X).

Step 3: Create the cron script file

Create the file /bitrix/php_interface/cron_events.php:

nano /bitrix/php_interface/cron_events.php

Insert the following code:

$_SERVER["DOCUMENT_ROOT"] = realpath(dirname(__FILE__) . "/../..");
$DOCUMENT_ROOT = $_SERVER["DOCUMENT_ROOT"];

define("NO_KEEP_STATISTIC", true);
define("NOT_CHECK_PERMISSIONS", true);
define("CHK_EVENT", true);

require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/modules/main/include/prolog_before.php");

@set_time_limit(0);
@ignore_user_abort(true);

CAgent::CheckAgents();

define("BX_CRONTAB_SUPPORT", true);
define("BX_CRONTAB", true);

CEvent::CheckEvents();

if (CModule::IncludeModule("subscribe")) {
    $cPosting = new CPosting;
    $cPosting->AutoSend();
}

Save the file (Ctrl+O → Enter → Ctrl+X).

Step 4: Add the cron job

Open crontab:

crontab -e

Add this line (run every 5 minutes):

*/5 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/php_interface/cron_events.php

Replace /home/bitrix/www/ with the actual path to your site. Save and exit.

Step 5: Optimize email sending (optional)

To speed up email event processing, increase the number of messages processed per run (recommended 20–50):

COption::SetOptionString("main", "mail_event_bulk", "20");
echo COption::GetOptionString("main", "mail_event_bulk", "5");

Useful notes

• If a new cron run starts before the previous one finishes — agents won't duplicate (they are locked during execution).
• For projects with heavy email volume, set mail_event_bulk higher (e.g., 100) and run cron more frequently (every 1–2 minutes).
• Check logs in /bitrix/.logs/ or cron.log to confirm cron is running and agents are executing.